orion/docs/implementation/admin-notification-system.md

# 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_stores`, `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_store_issue()` | Store-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,
    store_name="Acme Corp",
    job_id=123,
    error_message="CSV parsing failed: invalid column format",
    store_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