refactor: migrate to Tencent Cloud backend

2026-04-28 22:56:47 +08:00
@@ -0,0 +1,196 @@
+# BLE 通信协议明细
+
+基于 `软件系统说明.docx` 整理。本文档用于把 BLE 通信协议推进到"可联调设计"层，把帧结构、服务、命令表和时序骨架补到足够继续细化的程度。
+
+本文档仍然遵循一个原则：不虚构未被产品说明证实的命令字、UUID 或 payload 值。以下内容中，凡是来源仅为"推导"而非"文档原文确认"的，会标明"待确认"。
+
+## 已确认事实
+
+- 通信方式：`BLE 5.0 GATT`
+- 协议帧格式：帧头 `0xAA 0x55`，随后是长度、类型、数据、XOR 校验
+- 已知服务 UUID：
+  - `FFE0`：设备信息服务
+  - `FFE1`：数据通信服务
+  - `FFE2`：OTA 升级服务
+- 业务流程中至少存在以下设备交互阶段：连接设备、确认佩戴、自动扫描、开始治疗
+
+## 帧结构草案
+
+### 帧总体格式
+
+| 字段 | 偏移 | 长度 | 值域 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `header` | 0 | 2 字节 | `0xAA 0x55` | 文档确认 | 帧头标识 |
+| `length` | 2 | 1 字节 | 待确认 | 文档确认存在，定义待补 | 数据长度 |
+| `type` | 3 | 1 字节 | 待确认 | 文档确认存在，枚举待补 | 命令/数据/事件类型 |
+| `payload` | 4 | N 字节 | 待确认 | 文档确认存在 | 业务载荷 |
+| `checksum` | 4+N | 1 字节 | 待确认 | 文档确认为 XOR | 校验 |
+
+### 必须补齐的帧定义
+
+| 项目 | 当前状态 | 阻塞影响 |
+| --- | --- | --- |
+| `length` 是否包含 `type`、`checksum` | 未定义 | 无法正确解析帧 |
+| `checksum` XOR 计算范围 | 未定义 | 无法正确校验帧 |
+| 多字节字段字节序 | 未定义 | 数值解析错误 |
+| 字符串编码方式 | 未定义 | 文本解析错误 |
+| 最大 payload 长度 | 未定义 | 分包策略无法设计 |
+| MTU 约束 | 未定义 | 传输效率与可靠性 |
+
+### 建议帧计算规则（待确认）
+
+以下为建议方案，非最终定义：
+
+- `length`：建议仅表示 `payload` 的字节长度
+- `checksum`：建议对 `length`、`type`、`payload` 所有字节做 XOR 运算
+- 字节序：建议统一大端序（`Big-Endian`）
+- 字符串：建议统一 `UTF-8`
+
+## 服务与 characteristic 草案
+
+### `FFE0` 设备信息服务
+
+职责：提供设备基础信息。
+
+建议 characteristic 划分（待确认）：
+
+| 建议名称 | 建议属性 | 说明 |
+| --- | --- | --- |
+| `device_info` | `read` | 读取设备型号、固件版本、硬件版本、序列号 |
+| `battery_level` | `read` / `notify` | 电量信息 |
+
+UUID 值：待确认
+
+### `FFE1` 数据通信服务
+
+职责：承担主要业务通信。
+
+建议 characteristic 划分（待确认）：
+
+| 建议名称 | 建议属性 | 说明 |
+| --- | --- | --- |
+| `write_cmd` | `write` / `writeWithoutResponse` | 小程序向设备发送命令 |
+| `notify_data` | `notify` | 设备向小程序上报数据和事件 |
+
+UUID 值：待确认
+
+### `FFE2` OTA 升级服务
+
+职责：固件升级传输。
+
+建议 characteristic 划分（待确认）：
+
+| 建议名称 | 建议属性 | 说明 |
+| --- | --- | --- |
+| `ota_control` | `write` / `notify` | OTA 控制命令和状态通知 |
+| `ota_data` | `writeWithoutResponse` | 升级包分片传输 |
+
+UUID 值：待确认
+
+## 命令表草案
+
+以下命令基于业务流程推导，所有 `type` 值和 `payload` 结构都是待确认的占位。
+
+### 设备信息类
+
+| 建议命令名 | 建议方向 | 建议功能 | type 占位 | payload 请求 | payload 响应 | 待确认 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `GET_DEVICE_INFO` | 小程序 -> 设备 | 读取设备型号、固件版本、序列号 | `0x??` | 空 | 设备信息结构体 | 是 |
+| `GET_BATTERY` | 小程序 -> 设备 | 读取设备电量 | `0x??` | 空 | 电量值 | 是 |
+| `GET_DEVICE_STATUS` | 小程序 -> 设备 | 读取设备当前状态 | `0x??` | 空 | 状态码 | 是 |
+
+### 治疗流程类
+
+| 建议命令名 | 建议方向 | 建议功能 | type 占位 | payload 请求 | payload 响应 | 待确认 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `START_WEARING_CHECK` | 小程序 -> 设备 | 启动佩戴确认 | `0x??` | 空 | 佩戴检测结果 | 是 |
+| `WEARING_CHECK_RESULT` | 设备 -> 小程序 | 上报佩戴确认结果 | `0x??` | 无（通知） | 佩戴状态 | 是 |
+| `START_AUTO_SCAN` | 小程序 -> 设备 | 启动自动扫描 | `0x??` | 空 | 扫描结果 | 是 |
+| `AUTO_SCAN_RESULT` | 设备 -> 小程序 | 上报自动扫描结果 | `0x??` | 无（通知） | 扫描数据 | 是 |
+| `START_TREATMENT` | 小程序 -> 设备 | 开始治疗 | `0x??` | 治疗参数（待确认） | 确认/拒绝 | 是 |
+| `PAUSE_TREATMENT` | 小程序 -> 设备 | 暂停治疗 | `0x??` | 空 | 确认 | 是 |
+| `RESUME_TREATMENT` | 小程序 -> 设备 | 恢复治疗 | `0x??` | 空 | 确认 | 是 |
+| `STOP_TREATMENT` | 小程序 -> 设备 | 结束治疗 | `0x??` | 空 | 治疗摘要 | 是 |
+| `TREATMENT_PROGRESS` | 设备 -> 小程序 | 上报治疗进度 | `0x??` | 无（通知） | 进度数据 | 是 |
+| `TREATMENT_ERROR` | 设备 -> 小程序 | 上报治疗异常 | `0x??` | 无（通知） | 错误码 | 是 |
+
+### OTA 类
+
+| 建议命令名 | 建议方向 | 建议功能 | type 占位 | payload 请求 | payload 响应 | 待确认 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `OTA_START` | 小程序 -> 设备 | 启动 OTA | `0x??` | 固件版本、总大小 | 确认/拒绝 | 是 |
+| `OTA_CHUNK` | 小程序 -> 设备 | 传输分片 | `0x??` | 分片序号、分片数据 | 确认 | 是 |
+| `OTA_VERIFY` | 小程序 -> 设备 | 校验完整固件 | `0x??` | 校验值 | 校验结果 | 是 |
+| `OTA_APPLY` | 小程序 -> 设备 | 应用新固件 | `0x??` | 空 | 结果 | 是 |
+| `OTA_PROGRESS` | 设备 -> 小程序 | 上报 OTA 进度 | `0x??` | 无（通知） | 进度百分比 | 是 |
+
+## 会话时序草案
+
+### 连接后初始化时序（建议）
+
+以下为建议流程，非最终定义：
+
+1. 小程序扫描并连接设备 GATT
+2. 发现 `FFE0`、`FFE1`、`FFE2` 服务
+3. 订阅 `FFE1` 的 `notify_data` 通知
+4. 读取 `FFE0` 的 `device_info` 获取设备基本信息
+5. 根据业务需要发送后续命令
+
+### 治疗主流程时序（建议）
+
+1. 发送 `START_WEARING_CHECK`
+2. 等待 `WEARING_CHECK_RESULT` 通知
+3. 佩戴确认通过后发送 `START_AUTO_SCAN`
+4. 等待 `AUTO_SCAN_RESULT` 通知
+5. 扫描完成后发送 `START_TREATMENT`
+6. 接收 `TREATMENT_PROGRESS` 周期通知
+7. 治疗完成或用户主动停止后发送 `STOP_TREATMENT`
+
+### 异常处理时序（建议）
+
+- 命令超时：建议 3-5 秒未收到响应则重试，最多重试 3 次
+- 断连重连：建议重连后重新订阅 notify 并查询设备当前状态
+- 治疗中断：建议重连后查询是否需要恢复上次治疗会话
+
+## ACK/NACK 机制建议
+
+建议每个命令都存在对应的 ACK 或 NACK 响应（待确认）：
+
+| 响应类型 | 含义 |
+| --- | --- |
+| ACK | 命令已接收并执行成功 |
+| NACK | 命令接收失败或执行失败，附带错误码 |
+
+建议错误码表（待确认）：
+
+| 建议范围 | 含义 |
+| --- | --- |
+| `0x00` | 成功 |
+| `0x01` - `0x0F` | 通用错误 |
+| `0x10` - `0x1F` | 参数错误 |
+| `0x20` - `0x2F` | 设备状态错误 |
+| `0x30` - `0x3F` | 治疗相关错误 |
+| `0x40` - `0x4F` | OTA 相关错误 |
+
+## 分包与粘包建议
+
+当前文档未定义，以下为建议方案（待确认）：
+
+- 建议每个 BLE 写入操作对应一个完整帧
+- 若 payload 超过 MTU 限制，建议在应用层定义分包协议
+- 每个分包建议携带：帧序号、是否最后一包的标记
+- 接收端建议按序号拼装，收到最后一包后校验完整性
+
+## 待确认问题
+
+- 设备绑定是否依赖 BLE 返回的设备唯一标识，还是依赖扫码
+- "确认佩戴"由什么传感器或状态判断，是自动还是手动
+- "自动扫描"具体扫描什么数据
+- 治疗模式、档位、时长是否由小程序下发
+- 治疗记录是否由小程序组装后上传，还是由设备通过 MQTT 直接上报云端
+- OTA 是否通过小程序中转升级包
+- 是否需要设备端主动发起的连接认证或握手
+
+## 当前结论
+
+当前说明已经足够把 BLE 协议推进到"命令表草案"层。所有标为"待确认"的命令字、payload 和 UUID 都需要在下一步被确认或修正。最优先要补齐的是 `FFE1` 下的 characteristic UUID、命令字分配、ACK/NACK 机制和帧计算规则。