iot-device-management-service/README.md

# AI 告警平台后端服务

> ⚠️ **重要**：本项目是芋道大前端中的**告警业务模块后端**，不是独立前端项目。

## 项目定位

**职责**：接收边缘端（ai_edge）告警、保存告警证据、提供 REST API

**不负责**：
- 设备管理（由 IoT 平台负责）
- 推理逻辑（由边缘端 ai_edge 负责）
- 用户体系（复用芋道前端用户体系）

## 在芋道中的定位

```
yudao-ui-admin-vben (芋道前端项目)
├─ 用户管理（已有）
├─ 权限管理（已有）
├─ 系统配置（已有）
└─ 业务模块
    └─ 告警管理（本项目后端对接）
        ├─ 告警列表
        ├─ 告警详情
        ├─ 人工处理
        └─ 大模型分析结果展示
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | FastAPI + Uvicorn |
| 数据库 | SQLite（轻量）或 MySQL |
| 图片存储 | 阿里云 OSS |
| 异步任务 | asyncio（预留 Celery） |

## 快速开始

```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

# 5. 启动服务
python -m app.main
```

## 项目结构

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

## API 文档

启动后访问：http://localhost:8000/docs

## 对接文档

详细的前端集成指南请参考：`docs/芋道前端对接文档.md`

## 边缘端对接示例

在 ai_edge 项目中调用：

```python
import requests
import json

alert_data = {
    "camera_id": "cam-001",
    "roi_id": "roi-01",
    "alert_type": "leave_post",
    "algorithm": "LeavePostAlgorithm",
    "confidence": 85,
    "duration_minutes": 5,
    "trigger_time": "2024-01-20T10:30:00Z",
    "message": "离岗告警"
}

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
)
```