jw-beauty/docs/planning/10-开发计划.md

开发计划

基于全部已有资料整理，包括：

• 软件系统说明.docx（根目录 + 开发资料目录两份一致）
• 通信协议_小程序与光子美容仪设备.docx — BLE 协议完整定义
• 通信协议_小程序与腾讯云.docx — HTTP API、MQTT 主题与消息格式、后台 API
• 小程序UI/ — 14 个页面 HTML 原型
• 管理后台UI/ — 10 个页面 HTML 原型

新资料解决了什么

对比之前的 09-待确认决策清单.md，以下问题已被新资料明确回答：

原待确认项	新资料结论
D1 佩戴确认判断方式	设备自动状态上报（0x21），mode_state 含 SCANNING/ACTIVE 等
D2 自动扫描定义	扫描面部（mode_state=0x01 SCANNING），PD 传感器采集各区光功率密度
D3 治疗参数来源	小程序下发：区域掩码、波长、亮度、时长、模式（0x01 命令）
D4 治疗记录上传主体	小程序通过 HTTP API 同步（POST /api/v1/treatment/sync），设备通过 MQTT 上报遥测
D6 设备连接认证/握手	BLE 绑定使用服务器生成的 bind_token，写入 BondInfo characteristic
D7 设备绑定标识	扫码获取 device_id，后端验证后生成 bind_token
M1 小程序是否直接 MQTT	是，小程序通过 MQTT 连接 mqtt://iotcloud.tencent.com:8883
A1 登录凭证	微信 code，后端返回 JWT Token
A2 token 方案	JWT Token，有效期 7 天
A3 token 续期	POST /api/v1/auth/refresh，带 refresh_token
A4 绑定是否扫码	是，扫码获取 device_id
DB4 pd_data 含义	PD 传感器光功率密度数据，分区域采集，含 avg_pd
I5 telemetry/event 边界	telemetry 为周期遥测数据，event 为护理完成/设备异常等事件
S2 设备侧应用层加密	TLS 层加密，绑定使用 bind_token 验证

仍有少量未明确项，但不阻塞主链路开发：

• 订阅支付对接（微信支付流程细节）
• OTA 分片协议具体分包大小
• 管理后台管理员登录方式
• 管理后台多租户/角色矩阵细节

已有代码现状

仓库中已存在三个子系统的代码骨架：

• miniprogram/ — 小程序基础结构，4 个 tabBar 页面，BLE 服务框架（命令字为占位）
• cloud/ — 云函数 auth/device/subscription/record 四组函数（路由和字段为草案）
• admin-console/ — uniapp + Vue 3 + Pinia 后台骨架，7 个页面（基础列表）

开发计划

阶段 1：基础设施与数据层

目标：数据库建表、云函数 API 真实路由、统一中间件

1.1 数据库建表

根据 04-数据库表结构设计.md 和新协议资料，创建 DDL：

• users：openid、union_id、nickname、avatar_url、phone、status
• devices：device_sn → 改为 device_id（8 字节设备唯一 ID）、product_id、device_name、hw_version、fw_version、device_type、status、activated_at
• bindings：user_id、device_id、bind_token、status、bound_at、unbound_at
• subscriptions：user_id、device_id（可选）、type（试用/正式）、plan、status、started_at、expired_at、trial_used、source
• sessions：user_id、device_id、session_id（8 字节）、status、started_at、ended_at
• treatment_records：session_id、user_id、device_id、regions、total_duration_ms、mode、avg_pd、sync_status
• pd_data：session_id、device_id、region_name、pd_value、recorded_at
• operation_logs：operator_type、operator_id、target_type、target_id、action、before_snapshot、after_snapshot、ip_address

1.2 云函数统一框架

• 统一响应格式：{ code, message, data }，错误码与 通信协议_小程序与腾讯云.docx 对齐（1001-3001）
• JWT Token 生成/验证中间件
• MySQL 连接池复用
• 请求日志记录

1.3 认证接口

• POST /api/v1/auth/login — 微信 code 换 token
• POST /api/v1/auth/refresh — Token 续期
• JWT 签发，有效期 7 天

阶段 2：BLE 通信层

