jw-beauty/docs/planning/需求缺口清单.md

需求缺口清单

基于 软件系统说明.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 契约
• 数据库字段设计
• 业务状态机

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