docs: add comprehensive documentation for today's work
Technical Documentation: - docs/development/architecture-fixes-2026-01.md: Complete guide to all architecture validation fixes (62 -> 0 errors) User Guides: - docs/guides/email-templates.md: How-to guide for vendors and admins to use the email template customization system Implementation Docs: - docs/implementation/password-reset-implementation.md: Technical documentation for the password reset feature - Updated email-templates-architecture.md with EmailTemplateService documentation and related links Bugfix: - Fixed TemplateListItem Pydantic model to match service output (languages vs available_languages field name) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
476
docs/development/architecture-fixes-2026-01.md
Normal file
476
docs/development/architecture-fixes-2026-01.md
Normal file
@@ -0,0 +1,476 @@
|
||||
# Architecture Validation Fixes (January 2026)
|
||||
|
||||
## Overview
|
||||
|
||||
This document details the architecture validation fixes implemented to achieve **zero architecture errors** in the codebase. The fixes addressed violations across API endpoints, service layer, JavaScript files, and templates.
|
||||
|
||||
**Before:** 62 errors
|
||||
**After:** 0 errors
|
||||
|
||||
---
|
||||
|
||||
## Summary of Changes
|
||||
|
||||
| Category | Files Changed | Violations Fixed |
|
||||
|----------|---------------|------------------|
|
||||
| API Layer | 3 files | 12 violations |
|
||||
| Service Layer | 2 files | Business logic moved |
|
||||
| Exceptions | 1 file | 2 new exceptions |
|
||||
| JavaScript | 2 files | 8 violations |
|
||||
| Templates | 2 files | 2 violations |
|
||||
| Tooling | 1 file | 1 false positive fix |
|
||||
|
||||
---
|
||||
|
||||
## 1. API Layer Fixes
|
||||
|
||||
### 1.1 Vendor Settings API
|
||||
|
||||
**File:** `app/api/v1/vendor/settings.py`
|
||||
|
||||
**Problem:** 10 HTTPException raises directly in endpoint functions (API-003 violations).
|
||||
|
||||
**Solution:** Moved validation to Pydantic field validators.
|
||||
|
||||
#### Before (Inline Validation)
|
||||
```python
|
||||
@router.put("/letzshop")
|
||||
def update_letzshop_settings(letzshop_config: LetzshopFeedSettingsUpdate, ...):
|
||||
update_data = letzshop_config.model_dump(exclude_unset=True)
|
||||
|
||||
# Validate tax rate - VIOLATION: HTTPException in endpoint
|
||||
if "letzshop_default_tax_rate" in update_data:
|
||||
if update_data["letzshop_default_tax_rate"] not in VALID_TAX_RATES:
|
||||
raise HTTPException(status_code=400, detail="Invalid tax rate")
|
||||
# ... more inline validation
|
||||
```
|
||||
|
||||
#### After (Pydantic Validators)
|
||||
```python
|
||||
# Constants moved above model
|
||||
VALID_TAX_RATES = [0, 3, 8, 14, 17]
|
||||
VALID_DELIVERY_METHODS = ["nationwide", "package_delivery", "self_collect"]
|
||||
|
||||
class LetzshopFeedSettingsUpdate(BaseModel):
|
||||
letzshop_default_tax_rate: int | None = Field(None)
|
||||
letzshop_boost_sort: str | None = Field(None)
|
||||
letzshop_delivery_method: str | None = Field(None)
|
||||
letzshop_preorder_days: int | None = Field(None, ge=0) # Built-in validation
|
||||
|
||||
@field_validator("letzshop_default_tax_rate")
|
||||
@classmethod
|
||||
def validate_tax_rate(cls, v: int | None) -> int | None:
|
||||
if v is not None and v not in VALID_TAX_RATES:
|
||||
raise ValueError(f"Invalid tax rate. Must be one of: {VALID_TAX_RATES}")
|
||||
return v
|
||||
|
||||
@field_validator("letzshop_delivery_method")
|
||||
@classmethod
|
||||
def validate_delivery_method(cls, v: str | None) -> str | None:
|
||||
if v is not None:
|
||||
methods = v.split(",")
|
||||
for method in methods:
|
||||
if method.strip() not in VALID_DELIVERY_METHODS:
|
||||
raise ValueError(f"Invalid delivery method")
|
||||
return v
|
||||
|
||||
@field_validator("letzshop_boost_sort")
|
||||
@classmethod
|
||||
def validate_boost_sort(cls, v: str | None) -> str | None:
|
||||
if v is not None:
|
||||
try:
|
||||
boost = float(v)
|
||||
if boost < 0.0 or boost > 10.0:
|
||||
raise ValueError("Boost sort must be between 0.0 and 10.0")
|
||||
except ValueError as e:
|
||||
if "could not convert" in str(e).lower():
|
||||
raise ValueError("Boost sort must be a valid number")
|
||||
raise
|
||||
return v
|
||||
|
||||
# Endpoint now clean
|
||||
@router.put("/letzshop")
|
||||
def update_letzshop_settings(letzshop_config: LetzshopFeedSettingsUpdate, ...):
|
||||
"""Validation is handled by Pydantic model validators."""
|
||||
vendor = vendor_service.get_vendor_by_id(db, current_user.token_vendor_id)
|
||||
update_data = letzshop_config.model_dump(exclude_unset=True)
|
||||
|
||||
for key, value in update_data.items():
|
||||
setattr(vendor, key, value)
|
||||
# ...
|
||||
```
|
||||
|
||||
**Same pattern applied to:**
|
||||
- `LocalizationSettingsUpdate` - language and locale validation
|
||||
|
||||
---
|
||||
|
||||
### 1.2 Admin Email Templates API
|
||||
|
||||
**File:** `app/api/v1/admin/email_templates.py`
|
||||
|
||||
**Problem:** 2 endpoints returning raw dicts instead of Pydantic models (API-001 violations).
|
||||
|
||||
**Solution:** Added Pydantic response models.
|
||||
|
||||
#### Before
|
||||
```python
|
||||
@router.get("")
|
||||
def list_templates(...):
|
||||
return {"templates": service.list_platform_templates()}
|
||||
|
||||
@router.get("/categories")
|
||||
def get_categories(...):
|
||||
return {"categories": service.get_template_categories()}
|
||||
```
|
||||
|
||||
#### After
|
||||
```python
|
||||
class TemplateListItem(BaseModel):
|
||||
code: str
|
||||
name: str
|
||||
description: str | None = None
|
||||
category: str
|
||||
languages: list[str] # Matches service output
|
||||
is_platform_only: bool = False
|
||||
variables: list[str] = []
|
||||
|
||||
class Config:
|
||||
from_attributes = True
|
||||
|
||||
class TemplateListResponse(BaseModel):
|
||||
templates: list[TemplateListItem]
|
||||
|
||||
class CategoriesResponse(BaseModel):
|
||||
categories: list[str]
|
||||
|
||||
@router.get("", response_model=TemplateListResponse)
|
||||
def list_templates(...):
|
||||
return TemplateListResponse(templates=service.list_platform_templates())
|
||||
|
||||
@router.get("/categories", response_model=CategoriesResponse)
|
||||
def get_categories(...):
|
||||
return CategoriesResponse(categories=service.get_template_categories())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.3 Shop Auth API (Password Reset)
|
||||
|
||||
**File:** `app/api/v1/shop/auth.py`
|
||||
|
||||
**Problem:** Business logic in `forgot_password()` and `reset_password()` endpoints.
|
||||
|
||||
**Solution:** Moved business logic to `CustomerService`.
|
||||
|
||||
#### Before (Business Logic in Endpoint)
|
||||
```python
|
||||
@router.post("/auth/reset-password")
|
||||
def reset_password(request: Request, reset_token: str, new_password: str, db: Session = Depends(get_db)):
|
||||
# Validate password length - BUSINESS LOGIC
|
||||
if len(new_password) < 8:
|
||||
raise HTTPException(status_code=400, detail="Password too short")
|
||||
|
||||
# Find valid token - BUSINESS LOGIC
|
||||
token_record = PasswordResetToken.find_valid_token(db, reset_token)
|
||||
if not token_record:
|
||||
raise HTTPException(status_code=400, detail="Invalid token")
|
||||
|
||||
# ... more business logic
|
||||
```
|
||||
|
||||
#### After (Delegated to Service)
|
||||
```python
|
||||
@router.post("/auth/reset-password", response_model=PasswordResetResponse)
|
||||
def reset_password(request: Request, reset_token: str, new_password: str, db: Session = Depends(get_db)):
|
||||
vendor = getattr(request.state, "vendor", None)
|
||||
if not vendor:
|
||||
raise VendorNotFoundException("context", identifier_type="subdomain")
|
||||
|
||||
# All business logic in service
|
||||
customer = customer_service.validate_and_reset_password(
|
||||
db=db,
|
||||
vendor_id=vendor.id,
|
||||
reset_token=reset_token,
|
||||
new_password=new_password,
|
||||
)
|
||||
db.commit()
|
||||
|
||||
return PasswordResetResponse(message="Password reset successfully.")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Service Layer Changes
|
||||
|
||||
### 2.1 CustomerService Enhancements
|
||||
|
||||
**File:** `app/services/customer_service.py`
|
||||
|
||||
Added two new methods for password reset:
|
||||
|
||||
```python
|
||||
def get_customer_for_password_reset(
|
||||
self, db: Session, vendor_id: int, email: str
|
||||
) -> Customer | None:
|
||||
"""Get active customer by email for password reset."""
|
||||
return (
|
||||
db.query(Customer)
|
||||
.filter(
|
||||
Customer.vendor_id == vendor_id,
|
||||
Customer.email == email.lower(),
|
||||
Customer.is_active == True,
|
||||
)
|
||||
.first()
|
||||
)
|
||||
|
||||
def validate_and_reset_password(
|
||||
self,
|
||||
db: Session,
|
||||
vendor_id: int,
|
||||
reset_token: str,
|
||||
new_password: str,
|
||||
) -> Customer:
|
||||
"""Validate reset token and update customer password.
|
||||
|
||||
Raises:
|
||||
PasswordTooShortException: If password too short
|
||||
InvalidPasswordResetTokenException: If token invalid/expired
|
||||
CustomerNotActiveException: If customer not active
|
||||
"""
|
||||
if len(new_password) < 8:
|
||||
raise PasswordTooShortException(min_length=8)
|
||||
|
||||
token_record = PasswordResetToken.find_valid_token(db, reset_token)
|
||||
if not token_record:
|
||||
raise InvalidPasswordResetTokenException()
|
||||
|
||||
customer = db.query(Customer).filter(Customer.id == token_record.customer_id).first()
|
||||
if not customer or customer.vendor_id != vendor_id:
|
||||
raise InvalidPasswordResetTokenException()
|
||||
|
||||
if not customer.is_active:
|
||||
raise CustomerNotActiveException(customer.email)
|
||||
|
||||
hashed_password = self.auth_service.hash_password(new_password)
|
||||
customer.hashed_password = hashed_password
|
||||
token_record.mark_used(db)
|
||||
|
||||
return customer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Exception Layer
|
||||
|
||||
### 3.1 New Customer Exceptions
|
||||
|
||||
**File:** `app/exceptions/customer.py`
|
||||
|
||||
Added two new exceptions for password reset:
|
||||
|
||||
```python
|
||||
class InvalidPasswordResetTokenException(ValidationException):
|
||||
"""Raised when password reset token is invalid or expired."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__(
|
||||
message="Invalid or expired password reset link. Please request a new one.",
|
||||
field="reset_token",
|
||||
)
|
||||
self.error_code = "INVALID_RESET_TOKEN"
|
||||
|
||||
|
||||
class PasswordTooShortException(ValidationException):
|
||||
"""Raised when password doesn't meet minimum length requirement."""
|
||||
|
||||
def __init__(self, min_length: int = 8):
|
||||
super().__init__(
|
||||
message=f"Password must be at least {min_length} characters long",
|
||||
field="password",
|
||||
details={"min_length": min_length},
|
||||
)
|
||||
self.error_code = "PASSWORD_TOO_SHORT"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. JavaScript Fixes
|
||||
|
||||
### 4.1 Admin Email Templates
|
||||
|
||||
**File:** `static/admin/js/email-templates.js`
|
||||
|
||||
**Problems:**
|
||||
- Used raw `fetch()` instead of `apiClient`
|
||||
- Used `showNotification()` instead of `Utils.showToast()`
|
||||
|
||||
#### Before
|
||||
```javascript
|
||||
async loadData() {
|
||||
this.loading = true;
|
||||
try {
|
||||
const response = await fetch('/api/v1/admin/email-templates');
|
||||
const data = await response.json();
|
||||
this.templates = data.templates || [];
|
||||
} catch (error) {
|
||||
showNotification('Failed to load templates', 'error');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### After
|
||||
```javascript
|
||||
async loadData() {
|
||||
this.loading = true;
|
||||
try {
|
||||
const [templatesData, categoriesData] = await Promise.all([
|
||||
apiClient.get('/admin/email-templates'),
|
||||
apiClient.get('/admin/email-templates/categories')
|
||||
]);
|
||||
this.templates = templatesData.templates || [];
|
||||
this.categories = categoriesData.categories || [];
|
||||
} catch (error) {
|
||||
Utils.showToast('Failed to load templates', 'error');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Vendor Email Templates
|
||||
|
||||
**File:** `static/vendor/js/email-templates.js`
|
||||
|
||||
**Problems:**
|
||||
- Used raw `fetch()` instead of `apiClient`
|
||||
- Missing parent init call pattern
|
||||
- Used `showNotification()` instead of `Utils.showToast()`
|
||||
|
||||
#### Before
|
||||
```javascript
|
||||
async init() {
|
||||
await this.loadData();
|
||||
}
|
||||
```
|
||||
|
||||
#### After
|
||||
```javascript
|
||||
async init() {
|
||||
vendorEmailTemplatesLog.info('Email templates init() called');
|
||||
|
||||
// Call parent init to set vendorCode and other base state
|
||||
const parentInit = data().init;
|
||||
if (parentInit) {
|
||||
await parentInit.call(this);
|
||||
}
|
||||
|
||||
await this.loadData();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Template Fixes
|
||||
|
||||
### 5.1 Admin Email Templates Template
|
||||
|
||||
**File:** `app/templates/admin/email-templates.html`
|
||||
|
||||
**Problem:** Wrong block name (TPL-015 violation).
|
||||
|
||||
```html
|
||||
<!-- Before -->
|
||||
{% block scripts %}
|
||||
|
||||
<!-- After -->
|
||||
{% block extra_scripts %}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.2 Shop Base Template
|
||||
|
||||
**File:** `app/templates/shop/base.html`
|
||||
|
||||
**Problem:** `request.state.language` used without default (LANG-009 violation).
|
||||
|
||||
```html
|
||||
<!-- Before -->
|
||||
language: '{{ request.state.language }}'
|
||||
|
||||
<!-- After -->
|
||||
language: '{{ request.state.language|default("fr") }}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Architecture Validator Fix
|
||||
|
||||
### 6.1 LANG-001 False Positive
|
||||
|
||||
**File:** `scripts/validate_architecture.py`
|
||||
|
||||
**Problem:** Validator flagged "English" as invalid language code in `SUPPORTED_LANGUAGES` dict (where it's a display name, not a code).
|
||||
|
||||
**Solution:** Extended pattern to skip `SUPPORTED_LANGUAGES` and `SUPPORTED_LOCALES` blocks.
|
||||
|
||||
```python
|
||||
# Before: Only skipped LANGUAGE_NAMES blocks
|
||||
if ("LANGUAGE_NAMES" in line or "LANGUAGE_NAMES_EN" in line) and "=" in line:
|
||||
in_language_names_dict = True
|
||||
|
||||
# After: Also skips SUPPORTED_LANGUAGES and SUPPORTED_LOCALES
|
||||
if any(
|
||||
name in line
|
||||
for name in [
|
||||
"LANGUAGE_NAMES",
|
||||
"LANGUAGE_NAMES_EN",
|
||||
"SUPPORTED_LANGUAGES",
|
||||
"SUPPORTED_LOCALES",
|
||||
]
|
||||
) and "=" in line:
|
||||
in_language_names_block = True
|
||||
if in_language_names_block and stripped in ("}", "]"):
|
||||
in_language_names_block = False
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Rules Reference
|
||||
|
||||
| Rule ID | Description | Fixed Files |
|
||||
|---------|-------------|-------------|
|
||||
| API-001 | Endpoint must use Pydantic models | admin/email_templates.py |
|
||||
| API-003 | Endpoint must NOT contain business logic | vendor/settings.py, shop/auth.py |
|
||||
| JS-001 | Must use apiClient for API calls | email-templates.js (admin & vendor) |
|
||||
| JS-002 | Must use Utils.showToast() for notifications | email-templates.js (admin & vendor) |
|
||||
| JS-003 | Must call parent init for Alpine components | vendor/email-templates.js |
|
||||
| TPL-015 | Must use correct block names | admin/email-templates.html |
|
||||
| LANG-009 | Must provide language default | shop/base.html |
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
After these changes:
|
||||
|
||||
```bash
|
||||
$ python scripts/validate_architecture.py
|
||||
|
||||
Files checked: 439
|
||||
Findings: 0 errors, 141 warnings, 2 info
|
||||
```
|
||||
|
||||
The remaining warnings are acceptable patterns (mostly `db.commit()` in services which is allowed for complex operations).
|
||||
|
||||
---
|
||||
|
||||
## Commit Reference
|
||||
|
||||
```
|
||||
commit 5155ef7
|
||||
fix: resolve all architecture validation errors (62 -> 0)
|
||||
|
||||
10 files changed, 394 insertions(+), 380 deletions(-)
|
||||
```
|
||||
@@ -56,7 +56,7 @@ Git is an open-source, distributed version control system that helps you manage
|
||||
Adding new repository on NAS DS223J
|
||||
|
||||
```bash
|
||||
> ssh boulaht1@DS223J
|
||||
> ssh boulaht1@DS223J -p 22
|
||||
> sudo -i
|
||||
> cd /volume1/git-repos/
|
||||
> git --bare init my-repo.git
|
||||
|
||||
Reference in New Issue
Block a user