目标：小程序 BLE 服务完全对齐协议文档

2.1 重写 BLE 服务模块

基于 通信协议_小程序与光子美容仪设备.docx：

• 帧构建/解析：header + length + type + payload + XOR 校验（校验结果为 0 表示通过）
• 服务 UUID：FFE0/FFE1/FFE2
• Characteristic UUID：FFE3（DeviceInfo Read）、FFE4（Command Write）、FFE5（Status Read+Notify）、FFE6（BondInfo Read+Write）、FFE7-FFE9（OTA）
• 命令字：0x01 设置参数、0x02 启动、0x03 停止、0x04 查询状态、0x05 绑定、0x06 解绑
• 状态字：0x21 状态上报、0x22 ACK、0x31 护理完成、0x32 异常、0x33 绑定成功
• 错误码：0x00-0x0C
• 区域掩码：bit0-6 对应左脸颊到右眼周，全脸 0x7F
• 波长：1=IR、2=R、3=UV、4=Y

2.2 设备绑定流程实现

1. 扫码获取 device_id
2. 调用 POST /api/v1/device/bind，后端返回 bind_token
3. BLE 连接设备，写入 FFE6 BondInfo（0x05 命令，含 user_id + bind_token + timestamp）
4. 设备发送 0x33 绑定成功事件
5. 后端更新 bindings 表

2.3 护理执行流程实现

1. BLE 连接，读取设备状态（0x04）
2. 设置护理参数（0x01）：region_mask、wavelength、brightness、duration_ms、mode
3. 启动护理（0x02）
4. 接收周期状态上报（0x21）：mode_state、remaining_ms、battery、temperature 等
5. 接收护理完成事件（0x31）：session_id、regions、total_duration_ms、avg_pd

阶段 3：云端 API 完整实现

目标：所有接口对齐 通信协议_小程序与腾讯云.docx

3.1 设备接口

• POST /api/v1/device/bind — 绑定设备，生成 bind_token
• POST /api/v1/device/unbind — 解绑设备，BLE 发送 0x06 命令
• GET /api/v1/device/list — 用户绑定设备列表
• GET /api/v1/device/{device_id} — 设备详情

3.2 订阅接口

• GET /api/v1/subscription — 当前订阅状态
• POST /api/v1/subscription/purchase — 购买订阅（含支付参数）
• POST /api/v1/subscription/verify — 验证支付
• 试用自动发放：绑定成功后自动创建 7 天试用

3.3 护理记录接口

• POST /api/v1/treatment/sync — 同步护理记录（含 session_id、regions、total_duration_ms、avg_pd）
• GET /api/v1/treatment/history — 分页查询历史记录

3.4 用户接口

• GET /api/v1/user/profile — 获取用户信息
• PUT /api/v1/user/profile — 更新用户信息

阶段 4：MQTT 消息处理

目标：设备 MQTT 接入与云端消息处理

4.1 MQTT 主题实现

设备主题：

• $iot/{product_id}/{device_name}/telemetry — 遥测数据（QoS 0）
• $iot/{product_id}/{device_name}/status — 状态上报（QoS 1）
• $iot/{product_id}/{device_name}/event — 事件（护理完成、设备异常）（QoS 1）
• $iot/{product_id}/{device_name}/control — 下发控制指令（QoS 1）
• $iot/{product_id}/{device_name}/ota — OTA 推送（QoS 1）

用户主题：

• users/{user_id}/subscription — 订阅状态变更通知
• users/{user_id}/devices — 设备列表更新
• users/{user_id}/notification — 推送通知

4.2 消息处理

• telemetry 消息：解析 JSON，写入 pd_data 表
• event 消息：护理完成写入 treatment_records，设备异常记日志
• control 下发：小程序或后台通过云端下发控制指令到设备

阶段 5：小程序 UI 完整实现

目标：14 个页面对齐 UI 设计稿

5.1 页面清单（按 UI 原型）

