refactor: migrate to Tencent Cloud backend

docs/planning/09-待确认决策清单.md

@@ -0,0 +1,111 @@
+# 待确认决策清单
+
+本清单汇总自所有规格文档中的"待确认问题"和"歧义点"，按主题归并去重。
+
+每条标注来源文档和阻塞范围，方便定位和分工。
+
+## 设备与 BLE
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| D1 | "确认佩戴"由什么传感器或状态判断，是自动还是手动 | 01-BLE | BLE 命令定义、小程序 UI |
+| D2 | "自动扫描"具体扫描什么：肤质检测、佩戴检测、设备自检，还是其他 | 01-BLE, 需求缺口 | BLE 命令定义、治疗参数 |
+| D3 | 治疗模式、档位、时长是否由小程序下发 | 01-BLE | BLE payload 定义 |
+| D4 | 治疗记录由小程序组装上传，还是设备通过 MQTT 直接上报云端 | 01-BLE, 03-API | 护理记录接口、数据库写入链路 |
+| D5 | OTA 是否通过小程序中转升级包 | 01-BLE | OTA 命令流程 |
+| D6 | 是否需要设备端主动发起的连接认证或握手 | 01-BLE | BLE 连接时序 |
+| D7 | 设备绑定是否依赖 BLE 返回的设备唯一标识，还是依赖扫码 | 01-BLE | 绑定流程 |
+| D8 | 设备是否需要主动上报固件版本、硬件版本、电量、错误状态 | 05-IoT | telemetry payload 设计 |
+
+## 小程序业务
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| M1 | 小程序是否直接使用 MQTT，还是仅通过 HTTPS API | 02-小程序, 需求缺口 | 通信架构、离线策略 |
+| M2 | 首页是否需要展示实时传感器数据 | 02-小程序 | 首页 UI、BLE 通知频率 |
+| M3 | 护理历史中的"统计"是本地统计还是云端聚合 | 02-小程序 | API 设计、前端逻辑 |
+| M4 | 发现页内容是否来自 CMS 或静态配置 | 02-小程序 | 后台功能范围 |
+| M5 | 我的页面是否包含售后、反馈、设置等附加入口 | 02-小程序 | 页面结构 |
+| M6 | 扫码内容是设备 SN、激活码、绑定码还是 URL | 02-小程序 | 绑定流程 |
+| M7 | 蓝牙授权是否还需要定位权限 | 02-小程序 | 小程序权限声明 |
+| M8 | 一人多设备/一设备多用户规则 | 02-小程序, 04-DB | 数据库关系、绑定逻辑 |
+| M9 | 试用按用户发还是按设备发，是否可重复领取 | 02-小程序, 03-API | 订阅模型、试用逻辑 |
+| M10 | 试用到期后是否自动降级为不可治疗 | 03-API | 订阅校验逻辑 |
+
+## 云端 API 与鉴权
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| A1 | 小程序提交给云端的是 `code` 还是其他凭证 | 03-API | 登录接口实现 |
+| A2 | 云端返回自有 token 还是复用微信态 | 03-API | 认证架构 |
+| A3 | Token 7 天有效期是否支持续期 | 03-API, 07-安全 | Token 生命周期 |
+| A4 | 绑定是否必须基于扫码 | 03-API | 绑定接口参数 |
+| A5 | 绑定时是否校验设备在线状态 | 03-API | 绑定逻辑 |
+| A6 | 重复绑定、换绑、解绑是否有限制 | 03-API | 绑定逻辑 |
+| A7 | 试用发放时机是否严格绑定在首次绑定成功后 | 03-API | 试用发放触发条件 |
+| A8 | 护理记录同步是实时提交还是治疗结束后提交 | 03-API | 同步策略、UI 交互 |
+| A9 | 异步写入与接口返回成功的关系 | 03-API | 前端状态管理 |
+| A10 | 小程序 token 是否也影响设备绑定授权 | 07-安全 | 鉴权模型 |
+
+## IoT 与设备注册
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| I1 | `DeviceSecret` 是否通过云函数动态返回给设备 | 05-IoT | 设备注册流程 |
+| I2 | 小程序在设备注册链路中扮演什么角色 | 05-IoT | 注册时序 |
+| I3 | 设备注册调用方是生产工具、设备首次上线，还是小程序触发 | 03-API, 05-IoT | 注册接口设计 |
+| I4 | `DeviceSecret` 是否只签发一次 | 03-API, 05-IoT | 密钥管理策略 |
+| I5 | `telemetry` 和 `event` 的边界如何划分 | 05-IoT | MQTT payload 设计 |
+| I6 | 后台是否需要通过云端下发控制指令 | 05-IoT | 下行 topic 设计 |
+
+## 管理后台
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| B1 | 后台管理员如何登录 | 06-后台 | 认证实现 |
+| B2 | 是否存在超级管理员 | 06-后台 | 权限模型 |
+| B3 | 是否需要多组织或多租户隔离 | 06-后台 | 数据隔离设计 |
+| B4 | 仪表盘统计口径是实时聚合还是离线任务 | 06-后台 | 统计接口实现 |
+| B5 | 数据导出是否受角色限制 | 06-后台 | 权限细化 |
+| B6 | 系统设置是否只管理管理员与权限，还是还包含设备、订阅、公告等 | 06-后台, 需求缺口 | 后台功能范围 |
+
+## 安全
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| S1 | 后台是否与小程序共用用户体系 | 07-安全 | 用户模型 |
+| S2 | 是否需要设备侧应用层签名或加密 | 07-安全 | BLE 协议安全层 |
+| S3 | 是否有合规或审计的特殊要求 | 07-安全 | 安全方案范围 |
+
+## 数据库
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| DB1 | `users` 与 `devices` 绑定约束：一对一还是多对多 | 04-DB | bindings 表设计 |
+| DB2 | `subscriptions` 归属用户、设备还是同时关联两者 | 04-DB | subscriptions 表设计 |
+| DB3 | `sessions` 与 `treatment_records` 是一对一还是一对多 | 04-DB | 表关系设计 |
+| DB4 | `pd_data` 的含义、数据来源、是否高频时序数据 | 04-DB, 需求缺口 | 存储方案选择 |
+
+## 测试与验收
+
+| # | 问题 | 来源 | 阻塞 |
+| --- | --- | --- | --- |
+| T1 | 小程序是否有最低微信版本要求 | 08-测试 | 兼容性测试范围 |
+| T2 | 设备联调是否依赖特定手机机型 | 08-测试 | 测试设备准备 |
+| T3 | 护理记录异步写入的最终一致性验收口径 | 08-测试 | 验收标准 |
+| T4 | 后台导出是否属于第一阶段验收范围 | 08-测试 | MVP 范围 |
+
+## 建议对齐优先级
+
+以下问题同时阻塞多个模块，建议最先对齐：
+
+1. **D2** 自动扫描定义 — 阻塞 BLE 命令 + 治疗参数 + 小程序 UI
+2. **D4** 治疗记录上传主体 — 阻塞 API + 数据库 + MQTT + 小程序
+3. **M1** 小程序是否直接 MQTT — 阻塞整体通信架构
+4. **M9** 试用按用户还是按设备 — 阻塞订阅模型 + 数据库 + API
+5. **DB4** pd_data 含义 — 阻塞存储方案
+6. **I3** 设备注册调用方 — 阻塞注册流程 + API + 密钥管理
+7. **A2** token 方案 — 阻塞认证架构
+8. **D1** 佩戴确认判断方式 — 阻塞 BLE 命令 + UI
+
+建议按此顺序逐一确认，每确认一项就同步更新对应的规格文档。

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

