# IoT 设备注册与 MQTT 消息规范

基于 `软件系统说明.docx` 整理。本文档用于固定当前已知的 IoT 与 MQTT 事实，并列出设备接入、消息定义和云端处理前必须补齐的规格项。

本文档不虚构未被文档确认的 topic、payload 或接入流程。

## 已确认事实

- 设备接入平台：`Tencent Cloud IoT Hub`
- 设备通过 `MQTT over TLS` 连接 IoT Hub
- 已知上报主题：`$iot/{product_id}/{device_name}/telemetry`
- 已知事件主题：`$iot/{product_id}/{device_name}/event`
- 云端业务组件包含：`SCF`、`MySQL`、`Redis`、`CLS`、`CMQ`
- 护理记录存在异步写入路径
- 云函数职责中包含：设备注册、动态获取 `DeviceSecret`

## 已知接入边界

从当前文档可确认以下边界：

- 设备端不是直接写业务数据库，而是先接入 IoT Hub
- 云端至少存在一条设备消息 -> 云端处理 -> 数据落库的链路
- 设备身份认证依赖 `DeviceSecret`
- 系统同时存在实时设备通信和异步消息处理

## 设备接入流程的最小骨架

当前文档没有给出完整时序，但从已知信息可整理出一条最小流程骨架：

1. 设备具备 `product_id` 和 `device_name`
2. 设备获取或持有 `DeviceSecret`
3. 设备通过 `MQTT over TLS` 连接 IoT Hub
4. 设备向指定 topic 上报 telemetry 和 event
5. 云端处理消息并执行日志、异步、入库等后续动作

## 待补齐的设备注册流程

当前最大缺口是 `DeviceSecret` 和设备注册流程，至少需要明确：

- 设备是在生产阶段预注册，还是首次使用时动态注册
- `DeviceSecret` 是一次性签发还是可轮换
- `DeviceSecret` 由谁调用云函数获取：生产工具、设备端、小程序端，还是后台系统
- 设备首次上线是否需要激活
- 设备注册与用户绑定是否是两个独立阶段
- 设备换绑、禁用、报废时如何处理 IoT 身份

## MQTT topic 已知信息

### 遥测主题

- Topic：`$iot/{product_id}/{device_name}/telemetry`
- 作用：设备业务数据上报

当前缺失：

- payload 结构
- 上报频率
- 是否包含治疗过程数据
- 是否包含传感器原始数据

### 事件主题

- Topic：`$iot/{product_id}/{device_name}/event`
- 作用：设备事件上报

当前缺失：

- 事件类型枚举
- 事件触发条件
- 事件 payload
- 错误事件与普通事件的区分

## 必须补齐的消息规范

### 1. Telemetry 消息

至少需要确认：

- 消息体格式：JSON、二进制或其他格式
- 核心字段
- 时间戳字段
- 设备状态字段
- 治疗相关字段
- 是否包含批量数据
- 是否需要签名或序列号

### 2. Event 消息

至少需要确认：

- 事件类型枚举
- 事件等级
- 事件时间
- 事件附加上下文
- 是否需要重试

### 3. 下行控制消息

当前文档没有明确写出下行 topic，但若系统需要远程控制或同步状态，必须明确：

- 是否存在云端 -> 设备的下发 topic
- 是否存在应答 topic
- 远程指令的触发方：小程序、后台、云端任务
- 指令时效和超时规则

## 消息处理链路待确认

当前只知道使用 `CMQ` 异步处理，至少需要明确：

- IoT Hub 消息如何进入云函数或消息队列
- 哪些消息同步处理，哪些消息异步处理
- 护理记录异步写入的触发条件
- 失败重试策略
- 死信消息处理策略
- 日志打点字段

## 建议补充的消息模板

后续可以按以下模板补齐实际 payload。

### Telemetry 模板

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| 待定义 | 待定义 | 待定义 | 待定义 |

### Event 模板

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| 待定义 | 待定义 | 待定义 | 待定义 |

## 设备状态建议先澄清的枚举

后续设计时建议先统一这些状态的定义：

- 未注册
- 已注册未激活
- 已激活未绑定
- 已绑定
- 在线
- 离线
- 禁用
- 故障

## 待确认问题

- `DeviceSecret` 是否通过云函数动态返回给设备
- 小程序在设备注册链路中扮演什么角色
- 设备是否需要主动上报固件版本、硬件版本、电量、错误状态
- `telemetry` 和 `event` 的边界如何划分
- 后台是否需要通过云端下发控制指令

## 当前结论

当前说明已足够确定 IoT 接入方式和两个基础 MQTT topic，但远不足以支持设备接入开发。最先要补的是设备注册流程、`DeviceSecret` 生命周期、payload 结构和消息处理链路。