AI识别MQTT实时同步-需求文档

版本：V1.0 编制日期：2026-07-02 状态：初稿

一、背景与目标

1.1 背景

当前线索识别流程已能够将无人机AI识别到的图片、目标类别、识别时间、截图地址、经[坐标已隐藏]等信息写入线索表，并在线索管理中进行展示和处置。现有 device_detection_clues 表已新增 drone_real_time_info 字段，用于保存无人机实时信息，例如经[坐标已隐藏]角度、高度等。

在实际飞行识别过程中，仅保存识别图片和目标检测框还不足以判断物体的真实空间位置。无人机在识别时刻的经[坐标已隐藏]高度、飞行姿态、云台角度、相机变焦、时间戳等信息，需要与AI识别结果一并入库。后续后台线索管理才能根据识别图片、目标对象、无人机位置和姿态信息，判断物体大致位置，并支撑地图展示、核查定位和线索追溯。

本需求要求在无人机AI识别过程中实时获取无人机MQTT属性信息，并在生成线索时将该时刻的无人机实时信息写入数据库。

1.2 需求目标

1.3 参考依据

• DJI 上云 API：Matrice 3D / 3TD 机场上云属性，参考地址：https://developer.dji.com/doc/cloud-api-tutorial/cn/api-reference/dock-to-cloud/mqtt/aircraft/m3d-properties.html
• MQTT实时数据样例：以本次提供的无人机属性消息JSON为准，包含 [坐标已隐藏]height、elevation、attitude_head、attitude_pitch、attitude_roll、gimbal_pitch、gimbal_yaw、zoom_factor、timestamp 等字段。

二、当前问题

2.1 线索缺少识别时刻的无人机状态

当前线索中虽然有图片、缩略图、识别时间、线索来源、线索类型、线索经[坐标已隐藏]等字段，但对无人机实时状态保存不足。若只有图片和目标框，后续很难准确解释目标位置来自哪里，也难以复盘识别时无人机的视角、高度和云台角度。

2.2 目标位置判断缺少必要参数

无人机AI识别目标真实位置时，需要综合以下信息：

2.3 数据追溯链条不完整

后续若出现线索位置偏差，需要能够回溯：

• AI识别到的原始图片
• 识别目标类别、置信度、检测框[坐标已隐藏]识别时刻无人机MQTT实时快照
• 计算线索位置时使用的关键无人机参数

因此，数据库需要同时保存“原始MQTT快照”和“关键结构化字段”。

三、需求范围

3.1 包含范围

• 在无人机AI识别服务运行过程中，接入无人机MQTT属性消息。
• 缓存每架无人机最新一帧实时属性信息。
• AI识别生成目标线索时，读取与识别时间最接近的无人机实时信息。
• 将无人机实时信息原样保存到线索表 drone_real_time_info 字段。
• 从MQTT快照中抽取关键字段，用于线索经[坐标已隐藏]计算、后台展示和问题排查。
• 后台线索管理详情页展示无人机实时信息摘要。

3.2 不包含范围

• 不改变无人机飞控、航线执行、视频拉流逻辑。
• 不改变DJI上云API的消息格式。
• 不在本需求中实现复杂三维投影算法；若需要精确由像素点反算目标坐标，可继续沿用或扩展《AI识别目标经[坐标已隐藏]定位与线索管理需求文档》中的算法方案。
• 不强制前端列表展示全部MQTT字段，完整原始数据以详情/调试信息方式保留。

四、业务流程

4.1 总体流程

DJI上云API / 无人机MQTT属性消息
        |
        v
无人机实时信息订阅服务
        |
        v
按设备ID缓存最新MQTT快照
        |
        +-----------------------------+
                                      |
AI视频/图片识别服务                    |
        |                             |
        v                             |
识别到目标对象、生成截图/检测框          |
        |                             |
        v                             |
根据 device_id + detect_time 匹配无人机实时信息
        |
        v
生成线索记录并写入 device_detection_clues
        |
        v
后台线索管理展示图片、目标、位置、无人机实时信息

4.2 时序要求

无人机MQTT属性消息约每2秒上报一次，因此系统不要求AI识别时间与MQTT时间绝对一致。线索生成时只需匹配识别时间前后2秒内最近的一条MQTT快照，并记录 drone_info_delay_ms 用于后续追溯和问题排查。

五、功能需求

