revamping documentation
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,315 @@
|
||||
# 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. fallback/{code}.html │
|
||||
│ 4. fallback/generic.html │
|
||||
└──────────┬───────────────────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ 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/fallback/404.html (skipped)
|
||||
4. Check: app/templates/fallback/generic.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/fallback/429.html ✗ Missing
|
||||
4. Check: app/templates/fallback/generic.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)
|
||||
│ │
|
||||
│ └── fallback/
|
||||
│ └── (minimal pages) # NEW: Unknown context fallback
|
||||
|
||||
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
|
||||
Reference in New Issue
Block a user