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

更新时间：2026-04-28

## 当前项目概况

项目当前由三部分组成：

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

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

```text
小程序/后台 -> 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 升级流程完善。

低优先级：

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