# 需求缺口清单

基于 `软件系统说明.docx` 整理。本清单只记录两类内容：

- 文档中已经明确、可作为后续设计输入的事实
- 文档中缺失、会直接阻塞开发或联调的规格项

当前仓库没有源码、接口定义、数据库 schema、CI 或部署配置，因此本清单以产品说明为唯一依据，不补充未被文档证实的实现细节。

## 已确认事实

### 系统边界

- 系统由微信小程序、光子美容仪设备端、腾讯云 IoT/云服务、管理后台组成。
- 小程序与设备通过 `BLE 5.0 GATT` 通信。
- 小程序与云端通过 `HTTPS/MQTT` 通信。
- 设备通过 `MQTT over TLS` 连接腾讯云 IoT Hub。
- 管理后台是独立前端，技术栈为 `uniapp + Vue 3 + uView Plus`，部署到腾讯云静态网站托管。
- 小程序端是微信原生 `WXML / WXSS / JS`，不是 `uniapp`。

### 小程序业务骨架

- 页面包括：首页、护理历史、发现、我的。
- 首次使用流程：扫码 -> 蓝牙授权 -> 设备绑定 -> 获得 7 天试用 -> 确认佩戴 -> 自动扫描 -> 开始治疗。
- 日常使用流程：打开小程序 -> 连接设备 -> 确认佩戴 -> 自动扫描 -> 开始治疗。

### BLE 已知协议事实

- 协议帧格式：帧头 `0xAA 0x55`，随后是长度、类型、数据、XOR 校验。
- 服务 UUID：`FFE0` 设备信息服务，`FFE1` 数据通信服务，`FFE2` OTA 升级服务。

### 云端已知能力

- 云端基础设施包括：`Tencent Cloud IoT Hub`、`SCF`、`MySQL`、`Redis`、`CLS`、`CMQ`。
- 环境划分为三套：开发环境 `IoT Hub + 云函数(测试)`，测试环境 `IoT Hub + 云函数 + MySQL`，生产环境 `IoT Hub + 云函数 + MySQL + Redis`。
- 云函数职责：用户认证、设备绑定/解绑、订阅管理、护理记录同步、设备注册、试用订阅管理、数据统计。

### 数据模型已知名称

- `users`
- `devices`
- `bindings`
- `subscriptions`
- `sessions`
- `treatment_records`
- `pd_data`
- `operation_logs`

### MQTT 已知事实

- 设备上报主题：`$iot/{product_id}/{device_name}/telemetry`
- 设备事件主题：`$iot/{product_id}/{device_name}/event`
- 使用 `CMQ` 做异步处理。
- 护理记录存在异步写入路径。

### 安全已知事实

- 全链路使用 `TLS 1.2+`。
- 设备认证依赖 `DeviceSecret`。
- 用户认证是微信登录 + Token。
- Token 有效期为 7 天。
- 需要敏感数据加密存储、API 鉴权、角色权限、API 级别鉴权。

## 核心缺口

### 1. BLE 协议规格不完整

当前只有帧结构和服务 UUID，无法支持小程序、设备端和测试联调。

缺失项：

- `type` 命令字完整定义
- 请求/响应 payload 结构
- 各字段长度、编码、字节序
- 长度字段计算规则
- XOR 校验计算范围
- 错误码与 ACK/NACK 机制
- 超时、重试、幂等策略
- 主动上报与被动响应的区分
- characteristic UUID 清单
- MTU、分包、粘包处理规则
- 断连重连与会话恢复策略
- OTA 协议、分片、校验、回滚规则
- 佩戴确认规则
- 自动扫描的具体定义
- 治疗开始、暂停、结束、状态同步命令

### 2. 小程序状态机与业务规则不完整

当前文档只描述了高层流程，没有足够的页面行为和异常流程定义。

缺失项：

- 扫码内容定义：二维码中包含什么
- 绑定是否必须扫码
- 用户和设备的绑定约束：一对一、一对多、多对一
- 解绑规则与限制
- 试用订阅规则：按用户还是按设备发放，是否可重复领取
- 订阅有效性校验时机
- 设备未连接、蓝牙拒绝、治疗中断、同步失败等异常流
- 小程序本地缓存与重试机制
- 页面跳转关系与关键空态
- 治疗前、中、后的状态枚举
- 后台切换、来电、锁屏、断蓝牙时的处理规则

