# 开发计划

基于全部已有资料整理，包括：
- `软件系统说明.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 设计稿重写页面