5.1 MQTT实时信息订阅

5.2 AI识别过程绑定无人机实时信息

5.3 线索管理展示

六、数据设计

6.1 现有线索表扩展

表名：device_detection_clues

截图中已新增字段：

该字段用于保存识别时刻匹配到的完整MQTT消息快照，建议保存为JSON字符串，内容不做裁剪，便于后续追溯和算法复算。

6.2 建议补充结构化字段

仅保存 drone_real_time_info 可以满足原始信息追溯，但后台查询、地图定位和统计筛选会不方便。建议同步增加以下结构化字段，或在数据库支持的情况下将 drone_real_time_info 改为 jsonb 并建立关键字段索引。

6.3 字段映射说明

七、接口与同步方案

7.1 MQTT消息处理接口

系统内部新增无人机实时信息处理服务，职责如下：

7.2 AI识别结果建议结构

AI识别服务向线索服务提交结果时，建议包含：

{
  "task_id": "巡查任务ID",
  "device_id": "无人机设备ID",
  "model_id": "AI模型ID",
  "detect_time": "2026-07-02 10:12:30.123",
  "image_path": "/uploads/clues/xxx.jpg",
  "thumbnail_path": "/uploads/clues/xxx_thumb.jpg",
  "payload_index": "81-0-0",
  "detections": [
    {
      "class_name": "疑似违建",
      "confidence": 0.92,
      "bbox": {
        "x1": 320,
        "y1": 240,
        "x2": 580,
        "y2": 460
      }
    }
  ]
}

7.3 线索写入逻辑

1. AI识别服务返回图片和目标对象
2. 线索服务读取 device_id、detect_time、payload_index
3. 查询无人机实时信息缓存或历史快照
4. 判断快照是否在识别时间前后2秒窗口内
5. 写入线索基础字段：图片、模型、目标类型、识别时间等
6. 写入无人机原始快照：drone_real_time_info
7. 写入结构化无人机字段：经[坐标已隐藏]高度、姿态、云台角度等
8. 若目标经[坐标已隐藏]计算成功，写入线索 [坐标已隐藏]
9. 若目标经[坐标已隐藏]未计算成功，保留无人机位置和状态用于后续复核

八、后台线索管理改造

8.1 列表页

列表页保持现有字段不变，可根据需要增加以下展示项：

默认列表不建议展示过多无人机参数，避免影响线索管理主流程。

8.2 详情页

线索详情页新增“无人机实时信息”区块：

8.3 地图定位

地图点位优先级如下：

1. 优先使用AI目标计算后的 `[坐标已隐藏]作为线索目标位置。
2. 如果目标经[坐标已隐藏]为空，但存在无人机实时位置，则可在详情中展示无人机拍摄点位置，并提示“目标位置待计算”。
3. 如果无人机实时信息缺失，则线索仍展示图片和识别结果，但地图定位状态标记为“不完整”。

九、非功能需求

9.1 实时性

9.2 稳定性

• MQTT断连不影响AI识别主流程。
• 无人机实时信息缺失时，线索仍正常入库。
• 原始MQTT JSON字段变化时，结构化字段解析失败不影响原始快照保存。
• 解析异常需要记录日志，便于排查字段格式变化。

9.3 数据安全

• MQTT消息中如包含设备序列号、电池序列号等敏感设备信息，后台默认不在普通页面展示。
• 原始JSON仅管理员或运维调试角色可查看。
• 内外网同步场景下，遵循现有数据交换和安全隔离机制。

十、验收标准

十一、待确认事项

1. MQTT属性消息中用于匹配无人机设备的唯一字段需要确认：使用 device_id、gateway、tid、无人机SN，还是平台内部设备ID。
2. AI识别服务当前是否已携带 payload_index，若未携带，需要确认视频源与载荷编号的映射方式。
3. device_detection_clues 表是否允许继续增加结构化字段，或改用独立扩展表保存无人机实时信息。
4. drone_real_time_info 字段类型建议评估是否由 text 调整为 PostgreSQL jsonb，便于后续查询和索引。
5. 目标真实经[坐标已隐藏]计算是否本期实现。如果本期只保存无人机实时信息，则线索目标位置计算可作为下一阶段增强。
6. MQTT属性消息约每2秒上报一次，本期按识别时间前后2秒内最近快照进行绑定；如现场上报频率发生变化，再同步调整匹配窗口。