docs: 更新 README，反映当前架构和功能

- 更新系统架构图（MQTT订阅 + WebSocket推送） - 添加完整的 API 接口文档 - 添加 MQTT 消息格式说明 - 更新项目结构说明 - 添加与 wvp-platform 集成说明 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-05 14:48:33 +08:00
parent a6697331df
commit df9dcd6f01
1 changed files with 170 additions and 78 deletions
--- a/README.md
+++ b/README.md
@@ -1,118 +1,210 @@
 # AI 告警平台后端服务

-> ⚠️ **重要**：本项目是芋道大前端中的**告警业务模块后端**，不是独立前端项目。
+基于 FastAPI 的 AI 告警接收与管理平台，支持 MQTT 告警订阅、WebSocket 实时推送、设备心跳监控。

-## 项目定位
+## 功能特性

-**职责**：接收边缘端（ai_edge）告警、保存告警证据、提供 REST API
+- **MQTT 告警订阅**：自动订阅边缘设备告警消息（`edge/alert/#`）
+- **WebSocket 实时推送**：告警实时推送到前端
+- **设备心跳监控**：监控边缘设备在线状态
+- **REST API**：告警查询、处理、统计等完整接口
+- **告警去重**：基于时间窗口的告警去重机制

-**不负责**：
- 设备管理（由 IoT 平台负责）
- 推理逻辑（由边缘端 ai_edge 负责）
- 用户体系（复用芋道前端用户体系）
-
-## 在芋道中的定位
+## 系统架构

 ```
-yudao-ui-admin-vben (芋道前端项目)
-├─ 用户管理（已有）
-├─ 权限管理（已有）
-├─ 系统配置（已有）
-└─ 业务模块
-    └─ 告警管理（本项目后端对接）
-        ├─ 告警列表
-        ├─ 告警详情
-        ├─ 人工处理
-        └─ 大模型分析结果展示
+┌─────────────────────────────────────────────────────────────┐
+│                    AI 告警平台架构                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────┐     MQTT      ┌──────────────────────┐   │
+│  │  ai_edge     │──────────────→│  EMQX Broker         │   │
+│  │  边缘推理    │  edge/alert/# │                      │   │
+│  └──────────────┘               └──────────┬───────────┘   │
+│                                            │               │
+│                                   MQTT Subscribe           │
+│                                            ▼               │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │              本服务 (FastAPI)                         │  │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │  │
+│  │  │ MqttService │  │AlertService │  │DeviceService│   │  │
+│  │  │ 消息订阅    │→ │ 告警处理    │  │ 心跳监控    │   │  │
+│  │  └─────────────┘  └──────┬──────┘  └─────────────┘   │  │
+│  │                          │                            │  │
+│  │                          ▼                            │  │
+│  │  ┌─────────────┐  ┌─────────────┐                    │  │
+│  │  │ WebSocket   │← │  Database   │                    │  │
+│  │  │ 实时推送    │  │  SQLite     │                    │  │
+│  │  └──────┬──────┘  └─────────────┘                    │  │
+│  └─────────│────────────────────────────────────────────┘  │
+│            │                                               │
+│            ▼                                               │
+│  ┌──────────────┐                                          │
+│  │   前端/AIOT  │                                          │
+│  │   主平台     │                                          │
+│  └──────────────┘                                          │
+└─────────────────────────────────────────────────────────────┘
 ```

 ## 技术栈

-| 层级 | 技术 |
+| 组件 | 技术 |
 |------|------|
-| 后端框架 | FastAPI + Uvicorn |
-| 数据库 | SQLite（轻量）或 MySQL |
-| 图片存储 | 阿里云 OSS |
-| 异步任务 | asyncio（预留 Celery） |
+| Web 框架 | FastAPI + Uvicorn |
+| 消息队列 | MQTT (paho-mqtt) |
+| 实时推送 | WebSocket |
+| 数据库 | SQLite / MySQL |
+| ORM | SQLAlchemy |
+| 配置管理 | Pydantic Settings + YAML |

 ## 快速开始

+### 1. 安装依赖
+
 ```bash
-# 1. 激活 yolo 环境
-conda activate yolo
-
-# 2. 进入项目目录
-cd c:\Users\16337\PycharmProjects\service
-
-# 3. 安装依赖
 pip install -r requirements.txt
+```

-# 4. 配置环境变量
-cp .env.example .env
-# 编辑 .env 文件，配置阿里云 OSS
+### 2. 配置服务

-# 5. 启动服务
+编辑 `config/config.yaml`：
+
+```yaml
+app:
+  name: "AI Alert Platform"
+  debug: true
+  host: "0.0.0.0"
+  port: 8000
+
+database:
+  url: "sqlite:///./data/alerts.db"
+
+mqtt:
+  enabled: true
+  host: "127.0.0.1"
+  port: 1883
+  username: ""
+  password: ""
+  topic_alert: "edge/alert/#"
+  topic_heartbeat: "edge/alert/heartbeat/#"
+```
+
+### 3. 启动服务
+
+```bash
+# 开发模式（自动重载）
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# 生产模式
 python -m app.main
 ```

