Samir Boulahtit
3c7af0ccdf
Renamed all documentation files to follow kebab-case naming standard: - UPPERCASE files → lowercase (e.g., RBAC.md → rbac.md) - snake_case files → kebab-case (e.g., icons_guide.md → icons-guide.md) - SCREAMING_SNAKE_CASE → kebab-case (e.g., DATABASE_SETUP_GUIDE.md → database-setup-guide.md) Files renamed (15 total): API Documentation: - api/RBAC.md → api/rbac.md Architecture: - architecture/API_CONSOLIDATION_PROPOSAL.md → api-consolidation-proposal.md - architecture/API_MIGRATION_STATUS.md → api-migration-status.md Development: - development/AUTH_DEPENDENCIES_GUIDE.md → auth-dependencies-guide.md - development/CUSTOMER_AUTHENTICATION_IMPLEMENTATION.md → customer-authentication-implementation.md - development/CUSTOMER_AUTH_SUMMARY.md → customer-auth-summary.md - development/icons_guide.md → icons-guide.md Database Seeder: - database-seeder/DATABASE_INIT_GUIDE.md → database-init-guide.md - database-seeder/DATABASE_QUICK_REFERENCE_GUIDE.md → database-quick-reference-guide.md - database-seeder/DATABASE_SEEDER_DOCUMENTATION.md → database-seeder-documentation.md - database-seeder/MAKEFILE_DATABASE_SEEDER.md → makefile-database-seeder.md Error Rendering: - error-rendering/ERROR_RENDERING_DEVELOPER_DOCUMENTATION.md → error-rendering-developer-documentation.md - error-rendering/HTML_ERROR_RENDERING_FLOW_DIAGRAM.md → html-error-rendering-flow-diagram.md Getting Started: - getting-started/DATABASE_QUICK_REFERENCE.md → database-quick-reference.md - getting-started/DATABASE_SETUP_GUIDE.md → database-setup-guide.md Updates: - Updated all references in mkdocs.yml - Updated all cross-references in markdown files - Verified mkdocs builds without warnings or errors Standard: Use kebab-case (lowercase-with-hyphens) for all markdown files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
316 lines
18 KiB
Markdown
316 lines
18 KiB
Markdown
# Error Handling System - Flow Diagram
|
|
|
|
## Request Processing Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Incoming HTTP Request │
|
|
└─────────────────────────────────┬───────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Vendor Context Middleware (FIRST) │
|
|
│ - Detects vendor from domain/subdomain/path │
|
|
│ - Sets request.state.vendor │
|
|
│ - Sets request.state.vendor_context │
|
|
└─────────────────────────────────┬───────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Context Detection Middleware (NEW) │
|
|
│ - Detects request context type │
|
|
│ - Sets request.state.context_type │
|
|
│ • API, ADMIN, VENDOR_DASHBOARD, SHOP, FALLBACK │
|
|
└─────────────────────────────────┬───────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Route Handler Execution │
|
|
│ - Process business logic │
|
|
│ - May throw exceptions │
|
|
└─────────────────────────────────┬───────────────────────────────┘
|
|
│
|
|
┌─────────────┴─────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ Success │ │ Exception │
|
|
│ Response │ │ Raised │
|
|
└──────────────┘ └──────┬───────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Exception Handler │
|
|
│ - WizamartException │
|
|
│ - HTTPException │
|
|
│ - RequestValidationError │
|
|
│ - Generic Exception │
|
|
│ - 404 Not Found │
|
|
└────────────────────┬───────────────────────────────────┘
|
|
│
|
|
┌─────────────┴────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────┐ ┌──────────────────┐
|
|
│ Special Case: │ │ General Error │
|
|
│ 401 on HTML │ │ Handling │
|
|
│ → Redirect to │ │ │
|
|
│ Login │ │ │
|
|
└──────────────────┘ └─────────┬────────┘
|
|
│
|
|
┌─────────────┴─────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────┐ ┌──────────────────┐
|
|
│ API Request? │ │ HTML Request? │
|
|
│ /api/* path │ │ GET + text/html │
|
|
└────────┬─────────┘ └─────────┬────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────┐ ┌──────────────────────────┐
|
|
│ Return JSON │ │ Error Page Renderer │
|
|
│ Response │ │ │
|
|
│ { │ │ - Detect context type │
|
|
│ error_code, │ │ - Select template │
|
|
│ message, │ │ - Prepare data │
|
|
│ status_code │ │ - Render HTML │
|
|
│ } │ └──────────┬───────────────┘
|
|
└──────────────────┘ │
|
|
▼
|
|
┌──────────────────────────────┐
|
|
│ Template Selection │
|
|
│ │
|
|
│ Priority: │
|
|
│ 1. {context}/errors/{code} │
|
|
│ 2. {context}/errors/generic│
|
|
│ 3. shared/{code}-fallback │
|
|
│ 4. shared/generic-fallback │
|
|
└──────────┬───────────────────┘
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ Admin │ │ Vendor │ │ Shop │
|
|
│ Error │ │ Error │ │ Error │
|
|
│ Page │ │ Page │ │ Page │
|
|
│ │ │ │ │ (Themed) │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Context Detection Logic
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────────┐
|
|
│ Request Arrives │
|
|
│ (host + path) │
|
|
└────────────────────────────┬─────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────┐
|
|
│ Path starts │───YES───→ API Context
|
|
│ with /api/ ? │ (Always JSON)
|
|
└────────┬─────────┘
|
|
│ NO
|
|
▼
|
|
┌──────────────────┐
|
|
│ Host starts │───YES───→ ADMIN Context
|
|
│ with admin. │ (Admin Portal)
|
|
│ OR path starts │
|
|
│ with /admin ? │
|
|
└────────┬─────────┘
|
|
│ NO
|
|
▼
|
|
┌──────────────────┐
|
|
│ Path starts │───YES───→ VENDOR_DASHBOARD Context
|
|
│ with /vendor/ ? │ (Vendor Management)
|
|
└────────┬─────────┘
|
|
│ NO
|
|
▼
|
|
┌──────────────────┐
|
|
│ Vendor object │───YES───→ SHOP Context
|
|
│ in request │ (Customer Storefront)
|
|
│ state? │
|
|
└────────┬─────────┘
|
|
│ NO
|
|
▼
|
|
┌──────────────────┐
|
|
│ FALLBACK │
|
|
│ Context │
|
|
│ (Unknown) │
|
|
└──────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Template Selection Example
|
|
|
|
For a 404 error in ADMIN context:
|
|
|
|
```
|
|
1. Check: app/templates/admin/errors/404.html ✓ EXISTS → USE THIS
|
|
2. Check: app/templates/admin/errors/generic.html (skipped)
|
|
3. Check: app/templates/shared/404-fallback.html (skipped)
|
|
4. Check: app/templates/shared/generic-fallback.html (skipped)
|
|
```
|
|
|
|
For a 429 error in SHOP context (not created yet):
|
|
|
|
```
|
|
1. Check: app/templates/shop/errors/429.html ✗ Missing
|
|
2. Check: app/templates/shop/errors/generic.html ✗ Missing
|
|
3. Check: app/templates/shared/429-fallback.html ✗ Missing
|
|
4. Check: app/templates/shared/generic-fallback.html ✓ EXISTS → USE THIS
|
|
```
|
|
|
|
---
|
|
|
|
## Error Response Types
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────────┐
|
|
│ Request Type │
|
|
└───────────┬─────────────┬───────────────────┬─────────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌────────────┐ ┌────────────┐ ┌──────────────┐
|
|
│ API │ │ HTML Page │ │ 401 on HTML │
|
|
│ Request │ │ Request │ │ Page │
|
|
└──────┬─────┘ └──────┬─────┘ └──────┬───────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌────────────┐ ┌────────────┐ ┌──────────────┐
|
|
│ JSON │ │ Rendered │ │ Redirect │
|
|
│ Response │ │ HTML │ │ to Login │
|
|
│ │ │ Error │ │ │
|
|
│ { │ │ Page │ │ 302 Found │
|
|
│ error_code│ │ │ │ Location: │
|
|
│ message │ │ Context- │ │ /admin/login│
|
|
│ status │ │ aware │ │ /vendor/login│
|
|
│ details │ │ template │ │ /shop/login │
|
|
│ } │ │ │ │ │
|
|
└────────────┘ └────────────┘ └──────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Example Scenarios
|
|
|
|
### Scenario 1: API 404 Error
|
|
```
|
|
Request: GET /api/v1/admin/vendors/999
|
|
Context: API
|
|
Result: JSON { "error_code": "VENDOR_NOT_FOUND", ... }
|
|
```
|
|
|
|
### Scenario 2: Admin Page 404 Error
|
|
```
|
|
Request: GET /admin/nonexistent
|
|
Accept: text/html
|
|
Context: ADMIN
|
|
Result: HTML admin/errors/404.html
|
|
```
|
|
|
|
### Scenario 3: Shop Page 500 Error
|
|
```
|
|
Request: GET /products/123 (on vendor1.platform.com)
|
|
Accept: text/html
|
|
Context: SHOP (vendor detected)
|
|
Result: HTML shop/errors/500.html (with vendor theme)
|
|
```
|
|
|
|
### Scenario 4: Unauthorized Access to Admin
|
|
```
|
|
Request: GET /admin/settings
|
|
Accept: text/html
|
|
No valid session
|
|
Context: ADMIN
|
|
Result: 302 Redirect to /admin/login
|
|
```
|
|
|
|
---
|
|
|
|
## Debug Information Display
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────┐
|
|
│ Error Page Display │
|
|
└──────────────────────┬───────────────────────────────────────┘
|
|
│
|
|
┌───────────┴───────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ Admin User │ │ Other Users │
|
|
│ (Context: │ │ (Vendor, │
|
|
│ ADMIN) │ │ Shop) │
|
|
└──────┬───────┘ └──────┬───────┘
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ Debug Info │ │ No Debug │
|
|
│ SHOWN: │ │ Info: │
|
|
│ • Path │ │ │
|
|
│ • Error code │ │ Only user- │
|
|
│ • Details │ │ friendly │
|
|
│ • Stack │ │ message │
|
|
└──────────────┘ └──────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## File Organization
|
|
|
|
```
|
|
app/
|
|
├── exceptions/
|
|
│ ├── handler.py # Exception handlers (refactored)
|
|
│ ├── error_renderer.py # NEW: Renders error pages
|
|
│ └── base.py # Base exceptions
|
|
│
|
|
├── templates/
|
|
│ ├── admin/
|
|
│ │ └── errors/ # NEW: Admin error pages
|
|
│ │ ├── base.html # Base template
|
|
│ │ ├── 404.html # Specific errors
|
|
│ │ └── generic.html # Catch-all
|
|
│ │
|
|
│ ├── vendor/
|
|
│ │ └── errors/ # TODO: Vendor error pages
|
|
│ │
|
|
│ ├── shop/
|
|
│ │ └── errors/ # TODO: Shop error pages (themed)
|
|
│ │
|
|
│ └── shared/
|
|
│ └── *-fallback.html # Shared fallback error pages
|
|
|
|
middleware/
|
|
├── vendor_context.py # Vendor detection (existing)
|
|
├── context_middleware.py # NEW: Context detection
|
|
└── theme_context.py # Theme loading (existing)
|
|
```
|
|
|
|
---
|
|
|
|
## Benefits Summary
|
|
|
|
✅ **Separation of Concerns**: HTML templates separate from handler logic
|
|
✅ **Context-Aware**: Different error pages for different areas
|
|
✅ **Maintainable**: Easy to update individual error pages
|
|
✅ **Scalable**: Easy to add new contexts or error types
|
|
✅ **Professional**: Polished error pages matching area design
|
|
✅ **Flexible**: Fallback mechanism ensures errors always render
|
|
✅ **Secure**: Debug info only shown to admins
|
|
✅ **Themed**: Shop errors can use vendor branding (Phase 3)
|
|
|
|
---
|
|
|
|
This flow ensures that:
|
|
1. API calls ALWAYS get JSON responses
|
|
2. HTML page requests get appropriate error pages
|
|
3. Each context (admin/vendor/shop) has its own error design
|
|
4. Fallback mechanism prevents broken error pages
|
|
5. 401 errors redirect to appropriate login pages
|