249 行
7.7 KiB
Markdown
249 行
7.7 KiB
Markdown
# 需求缺口清单
|
||
|
||
基于 `软件系统说明.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 契约
|
||
- 数据库字段设计
|
||
- 业务状态机
|
||
|
||
在这四项没有补齐前，代码实现和联调都将高度依赖猜测，返工风险很高。
|