XW-AIOT/iot-device-management-service
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 新增增强版架构设计文档

Browse Source 
- 定义 MQTT 订阅架构对接 ai_edge
- 设计 WebSocket 实时推送方案
- 规划设备心跳监控流程
- 明确 API 端点设计

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
16337
2026-02-05 13:56:09 +08:00
parent ec03d38920
commit b5c72f73e0
1 changed files with 315 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

315
docs/architecture.md Normal file
View File

@@ -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. 性能优化