diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..8718327 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,315 @@ +# AI 告警平台架构设计 + +## 一、目标架构 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 告警平台 (FastAPI) │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐│ +│ │ MQTT 订阅服务 │ │ REST API 服务 │ │ WebSocket 推送服务 ││ +│ │ edge/alert/# │ │ /api/v1/... │ │ /ws/alerts ││ +│ └────────┬─────────┘ └────────┬─────────┘ └────────────▲─────────────┘│ +│ │ │ │ │ +│ └──────────────────────┼──────────────────────────┘ │ +│ ▼ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ 核心业务层 │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ 告警服务 │ │ 工单服务 │ │ 设备服务 │ │ 通知服务 │ │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ 数据层 │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ SQLite/ │ │ 图片存储 │ │ Redis缓存 │ │ │ +│ │ │ MySQL │ │ (本地/OSS) │ │ (可选) │ │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ + ▲ │ + │ MQTT (边缘端上报) │ WebSocket (前端展示) + │ ▼ +┌─────────┴───────────┐ ┌────────────────────────┐ +│ ai_edge 边缘端 │ │ 前端 (Vue/React) │ +│ - YOLO推理 │ │ - 告警列表 │ +│ - 算法判断 │ │ - 工单管理 │ +│ - MQTT上报 │ │ - 设备监控 │ +└─────────────────────┘ └────────────────────────┘ +``` + +## 二、数据模型 + +### 2.1 告警表 (alerts) - 已有，增强 + +```sql +alerts ( + id BIGINT PRIMARY KEY, + alert_no VARCHAR(32) UNIQUE, -- 告警编号 + + -- 来源信息 + camera_id VARCHAR(64) NOT NULL, -- 摄像头ID + roi_id VARCHAR(64), -- ROI区域ID + bind_id VARCHAR(64), -- 绑定ID + device_id VARCHAR(64), -- 边缘设备ID + + -- 告警内容 + alert_type VARCHAR(64) NOT NULL, -- leave_post/intrusion/crowd + algorithm VARCHAR(128), -- 算法名称 + confidence INTEGER, -- 置信度 0-100 + duration_minutes INTEGER, -- 持续时长 + trigger_time DATETIME NOT NULL, -- 触发时间 + message TEXT, -- 告警消息 + bbox JSON, -- 检测框坐标 + + -- 截图 + snapshot_url VARCHAR(512), -- 图片URL + snapshot_path VARCHAR(512), -- 本地路径 + + -- 处理状态 + status ENUM('pending','confirmed','ignored','resolved','dispatched'), + level ENUM('low','medium','high','critical'), + handle_remark TEXT, + handled_by VARCHAR(64), + handled_at DATETIME, + + -- AI分析 + ai_analysis JSON, + + -- 关联工单 + work_order_id BIGINT, -- 关联的工单ID + + -- 时间戳 + created_at DATETIME, + updated_at DATETIME, + + INDEX idx_camera (camera_id), + INDEX idx_status (status), + INDEX idx_trigger_time (trigger_time) +) +``` + +### 2.2 工单表 (work_orders) - 新增 + +```sql +work_orders ( + id BIGINT PRIMARY KEY, + order_no VARCHAR(32) UNIQUE, -- 工单编号 + + -- 关联告警 + alert_id BIGINT, -- 关联告警ID + alert_no VARCHAR(32), -- 告警编号(冗余) + + -- 工单内容 + title VARCHAR(255) NOT NULL, -- 工单标题 + description TEXT, -- 问题描述 + priority ENUM('low','medium','high','urgent'), + + -- 派发信息 + assignee_id VARCHAR(64), -- 处理人ID + assignee_name VARCHAR(64), -- 处理人姓名 + department VARCHAR(64), -- 处理部门 + + -- 状态流转 + status ENUM('created','assigned','processing','completed','closed'), + + -- 处理结果 + result TEXT, -- 处理结果 + attachments JSON, -- 附件列表 + + -- 时间 + deadline DATETIME, -- 截止时间 + assigned_at DATETIME, -- 派发时间 + started_at DATETIME, -- 开始处理时间 + completed_at DATETIME, -- 完成时间 + created_at DATETIME, + updated_at DATETIME, + + INDEX idx_alert (alert_id), + INDEX idx_status (status), + INDEX idx_assignee (assignee_id) +) +``` + +### 2.3 边缘设备表 (edge_devices) - 新增 + +```sql +edge_devices ( + id BIGINT PRIMARY KEY, + device_id VARCHAR(64) UNIQUE, -- 设备唯一ID + device_name VARCHAR(128), -- 设备名称 + + -- 状态 + status ENUM('online','offline','error'), + last_heartbeat DATETIME, -- 最后心跳时间 + + -- 运行信息 + uptime_seconds BIGINT, -- 运行时长 + frames_processed BIGINT, -- 处理帧数 + alerts_generated BIGINT, -- 生成告警数 + + -- 配置 + ip_address VARCHAR(45), -- 设备IP + stream_count INTEGER, -- 视频流数量 + config_version VARCHAR(32), -- 配置版本 + + -- 扩展 + extra_info JSON, -- 其他信息 + + created_at DATETIME, + updated_at DATETIME, + + INDEX idx_status (status) +) +``` + +## 三、API 设计 + +### 3.1 告警 API (已有，扩展) + +``` +POST /api/v1/alerts # 创建告警 (HTTP方式) +GET /api/v1/alerts # 告警列表 (分页、筛选) +GET /api/v1/alerts/{id} # 告警详情 +PUT /api/v1/alerts/{id}/handle # 处理告警 +DELETE /api/v1/alerts/{id} # 删除告警 +GET /api/v1/alerts/statistics # 统计数据 +POST /api/v1/alerts/{id}/dispatch # 派发工单 (新增) +``` + +### 3.2 工单 API (新增) + +``` +POST /api/v1/work-orders # 创建工单 +GET /api/v1/work-orders # 工单列表 +GET /api/v1/work-orders/{id} # 工单详情 +PUT /api/v1/work-orders/{id} # 更新工单 +PUT /api/v1/work-orders/{id}/assign # 派发工单 +PUT /api/v1/work-orders/{id}/start # 开始处理 +PUT /api/v1/work-orders/{id}/complete # 完成工单 +GET /api/v1/work-orders/statistics # 工单统计 +``` + +### 3.3 设备 API (新增) + +``` +GET /api/v1/devices # 设备列表 +GET /api/v1/devices/{id} # 设备详情 +GET /api/v1/devices/{id}/alerts # 设备告警列表 +GET /api/v1/devices/statistics # 设备统计 +``` + +### 3.4 WebSocket (新增) + +``` +WS /ws/alerts # 实时告警推送 + - event: new_alert # 新告警 + - event: alert_updated # 告警更新 + - event: device_status # 设备状态变更 +``` + +## 四、MQTT 主题设计 + +与 ai_edge 对齐： + +``` +edge/alert/{camera_id}/{roi_id} # 告警消息 +edge/alert/heartbeat/{device_id} # 心跳消息 +``` + +消息格式： + +```json +// 告警消息 +{ + "alert_id": "uuid", + "camera_id": "cam_001", + "roi_id": "roi_001", + "alert_type": "leave_post", + "target_class": "person", + "confidence": 0.95, + "bbox": [100, 200, 300, 400], + "message": "检测到离岗", + "timestamp": "2026-02-05T10:00:00", + "duration_minutes": 5.5 +} + +// 心跳消息 +{ + "device_id": "edge_001", + "status": { + "running": true, + "uptime_seconds": 3600, + "frames_processed": 10000, + "alerts_generated": 5, + "stream_stats": {} + }, + "timestamp": "2026-02-05T10:00:00" +} +``` + +## 五、项目结构 + +``` +service/ +├── app/ +│ ├── __init__.py +│ ├── main.py # FastAPI 入口 +│ ├── config.py # 配置管理 +│ ├── models.py # 数据模型 (SQLAlchemy) +│ ├── schemas.py # 请求/响应模型 (Pydantic) +│ │ +│ ├── api/ # API 路由 (新结构) +│ │ ├── __init__.py +│ │ ├── alerts.py # 告警 API +│ │ ├── work_orders.py # 工单 API +│ │ ├── devices.py # 设备 API +│ │ └── websocket.py # WebSocket +│ │ +│ ├── services/ # 业务服务 +│ │ ├── __init__.py +│ │ ├── alert_service.py # 告警服务 +│ │ ├── work_order_service.py # 工单服务 (新增) +│ │ ├── device_service.py # 设备服务 (新增) +│ │ ├── mqtt_service.py # MQTT 订阅服务 (新增) +│ │ ├── notification_service.py # 通知服务 (新增) +│ │ ├── oss_storage.py # 图片存储 +│ │ └── ai_analyzer.py # AI 分析 +│ │ +│ └── utils/ +│ ├── __init__.py +│ └── logger.py +│ +├── data/ # 数据目录 +├── uploads/ # 上传文件 +├── logs/ # 日志 +├── requirements.txt +├── .env +└── README.md +``` + +## 六、实施步骤 + +### Phase 1: 打通核心链路 (优先) +1. ✅ 评估现有项目 +2. 新增 MQTT 订阅服务 +3. 新增 WebSocket 推送 +4. 端到端联调测试 + +### Phase 2: 工单功能 +5. 工单数据模型 +6. 工单 CRUD API +7. 告警关联工单 + +### Phase 3: 设备监控 +8. 设备数据模型 +9. 心跳监控 +10. 设备状态 API + +### Phase 4: 优化增强 +11. 通知服务 (邮件/企微/钉钉) +12. 权限控制 +13. 性能优化