页面	UI 文件	关键功能
授权登录	01_授权登录.html	微信登录授权
扫码绑定	02_扫码绑定.html	扫码获取 device_id
蓝牙连接	03_蓝牙连接.html	BLE 扫描连接
绑定成功	04_绑定成功.html	绑定完成 + 试用发放
确认佩戴	05_确认佩戴.html	佩戴状态检测
首页	06_首页.html	设备状态 + 护理入口
护理设置	06a_护理设置.html	区域、波长、亮度、时长、模式设置
自动扫描	07_自动扫描.html	PD 传感器扫描
护理中	08_护理中.html	实时状态、进度、剩余时间
护理完成	09_护理完成.html	完成摘要 + 记录同步
订阅提示	10_订阅提示.html	无订阅时引导
订阅套餐	11_订阅套餐.html	套餐选择 + 购买
订阅成功	12_订阅成功.html	购买完成确认
我的	13_我的.html	用户信息、设备、订阅
护理记录	14_护理记录.html	历史记录列表

5.2 小程序 MQTT 集成

• 连接配置：mqtt://iotcloud.tencent.com:8883，ClientID user_{user_id}
• 订阅用户主题接收订阅状态变更和设备列表更新
• 接收实时遥测数据展示

阶段 6：管理后台完整实现

目标：10 个页面对齐 UI 设计稿

6.1 页面清单

页面	UI 文件	关键功能
登录页	10_登录页.html	管理员登录
仪表盘	01_仪表盘.html	用户/设备/治疗/订阅统计
设备管理	02_设备管理.html	设备列表、筛选、在线状态
设备详情	08_设备详情.html	设备信息、绑定记录、远程控制
用户管理	03_用户管理.html	用户列表
用户详情	09_用户详情.html	用户信息、绑定、订阅、治疗记录
订阅管理	04_订阅管理.html	订阅列表、创建、续期
护理记录	05_护理记录.html	治疗记录查询、数据导出
操作日志	06_操作日志.html	日志查询、筛选
系统设置	07_系统设置.html	管理员管理、权限配置

6.2 后台 API

对齐 通信协议_小程序与腾讯云.docx 第七章：

• GET /api/v1/admin/devices — 设备列表（分页）
• GET /api/v1/admin/devices/{device_id} — 设备详情
• POST /api/v1/admin/devices/{device_id}/command — 远程控制
• GET /api/v1/admin/users — 用户列表（分页）
• GET /api/v1/admin/users/{user_id} — 用户详情
• GET /api/v1/admin/subscriptions — 订阅列表（分页）
• POST /api/v1/admin/subscriptions — 创建订阅
• GET /api/v1/admin/logs — 操作日志（按类型、时间筛选）

阶段 7：OTA 升级

目标：固件升级完整链路

• OTA 服务使用 FFE2：FFE7（控制）、FFE8（数据）、FFE9（状态通知）
• 小程序检查新版本
• 分包传输固件
• 设备校验并重启
• 后台 OTA 管理入口

阶段 8：安全加固与测试

• 敏感数据加密存储
• API 防重放、限流
• 操作审计完善
• 端到端测试覆盖主链路
• BLE 联调测试
• MQTT 联调测试
• 后台功能测试

建议执行顺序

1. 阶段 1 — 数据库 + 云函数框架（1-2 天）
2. 阶段 2 — BLE 通信重写（2-3 天）
3. 阶段 3 — 云端 API 实现（2-3 天）
4. 阶段 5 — 小程序 UI 对齐设计稿（3-5 天）
5. 阶段 4 — MQTT 消息处理（1-2 天）
6. 阶段 6 — 管理后台 UI 对齐设计稿（2-3 天）
7. 阶段 7 — OTA（1-2 天）
8. 阶段 8 — 安全与测试（2-3 天）

总计约 14-23 天。

需要立即更新的事项

新资料落地后，以下文件需要同步更新：

• 01-BLE通信协议明细.md — 用真实命令字、UUID、payload 替换占位
• 03-云函数API接口清单.md — 用真实路由和字段替换草案
• 04-数据库表结构设计.md — 用 DDL 替换字段草案，增加 pd_data 详情
• 09-待确认决策清单.md — 标记已解决的条目，更新剩余项
• miniprogram/services/ble.js — 用真实命令字和 UUID 重写
• cloud/functions/*/index.js — 用真实路由和字段重写
• admin-console/src/pages/ — 对齐 UI 设计稿重写页面