# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

AI Alert Platform backend service built with FastAPI. Receives alerts from edge AI devices via MQTT and HTTP, stores snapshot images, pushes real-time updates over WebSocket, and exposes REST APIs for a Yudao (芋道) Vue 3 frontend. Optionally triggers async big-model analysis on alert snapshots.

## Commands

```bash
# Install dependencies
pip install -r requirements.txt

# Run development server (starts at http://localhost:8000, auto-reload in debug mode)
python -m app.main

# API docs: http://localhost:8000/docs

# Production run with Gunicorn (Linux only)
gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:8000
```

Environment setup: copy `.env.example` to `.env` and configure. SQLite is the default database; set `DATABASE_URL` for MySQL in production. Set `MQTT_ENABLED=false` if no MQTT broker is available.

No test suite exists yet. If adding tests, use pytest.

**Root `main.py`** is a PyCharm template file, not the real entry point. Always use `python -m app.main`.

## Architecture

### Data Flow

```
Edge Devices ──MQTT──→ EMQX Broker ──subscribe──→ MQTTService ──→ AlertService ──→ DB
                                                        │
Edge Devices ──HTTP POST──→ /api/v1/alerts ────────────→│
                                                        ↓
                                              NotificationService ──WebSocket──→ Frontend
```

### Dual API Surface

The app exposes two parallel API layers hitting the same services and database:

1. **Native API** (`/api/v1/`) — endpoints defined inline in `app/main.py`. Standard REST responses.
2. **Yudao-compat API** (`/admin-api/`) — routers in `app/routers/yudao_alert.py` and `yudao_auth.py`. Wraps responses in `{"code": 0, "data": ..., "msg": ""}` format expected by the Yudao Vue frontend. Auth/permissions handled by `app/yudao_compat.py` (stub in dev mode: `DEV_MODE=true` skips token validation, returns mock admin).

### Services (Global Singletons)

All services are instantiated as module-level singletons, not injected via FastAPI `Depends()`. Access them via factory functions (`get_alert_service()`, `get_mqtt_service()`, etc.) or import the global directly.

- **AlertService** (`app/services/alert_service.py`) — CRUD, filtering/pagination, statistics, AI analysis update. Handles both HTTP (`create_alert`) and MQTT (`create_alert_from_mqtt`) creation paths. Alert numbers: `ALT` + timestamp + uuid fragment.
- **MQTTService** (`app/services/mqtt_service.py`) — paho-mqtt client subscribing to `edge/alert/#`. Routes messages to registered callbacks for alerts vs heartbeats. Compatible with paho-mqtt 1.x and 2.x APIs.
- **DeviceService** (`app/services/device_service.py`) — Tracks edge device status from MQTT heartbeats. In-memory cache + DB persistence. Marks devices offline after 90s without heartbeat.
- **NotificationService** (`app/services/notification_service.py`) — WebSocket connection manager + broadcast. Bridges sync MQTT callbacks to async WebSocket sends via `asyncio.run_coroutine_threadsafe()`.
- **OSSStorage** (`app/services/oss_storage.py`) — Image storage. Currently local-only (`uploads/` dir); Aliyun OSS stubbed but not implemented.
- **AIAnalyzer** (`app/services/ai_analyzer.py`) — Async httpx client for optional big-model analysis. Fire-and-forget via `asyncio.create_task()`.

### Lifecycle (`app/main.py` lifespan)

Startup: init DB → set async event loop on NotificationService → register MQTT handlers → start MQTT.
Shutdown: stop MQTT.

### Database

SQLite at `data/alert_platform.db` (auto-created). Three ORM models in `app/models.py`:

- **Alert** — main table. Enums: `AlertStatus` (pending/confirmed/ignored/resolved/dispatched), `AlertLevel` (low/medium/high/critical). Indexed on alert_no, camera_id, status, trigger_time.
- **EdgeDevice** — device status and heartbeat tracking. Enum: `DeviceStatus` (online/offline/error).
- **WorkOrder** — framework exists (model + relationship to Alert) but no API/service layer yet.

Sessions obtained via `get_session()`. Services manage their own session lifecycle with try/finally.

### Config

`app/config.py` — dataclass-based config loaded from `.env` via `os.getenv()`. Sections: `DatabaseConfig`, `OSSConfig`, `AppConfig` (includes `dev_mode`), `AIModelConfig`, `MQTTConfig`. Global `settings` instance created at module load.

### Key MQTT Topics

- Alert: `edge/alert/{camera_id}/{roi_id}` — JSON with camera_id, roi_id, alert_type, confidence, etc.
- Heartbeat: `edge/alert/heartbeat/{device_id}` — JSON with device_id, status, uptime, counters.