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

refactor: 更新项目结构和文档，明确芋道模块定位

Browse Source 
- 添加 .gitignore 文件，排除 .trae/ 目录
- 更新 README.md，明确项目是芋道大前端中的告警模块后端
- 删除 .trae/ 规划文件（已移至 docs/ 对接文档）
This commit is contained in:
16337
2026-02-02 09:51:58 +08:00
parent 12e127f1f0
commit ec03d38920
4 changed files with 150 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
.gitignore vendored Normal file
View File

@@ -0,0 +1,61 @@
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
# Virtual Environment
venv/
env/
ENV/
.venv
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# Trae AI
.trae/
# Logs
logs/
*.log
# Database
data/*.db
data/*.sqlite
# Uploads
uploads/
# Environment
.env
.env.local
.env.*.local
# OS
.DS_Store
Thumbs.db
# PyInstaller
*.manifest
*.spec

54
.trae/documents/plan_20260130_093809.md
View File

@@ -1,54 +0,0 @@
## 安保设备管理 & 事件告警平台实现计划
按照你的架构设计，我将分 8 个阶段实现：
### 阶段 1：项目骨架（1-2 小时）
- 创建目录结构 `security_platform/`
- 配置 `settings.py`（应用名、数据库、Redis）
- 配置 `requirements.txt`（FastAPI、SQLAlchemy 等依赖）
### 阶段 2：数据库层（2-3 小时）
- 创建 `infra/db.py`（SQLAlchemy engine 和 session 管理）
- 创建 `core/device/models.py`（Device 设备模型）
- 创建 `core/event/models.py`（Event 事件模型）
- 创建 Repository 基类和设备/事件仓储实现
### 阶段 3：设备管理模块（2-3 小时）
- 创建 `schemas/device.py`（Pydantic 请求/响应模型）
- 实现 `core/device/service.py`（设备业务逻辑）
- 创建 `api/device.py`（设备 CRUD + 心跳接口）
- 支持对接 IoT 平台的设备注册
### 阶段 4：事件告警模块（2-3 小时）
- 创建 `schemas/event.py`（事件 Pydantic 模型）
- 实现 `core/event/service.py`（事件处理逻辑）
- 实现 `core/event/rules.py`（告警规则引擎）
- 创建 `api/event.py`（事件上报、查询接口）
### 阶段 5：WebSocket 实时推送（1-2 小时）
- 实现 `api/realtime.py`（WebSocket 端点）
- 告警实时推送机制
- 连接管理和消息广播
### 阶段 6：辅助模块（1 小时）
- 创建 `api/health.py`（健康检查）
- 创建 `utils/logger.py`（日志工具）
- 创建 `utils/time.py`（时间工具）
### 阶段 7：部署配置（1 小时）
- 创建 `deploy/Dockerfile`
- 创建 `deploy/docker-compose.yml`
- 创建 `deploy/nginx.conf`
### 阶段 8：文档和测试（1 小时）
- 生成 `README.md`
- 编写基础 API 文档
**预计总工时：11-15 小时**
---
**核心技术栈确认：**
- FastAPI + Uvicorn + Gunicorn
- SQLite（本地）或 MySQL（云端）
- Redis（可选，用于 WebSocket 订阅）
- SQLAlchemy 2.0

151
.trae/documents/plan_20260202_013208.md
View File

@@ -1,151 +0,0 @@
## AI 告警平台开发计划
### 项目定位
**职责**：仅接收边缘端告警、保存告警证据、提供可视化与人工处理能力
**不负责**：设备管理、推理逻辑、用户体系（复用芋道前端用户体系）
---
### 一、边缘端 → 告警平台 数据协议
**传输方式**：multipart/form-data（JSON + 图片文件）
**JSON 字段**：
```json
{
"camera_id": "cam-001",
"roi_id": "roi-01",
"alert_type": "leave_post",
"algorithm": "LeavePostAlgorithm",
"confidence": 0.85,
"duration_minutes": 5,
"trigger_time": "2024-01-20T10:30:00Z",
"message": "离岗告警"
}
```
**图片字段**：`snapshot`（二进制文件）
---
### 二、后端架构（FastAPI）
```
alert_platform/
├── app/
│ ├── main.py # FastAPI 入口
│ ├── config.py # 配置（SQLite + 图片存储路径）
│ ├── models.py # SQLAlchemy 告警模型
│ ├── schemas.py # Pydantic 请求/响应模型
│ ├── api/
│ │ └── alert.py # 告警接收 & 查询接口
│ ├── service/
│ │ ├── alert_service.py # 告警业务逻辑
│ │ └── analyzer.py # 异步大模型分析
│ └── storage.py # 图片存储
├── data/ # SQLite + 图片目录
├── requirements.txt
└── Dockerfile
```
**核心接口**：
| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/v1/alerts` | 接收边缘端告警（multipart/form-data） |
| GET | `/api/v1/alerts` | 查询告警列表（分页 + 筛选） |
| GET | `/api/v1/alerts/{id}` | 告警详情 |
| PUT | `/api/v1/alerts/{id}/handle` | 处理告警（确认/忽略/备注） |
| GET | `/api/v1/alerts/{id}/image` | 获取告警图片 |
| GET | `/api/v1/alerts/statistics` | 告警统计 |
---
### 三、前端架构（芋道 UI）
**在 yudao-ui-admin-vben 中新增模块**：
```
apps/web-antd/src/
├── api/alert/
│ └── alert.ts # 告警 API
├── views/alert/
│ ├── list/
│ │ ├── data.ts # 列表表单/列配置
│ │ └── index.vue # 告警列表页
│ └── detail/
│ ├── data.ts
│ └── index.vue # 告警详情页
└── router/routes/modules/
└── alert.ts # 告警路由
```
**前端功能**：
- 告警列表：时间/类型/状态筛选 + 分页
- 告警详情：图片展示 + 算法信息 + 离岗时长
- 人工处理：确认、忽略、备注操作
- 大模型分析结果展示（可选）
---
### 四、大模型分析（异步）
**流程**：
1. 告警写入数据库后，触发异步任务
2. 任务队列发送图片 + 上下文到大模型服务
3. 大模型返回：风险等级、告警描述、误报建议
4. 结果写入告警记录的 `ai_analysis` 扩展字段
**实现方式**：Python `asyncio` 或 Celery（预留）
---
### 五、技术栈
| 层级 | 技术 |
|------|------|
| 后端框架 | FastAPI + Uvicorn |
| 数据库 | SQLite（轻量）或 MySQL |
| 图片存储 | 本地文件系统 / 对象存储 |
| 前端框架 | Vue 3 + Vben Admin（芋道） |
| 异步任务 | asyncio（预留 Celery） |
---
### 六、开发优先级
**Phase 1（核心）**：
1. 后端告警接收接口（multipart/form-data）
2. 图片存储与访问
3. SQLite 持久化
4. 告警查询接口
**Phase 2（前端）**：
1. 告警列表页
2. 告警详情页
3. 人工处理功能
**Phase 3（增强）**：
1. 异步大模型分析
2. 告警统计图表
3. Docker 部署
---
### 七、与 ai_edge 对接示例
边缘端（ai_edge）调用：
```python
import requests
files = {
'snapshot': ('alert.jpg', image_bytes, 'image/jpeg'),
'data': (None, json.dumps(alert_data), 'application/json')
}
response = requests.post(
"http://alert-platform/api/v1/alerts",
files=files
)
```
---

110
README.md
View File

@@ -1,25 +1,57 @@
# AI 告警平台 # AI 告警平台后端服务
轻量级告警接收与处理平台，接收边缘端告警数据，存储到数据库并提供可视化查询能力。 > ⚠️ **重要**：本项目是芋道大前端中的**告警业务模块后端**，不是独立前端项目。
## 功能特性 ## 项目定位
- 告警接收：支持边缘端通过 multipart/form-data 上报告警 **职责**：接收边缘端（ai_edge）告警、保存告警证据、提供 REST API
- 图片存储：阿里云 OSS 对象存储
- 告警管理：查询、筛选、处理告警 **不负责**：
- 大模型分析：异步告警智能分析 - 设备管理（由 IoT 平台负责）
- 推理逻辑（由边缘端 ai_edge 负责）
- 用户体系（复用芋道前端用户体系）
## 在芋道中的定位
```
yudao-ui-admin-vben (芋道前端项目)
├─ 用户管理（已有）
├─ 权限管理（已有）
├─ 系统配置（已有）
└─ 业务模块
└─ 告警管理（本项目后端对接）
├─ 告警列表
├─ 告警详情
├─ 人工处理
└─ 大模型分析结果展示
```
## 技术栈
| 层级 | 技术 |
|------|------|
| 后端框架 | FastAPI + Uvicorn |
| 数据库 | SQLite（轻量）或 MySQL |
| 图片存储 | 阿里云 OSS |
| 异步任务 | asyncio（预留 Celery） |
## 快速开始 ## 快速开始
```bash ```bash
# 安装依赖 # 1. 激活 yolo 环境
conda activate yolo
# 2. 进入项目目录
cd c:\Users\16337\PycharmProjects\service
# 3. 安装依赖
pip install -r requirements.txt pip install -r requirements.txt
# 配置环境变量 # 4. 配置环境变量
cp .env.example .env cp .env.example .env
# 编辑 .env 文件，配置数据库和 OSS # 编辑 .env 文件，配置阿里云 OSS
# 启动服务 # 5. 启动服务
python -m app.main python -m app.main
``` ```
@@ -28,23 +60,59 @@ python -m app.main
``` ```
alert_platform/ alert_platform/
├── app/ ├── app/
│ ├── main.py # FastAPI 入口 │ ├── main.py # FastAPI 入口 + API 接口
│ ├── config.py # 配置 │ ├── config.py # 配置管理
│ ├── models.py # 数据模型 │ ├── models.py # SQLAlchemy 告警模型
│ ├── schemas.py # Pydantic 模型 │ ├── schemas.py # Pydantic 请求/响应模型
│ ├── api/
│ │ └── alert.py # 告警 API
│ ├── services/ │ ├── services/
│ │ ├── alert_service.py # 告警业务 │ │ ├── alert_service.py # 告警业务逻辑
│ │ └── oss_storage.py # OSS 存储 │ │ ├── oss_storage.py # 阿里云 OSS 上传
│ │ └── ai_analyzer.py # 异步大模型分析
│ └── utils/ │ └── utils/
│ └── logger.py # 日志工具 │ └── logger.py # 日志工具
├── data/ # 数据库目录 ├── docs/
│ └── 芋道前端对接文档.md # 芋道前端集成指南
├── data/ # SQLite 数据库
├── uploads/ # 本地临时存储 ├── uploads/ # 本地临时存储
├── requirements.txt ├── requirements.txt
└── .env.example ├── .env.example
└── .gitignore
``` ```
## API 文档 ## API 文档
启动后访问：http://localhost:8000/docs 启动后访问：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
)
```