jw-beauty/docs/planning/PROGRESS.md

Hox 光子美容仪项目 — 当前进度交接

更新时间：2026-04-28

当前项目概况

项目当前由三部分组成：

• 微信原生小程序：miniprogram/
• 管理后台 H5：admin-console/，uniapp + Vue 3
• 腾讯云 HTTP 后端：server/，SCF HTTP Function + TencentDB MySQL + COS

旧的微信云开发云函数和 MQTT 客户端已经从活动架构中移除。当前主链路是：

小程序/后台 -> HTTPS API -> 腾讯云 HTTP 函数 -> TencentDB MySQL / COS
设备 <-> 小程序 BLE

当前部署状态

• 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/ 前缀

已完成

后端

• 新增 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/*

数据库

已设计并创建：

• users
• devices
• bindings
• subscriptions
• treatment_records
• device_events
• device_commands
• operation_logs
• admin_accounts
• system_settings
• firmware_files

小程序

• 移除 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 指令。

管理后台

• 请求层已接真实 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。

文档与部署

• 新增腾讯云部署文档：docs/deploy/tencent-cloud.md。
• 新增生产环境变量模板：server/.env.production.example。
• .gitignore 已忽略真实 .env、构建产物、node_modules。

已验证

• 云函数 /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 升级流程完善。

低优先级：

• 替换临时管理员密码。
• 接入真实微信支付。
• 增加更完整的自动化测试和部署脚本。