docs: align documentation with Tencent Cloud architecture

docs/planning/PROGRESS.md

@@ -1,124 +1,147 @@
-# Hox 光子美容仪项目 — 工作进度交接
+# Hox 光子美容仪项目 — 当前进度交接
 
-## 项目概况
-微信小程序 + 云开发后台 + uniapp 管理后台，产品是光子美容仪。
+更新时间：2026-04-28
 
-- 小程序 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）
+- 微信原生小程序：`miniprogram/`
+- 管理后台 H5：`admin-console/`，uniapp + Vue 3
+- 腾讯云 HTTP 后端：`server/`，SCF HTTP Function + TencentDB MySQL + COS
 
-cloud/functions/                # 旧版 SCF 格式（已废弃，保留参考）
+旧的微信云开发云函数和 MQTT 客户端已经从活动架构中移除。当前主链路是：
+
+```text
+小程序/后台 -> HTTPS API -> 腾讯云 HTTP 函数 -> TencentDB MySQL / COS
+设备 <-> 小程序 BLE
 ```
 
-## 已完成的工作
+## 当前部署状态
 
-### 基础架构
-- 云开发初始化，6 个云函数部署完成
-- 5 个数据库集合：users, bindings, subscriptions, treatment_records, operation_logs（权限：仅创建者可读写）
-- request.js 双模式：`USE_CLOUD=true` 走 `wx.cloud.callFunction()`，false 走 HTTP
-- 登录简化：云函数用 `cloud.getWXContext()` 自动获取 openid，无需手动 `wx.login()`
+- SCF 函数名：`jw-beauty-api`
+- 函数类型：HTTP 函数
+- 启动文件：`server/scf_bootstrap`
+- 服务端口：`9000`
+- 测试 API：`https://1426323813-ilxkhlxf4p.ap-guangzhou.tencentscf.com`
+- 数据库：TencentDB MySQL，schema 在 `server/sql/schema.sql`
+- COS Bucket：用于固件文件、后台 H5 构建产物和部署包
+- 后台 H5 已支持上传到 COS 的 `admin/` 前缀
 
-### 小程序页面（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
+- 新增 `server/` Node.js 后端。
+- 实现 HTTP 路由、JWT 鉴权、管理员鉴权、MySQL 连接池、COS 签名 URL、微信 `code2Session`。
+- 支持 Tencent Cloud HTTP Function 部署，根目录 `scf_bootstrap` 启动 `scripts/local-server.js`。
+- 已初始化并验证 TencentDB MySQL 表结构。
+- 云函数已绑定数据库所在 VPC/Subnet，并验证后台接口可访问。
+- 已实现核心接口：
+  - `/api/v1/auth/login`
+  - `/api/v1/user/profile`
+  - `/api/v1/user/phone`
+  - `/api/v1/device/bind`
+  - `/api/v1/device/bind/confirm`
+  - `/api/v1/device/unbind`
+  - `/api/v1/device/list`
+  - `/api/v1/device/command/pending`
+  - `/api/v1/device/command/result`
+  - `/api/v1/subscription`
+  - `/api/v1/treatment/history`
+  - `/api/v1/treatment/sync`
+  - `/api/v1/firmware/latest`
+  - `/api/v1/admin/*`
 
