feat: add logging, marketplace, and admin enhancements

Database & Migrations:
- Add application_logs table migration for hybrid cloud logging
- Add companies table migration and restructure vendor relationships

Logging System:
- Implement hybrid logging system (database + file)
- Add log_service for centralized log management
- Create admin logs page with filtering and viewing capabilities
- Add init_log_settings.py script for log configuration
- Enhance core logging with database integration

Marketplace Integration:
- Add marketplace admin page with product management
- Create marketplace vendor page with product listings
- Implement marketplace.js for both admin and vendor interfaces
- Add marketplace integration documentation

Admin Enhancements:
- Add imports management page and functionality
- Create settings page for admin configuration
- Add vendor themes management page
- Enhance vendor detail and edit pages
- Improve code quality dashboard and violation details
- Add logs viewing and management
- Update icons guide and shared icon system

Architecture & Documentation:
- Document frontend structure and component architecture
- Document models structure and relationships
- Add vendor-in-token architecture documentation
- Add vendor RBAC (role-based access control) documentation
- Document marketplace integration patterns
- Update architecture patterns documentation

Infrastructure:
- Add platform static files structure (css, img, js)
- Move architecture_scan.py to proper models location
- Update model imports and registrations
- Enhance exception handling
- Update dependency injection patterns

UI/UX:
- Improve vendor edit interface
- Update admin user interface
- Enhance page templates documentation
- Add vendor marketplace interface
This commit is contained in:
2025-12-01 21:51:07 +01:00
parent 915734e9b4
commit cc74970223
56 changed files with 8440 additions and 202 deletions

View File

@@ -221,6 +221,101 @@ async def create_vendor(
return result
```
### Rule API-005: Vendor Context from Token (Not URL)
**Vendor API endpoints MUST extract vendor context from JWT token, NOT from URL.**
> **Rationale:** Embedding vendor context in JWT tokens enables clean RESTful API endpoints, eliminates URL-based vendor detection issues, and improves security by cryptographically signing vendor access.
**❌ BAD: URL-based vendor detection**
```python
from middleware.vendor_context import require_vendor_context
@router.get("/products")
def get_products(
vendor: Vendor = Depends(require_vendor_context()), # ❌ Requires vendor in URL
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
# This fails on /api/v1/vendor/products (no vendor in URL)
products = product_service.get_vendor_products(db, vendor.id)
return products
```
**Issues with URL-based approach:**
- ❌ Only works with routes like `/vendor/{vendor_code}/dashboard`
- ❌ Fails on API routes like `/api/v1/vendor/products` (no vendor in URL)
- ❌ Inconsistent between page routes and API routes
- ❌ Violates RESTful API design
- ❌ Requires database lookup on every request
**✅ GOOD: Token-based vendor context**
```python
@router.get("/products")
def get_products(
current_user: User = Depends(get_current_vendor_api), # ✅ Vendor in token
db: Session = Depends(get_db),
):
# Extract vendor from JWT token
if not hasattr(current_user, "token_vendor_id"):
raise HTTPException(
status_code=400,
detail="Token missing vendor information. Please login again.",
)
vendor_id = current_user.token_vendor_id
# Use vendor_id from token
products = product_service.get_vendor_products(db, vendor_id)
return products
```
**Benefits of token-based approach:**
- ✅ Works on all routes (page and API)
- ✅ Clean RESTful API endpoints
- ✅ Vendor context cryptographically signed in JWT
- ✅ No database lookup needed for vendor detection
- ✅ Consistent authentication mechanism
- ✅ Security: Cannot be tampered with by client
**Token structure:**
```json
{
"sub": "user_id",
"username": "john.doe",
"vendor_id": 123, Vendor context
"vendor_code": "WIZAMART", Vendor code
"vendor_role": "Owner" Vendor role
}
```
**Available token attributes:**
- `current_user.token_vendor_id` - Vendor ID (use for database queries)
- `current_user.token_vendor_code` - Vendor code (use for logging)
- `current_user.token_vendor_role` - Vendor role (Owner, Manager, etc.)
**Migration checklist:**
1. Remove `vendor: Vendor = Depends(require_vendor_context())`
2. Remove unused imports: `from middleware.vendor_context import require_vendor_context`
3. Extract vendor from token: `vendor_id = current_user.token_vendor_id`
4. Add token validation check (see example above)
5. Update logging to use `current_user.token_vendor_code`
**See also:** `docs/backend/vendor-in-token-architecture.md` for complete migration guide
**Files requiring migration:**
- `app/api/v1/vendor/customers.py`
- `app/api/v1/vendor/notifications.py`
- `app/api/v1/vendor/media.py`
- `app/api/v1/vendor/marketplace.py`
- `app/api/v1/vendor/inventory.py`
- `app/api/v1/vendor/settings.py`
- `app/api/v1/vendor/analytics.py`
- `app/api/v1/vendor/payments.py`
- `app/api/v1/vendor/profile.py`
---
## Service Layer Patterns