refactor: migrate to Tencent Cloud backend
这个提交包含在：
Guoguo
@@ -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 | 仅创建者可读写 |
|
||||
在新工单中引用
屏蔽一个用户