iot-device-management-service/docs/architecture.md

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) - 已有，增强

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) - 新增

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) - 新增

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}   # 心跳消息

消息格式：

// 告警消息
{
    "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. 性能优化