feat: add admin notification system

- Add AdminNotificationService for notification operations - Enhance notifications API with mark-read, mark-all-read endpoints - Add notifications.html page template - Add notifications.js Alpine component - Add implementation documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-21 14:11:48 +01:00
parent 4dc08f87c5
commit 02edea7cb3
5 changed files with 1759 additions and 33 deletions
--- a/docs/implementation/admin-notification-system.md
+++ b/docs/implementation/admin-notification-system.md
@@ -0,0 +1,187 @@
+# Admin Notification System
+
+## Overview
+
+The admin notification system provides real-time alerts and notifications to platform administrators for important events, errors, and system status updates.
+
+## Components
+
+### Backend
+
+#### Database Models
+
+Located in `models/database/admin.py`:
+
+- **AdminNotification**: Stores individual notifications
+  - `type`: Notification type (import_failure, order_sync_failure, etc.)
+  - `priority`: low, normal, high, critical
+  - `title`, `message`: Content
+  - `is_read`, `read_at`, `read_by_user_id`: Read tracking
+  - `action_required`, `action_url`: Optional action link
+  - `notification_metadata`: JSON for additional context
+
+- **PlatformAlert**: Stores platform-wide alerts
+  - `alert_type`: security, performance, capacity, integration, etc.
+  - `severity`: info, warning, error, critical
+  - `affected_vendors`, `affected_systems`: Scope tracking
+  - `occurrence_count`, `first_occurred_at`, `last_occurred_at`: Deduplication
+  - `is_resolved`, `resolved_at`, `resolution_notes`: Resolution tracking
+
+#### Service Layer
+
+Located in `app/services/admin_notification_service.py`:
+
+```python
+from app.services.admin_notification_service import (
+    admin_notification_service,
+    platform_alert_service,
+    NotificationType,
+    Priority,
+    AlertType,
+    Severity,
+)
+```
+
+**AdminNotificationService** methods:
+
+| Method | Description |
+|--------|-------------|
+| `create_notification()` | Create a new notification |
+| `get_notifications()` | List notifications with filters |
+| `get_recent_notifications()` | Get recent unread for header dropdown |
+| `get_unread_count()` | Count unread notifications |
+| `mark_as_read()` | Mark single notification read |
+| `mark_all_as_read()` | Mark all as read |
+| `delete_notification()` | Delete a notification |
+
+**Convenience methods** for common scenarios:
+
+| Method | Use Case |
+|--------|----------|
+| `notify_import_failure()` | Product/order import failed |
+| `notify_order_sync_failure()` | Letzshop sync failed |
+| `notify_order_exception()` | Order has unmatched products |
+| `notify_critical_error()` | System critical error |
+| `notify_vendor_issue()` | Vendor-related problem |
+| `notify_security_alert()` | Security event detected |
+
+**PlatformAlertService** methods:
+
+| Method | Description |
+|--------|-------------|
+| `create_alert()` | Create a new platform alert |
+| `get_alerts()` | List alerts with filters |
+| `resolve_alert()` | Mark alert as resolved |
+| `get_statistics()` | Get alert counts and stats |
+| `create_or_increment_alert()` | Deduplicate recurring alerts |
+
+#### API Endpoints
+
+Located in `app/api/v1/admin/notifications.py`:
+
+**Notifications:**
+- `GET /api/v1/admin/notifications` - List with filters
+- `POST /api/v1/admin/notifications` - Create (manual)
+- `GET /api/v1/admin/notifications/recent` - For header dropdown
+- `GET /api/v1/admin/notifications/unread-count` - Badge count
+- `PUT /api/v1/admin/notifications/{id}/read` - Mark read
+- `PUT /api/v1/admin/notifications/mark-all-read` - Mark all read
+- `DELETE /api/v1/admin/notifications/{id}` - Delete
+
+**Platform Alerts:**
+- `GET /api/v1/admin/notifications/alerts` - List with filters
+- `POST /api/v1/admin/notifications/alerts` - Create (manual)
+- `PUT /api/v1/admin/notifications/alerts/{id}/resolve` - Resolve
+- `GET /api/v1/admin/notifications/alerts/stats` - Statistics
+
+### Frontend
+
+#### Header Dropdown
+
+Located in `app/templates/admin/partials/header.html`:
+
+- Real-time notification bell with unread count badge
+- Polls for new notifications every 60 seconds
+- Quick actions: mark as read, view all
+- Priority-based color coding
+
+#### Notifications Page
+
+Located in `app/templates/admin/notifications.html` with `static/admin/js/notifications.js`:
+
+- Full notifications management interface
+- Two tabs: Notifications and Platform Alerts
+- Statistics cards (unread, active alerts, critical, resolved today)
+- Filtering by priority, type, read status
+- Bulk operations (mark all read)
+- Alert resolution workflow
+
+## Automatic Triggers
+
+Notifications are automatically created in these scenarios:
+
+### Import Failures
+
+**Product Import** (`app/tasks/background_tasks.py`):
+- When a product import job fails completely
+- When import completes with 5+ errors
+
+**Historical Order Import** (`app/tasks/letzshop_tasks.py`):
+- When Letzshop API returns an error
+- When import fails with an unexpected exception
+
+### Example Usage
+
+```python
+from app.services.admin_notification_service import admin_notification_service
+
+# In a background task or service
+admin_notification_service.notify_import_failure(
+    db=db,
+    vendor_name="Acme Corp",
+    job_id=123,
+    error_message="CSV parsing failed: invalid column format",
+    vendor_id=5,
+)
+db.commit()
+```
+
+## Priority Levels
+
+| Priority | When to Use | Badge Color |
+|----------|-------------|-------------|
+| `critical` | System down, data loss risk | Red |
+| `high` | Import/sync failures, action needed | Orange |
+| `normal` | Informational alerts | Blue |
+| `low` | Minor issues, suggestions | Gray |
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────────┐
+│  Background     │────▶│  Notification        │
+│  Tasks          │     │  Service             │
+└─────────────────┘     └──────────┬───────────┘
+                                   │
+┌─────────────────┐                ▼
+│  API Endpoints  │◀───────────────┤
+└─────────────────┘                │
+                                   ▼
+┌─────────────────┐     ┌──────────────────────┐
+│  Header         │◀────│  Database            │
+│  Dropdown       │     │  (admin_notifications│
+└─────────────────┘     │   platform_alerts)   │
+         │              └──────────────────────┘
+         ▼
+┌─────────────────┐
+│  Notifications  │
+│  Page           │
+└─────────────────┘
+```
+
+## Future Enhancements
+
+- Email notifications for critical alerts
+- Webhook integration for external systems
+- Customizable notification preferences per admin
+- Scheduled notification digests