+### 4. 访问 API 文档
+
+启动后访问：http://localhost:8000/docs
+
 ## 项目结构

 ```
-alert_platform/
+service/
 ├── app/
-│   ├── main.py              # FastAPI 入口 + API 接口
-│   ├── config.py            # 配置管理
-│   ├── models.py            # SQLAlchemy 告警模型
+│   ├── main.py              # FastAPI 入口 + 路由
+│   ├── config.py            # 配置管理（YAML + 环境变量）
+│   ├── models.py            # SQLAlchemy 数据模型
 │   ├── schemas.py           # Pydantic 请求/响应模型
-│   ├── services/
-│   │   ├── alert_service.py # 告警业务逻辑
-│   │   ├── oss_storage.py   # 阿里云 OSS 上传
-│   │   └── ai_analyzer.py   # 异步大模型分析
-│   └── utils/
-│       └── logger.py        # 日志工具
-├── docs/
-│   └── 芋道前端对接文档.md   # 芋道前端集成指南
+│   └── services/
+│       ├── mqtt_service.py  # MQTT 订阅服务
+│       ├── alert_service.py # 告警业务逻辑
+│       └── storage.py       # 存储服务
+├── config/
+│   └── config.yaml          # 配置文件
 ├── data/                    # SQLite 数据库
-├── uploads/                 # 本地临时存储
+├── logs/                    # 日志文件
+├── docs/                    # 文档
 ├── requirements.txt
-├── .env.example
-└── .gitignore
+└── README.md
 ```

-## API 文档
+## API 接口

-启动后访问：http://localhost:8000/docs
+### 告警管理

-## 对接文档
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/v1/alerts` | 告警列表（分页、筛选） |
+| GET | `/api/v1/alerts/{id}` | 告警详情 |
+| PUT | `/api/v1/alerts/{id}/handle` | 处理告警 |
+| GET | `/api/v1/alerts/statistics` | 告警统计 |

-详细的前端集成指南请参考：`docs/芋道前端对接文档.md`
+### 设备管理

-## 边缘端对接示例
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/v1/devices` | 设备列表 |
+| GET | `/api/v1/devices/{id}` | 设备详情 |
+| GET | `/api/v1/devices/statistics` | 设备统计 |

-在 ai_edge 项目中调用：
+### WebSocket

-```python
-import requests
-import json
+| 路径 | 说明 |
+|------|------|
+| `/ws/alerts` | 告警实时推送 |

-alert_data = {
-    "camera_id": "cam-001",
-    "roi_id": "roi-01",
+### 健康检查
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 服务健康状态 |
+
+## MQTT 消息格式
+
+### 告警消息（边缘端发布）
+
+Topic: `edge/alert/{camera_id}/{roi_id}`
+
+```json
+{
+  "camera_id": "cam_001",
+  "roi_id": "roi_001",
+  "device_id": "edge_device_001",
  "alert_type": "leave_post",
-    "algorithm": "LeavePostAlgorithm",
-    "confidence": 85,
-    "duration_minutes": 5,
-    "trigger_time": "2024-01-20T10:30:00Z",
-    "message": "离岗告警"
+  "algorithm": "YOLO",
+  "confidence": 0.92,
+  "duration_minutes": 15,
+  "trigger_time": "2026-02-05T12:00:00",
+  "message": "检测到离岗行为",
+  "bbox": [100, 100, 300, 400]
 }
-
-files = {
-    "snapshot": ("alert.jpg", image_bytes, "image/jpeg"),
-    "data": (None, json.dumps(alert_data), "application/json"),
-}
-
-response = requests.post(
-    "http://localhost:8000/api/v1/alerts",
-    files=files
-)
 ```
+
+### 心跳消息（边缘端发布）
+
+Topic: `edge/alert/heartbeat/{device_id}`
+
+```json
+{
+  "device_id": "edge_device_001",
+  "status": "online",
+  "uptime": 3600,
+  "frames_processed": 10000,
+  "alerts_generated": 5,
+  "timestamp": "2026-02-05T12:00:00"
+}
+```
+
+## 与 wvp-platform 集成
+
+本服务与 wvp-platform（视频监控平台）配合使用：
+
+1. **wvp-platform**：管理摄像头、配置 ROI 区域、推送算法配置
+2. **ai_edge**：接收配置、执行推理、上报告警
+3. **本服务**：接收告警、存储管理、实时推送
+
+## 环境要求
+
+- Python 3.8+
+- MQTT Broker（推荐 EMQX）
+
+## License
+
+MIT