-### 已清理
-- 删除了无用的 `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 天试用订阅）
-- 解绑正常
-- 重复绑定提示正确
+- `users`
+- `devices`
+- `bindings`
+- `subscriptions`
+- `treatment_records`
+- `device_events`
+- `device_commands`
+- `operation_logs`
+- `admin_accounts`
+- `system_settings`
+- `firmware_files`
 
-## 需要继续的工作
+### 小程序
 
-### 高优先级
-1. **真机测试剩余流程**：订阅购买、订阅验证、历史记录查看
-2. **BLE 真机调试**：需要真实硬件设备（devtools 无蓝牙）
-   - 扫描发现设备 → 连接 → 绑定 → 护理全流程
-3. **管理后台连接真实后端**：当前 `USE_MOCK=true`，需要部署 HTTP 触发的云函数网关
+- 移除 `wx.cloud` 依赖，改为 HTTPS API。
+- API base 配置在 `miniprogram/config/env.js`。
+- 当前 `ENV = 'test'`，指向测试云函数域名。
+- 登录流程：
+  - `wx.getUserProfile()` 触发微信官方用户资料授权弹窗。
+  - `wx.login()` 获取 code。
+  - 后端换取 openid 并签发 JWT。
+  - 如微信返回昵称/头像，则保存到用户资料。
+  - 若返回 `微信用户` 或默认头像，这是微信平台策略，不是后端问题。
+- 手机号授权已预留：隐藏的 `open-type="getPhoneNumber"` 按钮 + `/api/v1/user/phone`。
+- 扫码绑定已改为两阶段：
+  - 后端创建 pending bind token。
+  - 小程序进入 BLE 连接。
+  - 设备返回绑定成功后小程序确认后端绑定。
+- BLE 校验修正为对 header/length/type/payload 做 XOR。
+- 新增 BLE frame 测试脚本：`miniprogram/scripts/test-ble-frame.js`。
+- 普通模式固定 10 分钟、默认全脸、护理区域灰色不可调。
+- 智能模式保留扫描流程和一次性下发参数。
+- 小程序可拉取后台 `device_commands` 并执行 BLE 指令。
 
-### 中优先级
-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 格式已废弃
+- 请求层已接真实 API，配置在 `admin-console/src/config/env.js`。
+- 当前 `ENV = 'test'`。
+- 临时后台账号仍为 `admin/admin`，生产必须替换。
+- 支持后台页面：dashboard、设备、用户、订阅、护理记录、操作日志、系统设置等。
+- 新增 CSV 导出工具。
+- 新增 H5 构建 manifest。
+- 新增 COS 部署脚本：`admin-console/scripts/deploy-cos.js`。
+- 构建上传命令：`npm run deploy:cos`。
 
-## 关键代码约定
-- 云函数接收 `{ 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 右眼周
+- 新增腾讯云部署文档：`docs/deploy/tencent-cloud.md`。
+- 新增生产环境变量模板：`server/.env.production.example`。
+- `.gitignore` 已忽略真实 `.env`、构建产物、node_modules。
 
-## 数据库集合
-| 集合 | 关键字段 | 权限 |
-|------|---------|------|
-| 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 | 仅创建者可读写 |
+## 已验证
+
+- 云函数 `/health` 返回成功。
+- 后台登录 `/api/v1/admin/login` 成功。
+- 后台 dashboard 返回云数据库统计。
+- 后台设备列表返回预生成设备。
+- 后台设备命令队列写入 `device_commands`。
+- 后台 H5 构建成功并上传到 COS `admin/` 前缀。
+- `node miniprogram/scripts/test-ble-frame.js` 通过。
+
+## 当前注意事项
+
+- `wx.getUserProfile()` 可能返回 `微信用户` 和默认头像，这是微信隐私策略导致。
+- 如果必须可靠获取昵称头像，需要改用 `chooseAvatar` + `input type="nickname"`，但当前按产品要求使用官方授权弹窗。
+- 真机小程序请求云函数测试域名，需要微信公众平台配置 `request 合法域名`。
+- 云函数使用 TencentDB 内网地址时必须保持 VPC/Subnet 配置。
+- 不要提交 `server/.env`、COS 签名 URL、数据库密码、微信密钥或腾讯云密钥。
+
+## 待继续
+
+高优先级：
+
+- 真机验证微信登录、扫码绑定、BLE 连接、设备绑定确认全流程。
+- 护理完成页调用 `/api/v1/treatment/sync`，确保后台能看到护理记录。
+- 后台设备详情接入命令历史和用户绑定详情。
+
+中优先级：
+
+- 后台固件管理 UI 接入 `/api/v1/admin/firmware`。
+- COS 静态网站或自定义域名配置后台长期访问地址。
+- OTA 升级流程完善。
+
+低优先级：
+
+- 替换临时管理员密码。
+- 接入真实微信支付。
+- 增加更完整的自动化测试和部署脚本。