@@ -0,0 +1,265 @@
+# 开发计划
+
+基于全部已有资料整理，包括：
+- `软件系统说明.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 设计稿重写页面

docs/planning/11-剩余缺失信息清单.md

@@ -0,0 +1,51 @@
+# 剩余缺失信息清单
+
+基于全部已有资料整理。以下问题在新开发资料中仍未明确，按阻塞程度排序。
+
+## 阻塞主链路开发
+
+| # | 问题 | 影响 | 建议处理方式 |
+| --- | --- | --- | --- |
+| C1 | DeviceSecret 签发流程：何时签发、由谁调用、是否可轮换 | 设备无法注册接入 IoT Hub | 先用腾讯云 IoT 控制台手动注册设备，后续再自动化 |
+| C2 | 订阅支付对接：微信支付商户配置、payment_params 具体格式、支付回调地址 | 用户无法购买正式订阅 | 第一版只实现试用，购买功能后续对接微信支付 |
+| C3 | refresh_token 机制：`/auth/refresh` 需要 refresh_token，但登录响应字段中只有 token | Token 续期无法实现 | 先用 token 直接续期，后续补 refresh_token 双 token 方案 |
+
+## 阻塞部分功能
+
+| # | 问题 | 影响 | 建议处理方式 |
+| --- | --- | --- | --- |
+| P1 | 一人多设备/一设备多用户规则：API 用 `device/list` 复数形式，但未明确限制 | 绑定逻辑不确定 | 先实现一对一，后续按需放开 |
+| P2 | 试用按用户还是按设备发放：订阅消息含 `trial_used` 暗示按用户，但未明确 | 试用发放逻辑不确定 | 先按用户发放，trial_used 字段标记是否已用 |
+| P3 | 试用到期后是否自动降级：设备错误码 0x06 ERR_NO_SUBSCRIPTION 暗示会校验 | 订阅校验逻辑不确定 | 先实现：到期后设备端返回无订阅错误，小程序引导购买 |
+| P4 | OTA 分包策略：协议定义了 FFE7/FFE8/FFE9，但未给出具体分包大小和传输规则 | OTA 无法实现 | 先跳过 OTA，后续与固件团队对齐 |
+| P5 | 后台管理员认证方式：有登录页 UI，但未定义用什么方式登录（账号密码/微信扫码/SSO） | 后台登录无法实现 | 先实现账号密码登录 |
+| P6 | 后台权限矩阵：角色定义、菜单权限、API 权限均未定义 | 权限控制无法实现 | 先实现单角色无权限区分，后续补角色矩阵 |
+| P7 | 小程序 MQTT 库选型：微信小程序使用 MQTT 需确认库 | 实时推送无法实现 | 调研 wx-mqtt 或通过 WebSocket 转 MQTT |
+
+## 低阻塞可后续迭代
+
+| # | 问题 | 影响 | 建议处理方式 |
+| --- | --- | --- | --- |
+| L1 | 护理历史"统计"是本地还是云端聚合 | API 设计 | 看 UI 原型 14_护理记录.html 推断 |
+| L2 | 发现页内容来源：CMS 还是静态配置 | 后台功能范围 | UI 原型中未出现发现页，优先级最低 |
+| L3 | 我的页面是否有售后、反馈、设置入口 | 页面结构 | 看 UI 原型 13_我的.html 推断 |
+| L4 | 蓝牙授权是否需要定位权限 | 小程序权限声明 | iOS 需要，建议直接加上 |
+| L5 | 绑定时是否校验设备在线状态 | 绑定逻辑 | 先不校验，后续加上 |
+| L6 | 重复绑定/换绑限制 | 绑定逻辑 | 先实现基础逻辑 |
+| L7 | 异步写入与接口返回关系 | 前端状态管理 | sync 接口同步返回 record_id |
+| L8 | 固件版本管理和存储规则 | OTA 管理 | 后续定义 |
+| L9 | 仪表盘统计口径：实时聚合还是离线任务 | 统计接口实现 | 先用 SQL 实时聚合，数据量大再改离线 |
+| L10 | 数据导出是否受角色限制 | 权限细化 | 先不受限 |
+| L11 | 系统设置范围：是否包含公告、字典、设备参数配置 | 后台功能范围 | 先只做管理员管理 |
+| L12 | 多组织/多租户隔离 | 数据隔离 | 第一版不需要 |
+| L13 | 是否有合规或审计特殊要求 | 安全方案 | 按通用标准实现 |
+| L14 | 小程序最低微信版本要求 | 兼容性测试 | 使用基础库 2.25.0+ |
+| L15 | 设备联调是否依赖特定手机机型 | 测试准备 | 联调时确认 |
+
+## 总结
+
+- 主链路阻塞项：3 条（C1-C3）
+- 部分功能阻塞项：7 条（P1-P7）
+- 低阻塞可迭代项：15 条（L1-L15）
+
+主链路开发已可启动，C1-C3 有临时替代方案。P1-P7 建议在对应阶段开始前确认。L1-L15 不阻塞任何阶段，可边做边补。

docs/planning/PROGRESS.md

@@ -0,0 +1,124 @@
+# Hox 光子美容仪项目 — 工作进度交接
+
+## 项目概况
+微信小程序 + 云开发后台 + uniapp 管理后台，产品是光子美容仪。
+
+- 小程序 appid: `wxc4045074ef298510`
+- 项目名: `hox-beauty`
+- 部署: 微信云开发（免费 Tier）
+- 主色: `#E6508C`（粉）、`#DCB982`（金）、`#52c41a`（绿）
+
+## 目录结构
+```
+miniprogram/                    # 微信小程序
+  app.js / app.json / app.wxss  # 入口 + 全局样式 + tabBar
+  cloud-functions/              # 6 个云函数（auth/device/subscription/treatment/user/admin）
+  pages/                        # 15 个页面
+  services/                     # ble.js + mqtt.js
+  utils/                        # request.js（双模式：云函数/HTTP）+ mock.js
+
+admin-console/                  # uniapp + Vue 3 管理后台
+  src/pages/                    # 10 个页面
+  src/components/AdminLayout.vue # 侧边栏布局
+  src/utils/request.js          # mock 模式（USE_MOCK=true）
+
+cloud/functions/                # 旧版 SCF 格式（已废弃，保留参考）
+```
+
+## 已完成的工作
+
+### 基础架构
+- 云开发初始化，6 个云函数部署完成
+- 5 个数据库集合：users, bindings, subscriptions, treatment_records, operation_logs（权限：仅创建者可读写）
+- request.js 双模式：`USE_CLOUD=true` 走 `wx.cloud.callFunction()`，false 走 HTTP
+- 登录简化：云函数用 `cloud.getWXContext()` 自动获取 openid，无需手动 `wx.login()`
+
+### 小程序页面（15 个）
+- login（手机号登录）
+- index（首页：设备状态 + 开始护理 + 设备管理）
+- scan（扫码/手动输入绑定设备）
+- bind-success（绑定成功 + 7天试用提示）
+- ble-connect（BLE 蓝牙连接，15秒超时）
+- treatment-setup（护理参数设置）
+- wear-check（佩戴检测）
+- treating（护理进行中）
+- treating-complete（护理完成）
+- history（历史记录，从云端拉取）
+- subscribe-plans（订阅方案选择）
+- subscribe-prompt（订阅引导）
+- subscribe-success（订阅成功）
+- profile（个人中心 + 退出登录）
+- device-info（设备信息详情）
+
+### 设备管理
+- 首页「设备管理」按钮：已绑定时弹出操作菜单（解绑）
+- 解绑流程：断开 BLE → 调云函数 → 清空本地状态
+- 手动输入绑定：绑定成功后直接跳 bind-success，不再跳 ble-connect
+- 已绑定设备重复绑定时提示「已绑定设备」并返回
+
+### 管理后台（10 个页面）
+- login / dashboard / device / device-detail / user / user-detail / subscription / record / log / settings
+- request.js 有 mock 模式（`USE_MOCK=true`），所有页面可用 mock 数据开发
+- admin 云函数有 9 个 action：dashboard / devices / device_detail / device_unbind / users / user_detail / subscriptions / records / logs
+
+### 已清理
+- 删除了无用的 `miniprogram/pages/discover/` 和 `cloud/functions/record/`
+
+## 本轮修复的问题
+1. 手动输入设备号绑定后卡在 BLE 搜索 → 改为绑定成功直接跳 bind-success
+2. ble-connect 页加 15 秒超时 + stopScan
+3. ble.js 新增 `stopScan()` 方法
+4. bind-success 页加「返回首页」按钮
+5. subscribe-plans.js 字段名修正（plan → plan_type）
+6. history.js 兼容云函数返回的 created_at 字段
+7. index.js 设备名兼容 name/device_id 字段
+8. request.js 补 /api/v1/subscription 路由别名
+9. admin 云函数从 1 个 action 扩展到 9 个
+10. admin-console request.js 加 mock 模式
+
+## 已验证的功能（真机测试）
+- 登录正常
+- 手动输入设备号绑定正常（自动发放 7 天试用订阅）
+- 解绑正常
+- 重复绑定提示正确
+
+## 需要继续的工作
+
+### 高优先级
+1. **真机测试剩余流程**：订阅购买、订阅验证、历史记录查看
+2. **BLE 真机调试**：需要真实硬件设备（devtools 无蓝牙）
+   - 扫描发现设备 → 连接 → 绑定 → 护理全流程
+3. **管理后台连接真实后端**：当前 `USE_MOCK=true`，需要部署 HTTP 触发的云函数网关
+
+### 中优先级
+4. **Phase 7: OTA 升级**：ble.js 里已有 OTA 相关 characteristic（FFE2/FFE7/FFE8/FFE9），但 OTA 流程未实现
+5. **管理后台 pages.json 配置 tabBar**：目前靠 AdminLayout 组件做导航，可考虑 uniapp 原生 tabBar
+6. **operation_logs 集合**：admin 云函数的 logs action 查这个集合，但各业务云函数尚未写入操作日志
+
+### 低优先级
+7. **Phase 8: 安全加固**：admin 云函数无鉴权，任何人都可调用
+8. **数据导出功能**：管理后台各页面的「导出」按钮都是空操作
+9. **清理 cloud/functions/ 目录**：旧版 SCF 格式已废弃
+
+## 关键代码约定
+- 云函数接收 `{ action, data }`，路由通过 action 字段
+- `request.js` 的 `FUNC_MAP` 把 REST 路径映射到云函数调用，新接口必须加在这里
+- `cloud.getWXContext()` 自动获取 openid，无需前端传
+- tabBar 页面（index/history/profile）用原生导航栏；其他页面用自定义 header
+- 动态岛适配：`style="padding-top: {{statusBarHeight + 24}}px;"` + app.globalData.statusBarHeight
+- 小程序用 WXML/WXSS/JS（非 uniapp）；管理后台用 uniapp + Vue 3
+
+## BLE 协议备忘
+- 帧格式：头 `0xAA 0x55` + 长度 + 类型 + 载荷 + XOR 校验
+- 服务 UUID：FFE0（设备信息）/ FFE1（数据通信）/ FFE2（OTA）
+- 设备广播名含 `HOX` 或 `LIGHTMASK`
+- 护理区域位掩码：0x01 左脸颊 / 0x02 右脸颊 / 0x04 额头 / 0x08 下巴 / 0x10 鼻部 / 0x20 左眼周 / 0x40 右眼周
+
+## 数据库集合
+| 集合 | 关键字段 | 权限 |
+|------|---------|------|
+| users | openid, nickname, phone, created_at | 仅创建者可读写 |
+| bindings | openid, device_id, status(active/inactive), bind_time | 仅创建者可读写 |
+| subscriptions | openid, plan_type(trial/monthly/yearly), status, start_time, end_time, price | 仅创建者可读写 |
+| treatment_records | openid, session_id, device_id, regions, total_duration_ms, mode, created_at | 仅创建者可读写 |
+| operation_logs | action, detail, openid, created_at | 仅创建者可读写 |

docs/planning/需求缺口清单.md

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