### 3. 云端 API 契约缺失

当前只有功能名，没有接口定义，前后端和测试都无法并行推进。

缺失项：

- API 列表和路由
- HTTP 方法
- 请求参数
- 返回结构
- 错误码
- 鉴权方式
- Token 刷新与吊销机制
- 微信登录换取身份的流程
- 绑定/解绑接口规则
- 订阅接口的查询、创建、续期、停用规则
- 护理记录同步接口格式
- 幂等、防重、防刷设计

### 4. 设备注册与 IoT 流程缺失

文档提到设备注册和 `DeviceSecret`，但没有写清注册与认证流程。

缺失项：

- 设备出厂、激活、绑定、上线的完整流程
- `DeviceSecret` 的签发时机和保存方式
- 小程序是否参与设备注册
- IoT 事件如何触发云函数
- 是否使用规则引擎或设备影子
- MQTT 上下行消息结构
- 设备控制指令的 topic 与 payload
- 设备离线、禁用、换绑时的状态管理

### 5. 数据库字段设计缺失

当前只有表名，无法开始建库、写接口或定义查询。

缺失项：

- 每张表的字段列表
- 主键、外键、唯一约束
- 状态枚举
- 时间字段和时区约定
- 审计字段
- 软删/硬删策略
- `sessions` 与 `treatment_records` 的边界
- `pd_data` 数据含义、采样频率、保留周期
- `operation_logs` 的记录范围和保留周期

### 6. 管理后台规格不完整

当前只有模块清单，还不足以支持页面设计和接口定义。

缺失项：

- 管理员登录方式
- 角色定义与权限矩阵
- 页面路由和菜单结构
- 列表页筛选项、排序项、导出格式
- 详情页字段清单
- 仪表盘统计指标口径
- 日志查询维度
- 是否支持设备远程控制

### 7. 安全设计缺实现细节

当前停留在原则层面，无法转为工程方案。

缺失项：

- Token 格式、签名算法、刷新策略
- `DeviceSecret` 存储和轮换方式
- 敏感字段加密范围
- API 防重放、防刷、限流策略
- 后台高权限操作的二次确认要求
- 审计日志保留和防篡改策略
- 隐私数据脱敏要求

### 8. 测试与运维方案缺失

缺少交付和验收所需的执行标准。

缺失项：

- BLE 联调测试方案
- 设备模拟方案
- API 测试样例
- MQTT 联调样例
- 真机测试范围
- 云函数发布流程
- 数据库迁移流程
- CLS 日志规范
- CMQ 重试和死信策略
- 告警、备份、恢复方案
- 验收标准与性能指标

## 歧义点

这些内容在文档中提到，但定义仍然模糊，后续需要先澄清再设计：

- 小程序与云端的 `MQTT` 是直接连接还是仅通过服务端转发。
- “自动扫描”到底指肤质检测、佩戴检测、设备自检，还是其他扫描动作。
- `pd_data` 的 `PD` 含义和数据来源。
- 护理记录“异步写入”是全量异步，还是仅明细异步。
- 管理后台中的“系统设置”是否只管理管理员与权限，还是还包含设备、订阅、公告等全局配置。

## 补规格优先级

建议按以下顺序补充规格，避免阻塞主链路开发：

1. BLE 通信协议明细
2. 小程序与云端 API 契约
3. 数据库表结构设计
4. 设备注册、绑定、订阅规则
5. MQTT 消息规范
6. 小程序状态机与异常流程
7. 管理后台权限与页面规格
8. 安全与运维方案

## 建议补充文档

建议在当前说明基础上继续补以下文档：

- `01-BLE通信协议明细.md`
- `02-小程序业务流程与状态机.md`
- `03-云函数API接口清单.md`
- `04-数据库表结构设计.md`
- `05-IoT设备注册与MQTT消息规范.md`
- `06-管理后台功能与权限设计.md`
- `07-安全与鉴权方案.md`
- `08-测试与验收标准.md`

## 当前结论

当前说明已经足够确定系统边界、主要技术选型和一阶段开发主线，但还不足以直接进入实现。最关键的四个缺口是：

- BLE 协议明细
- API 契约
- 数据库字段设计
- 业务状态机

在这四项没有补齐前，代码实现和联调都将高度依赖猜测，返工风险很高。
