From 543808b76e1abbcd7472e00d48982f0c7ac563f0 Mon Sep 17 00:00:00 2001 From: Guoguo Date: Tue, 28 Apr 2026 23:16:26 +0800 Subject: [PATCH] docs: align documentation with Tencent Cloud architecture --- AGENTS.md | 76 ++++++-- docs/README.md | 18 +- docs/planning/PROGRESS.md | 229 ++++++++++++++----------- docs/reviews/代码与设计文档对比分析.md | 2 + 4 files changed, 204 insertions(+), 121 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 533aaad..1de6c03 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,24 +1,74 @@ # Repository Reality -- This repository currently contains only `软件系统说明.docx`; no source code, package manifest, lockfile, CI workflow, or existing agent instruction files were present when this file was written. -- Treat the Word document as the only verified source of truth. Do not invent build, test, lint, deploy, or startup commands until executable config is added to the repo. -- If code appears later, re-audit the repo and update this file from executable config before relying on the document alone. +- This repository now contains the WeChat Mini Program, the uniapp/Vue 3 admin console, a Tencent Cloud SCF HTTP backend, deployment docs, and design/planning references. +- Current backend implementation lives in `server/` and targets Tencent Cloud HTTP Function + TencentDB MySQL + COS. +- The previous WeChat Cloud Development function directories have been removed from the active architecture. +- Do not treat older planning/review documents as current implementation truth unless they explicitly say they are current. # Verified System Scope -- Product scope from `软件系统说明.docx`: a WeChat Mini Program connects to a beauty device over BLE 5.0 GATT, cloud services run on Tencent Cloud IoT + SCF + MySQL + Redis, and the admin console is `uniapp + Vue 3 + uView Plus` deployed as H5/static hosting. -- Mini Program side is described as WeChat native (`WXML` / `WXSS` / `JS`), not `uniapp`. -- Admin console is separate from the Mini Program. Do not merge those frontend assumptions when future code is added. +- Mini Program: native WeChat `WXML` / `WXSS` / `JS` under `miniprogram/`. +- Device communication: BLE 5.0 GATT via `miniprogram/services/ble.js`. +- Mini Program cloud API: HTTPS requests through `miniprogram/utils/request.js` to the configured API base in `miniprogram/config/env.js`. +- Backend: Tencent Cloud HTTP Function, package root uses executable `server/scf_bootstrap` to start `node scripts/local-server.js` on port `9000`. +- Database: TencentDB MySQL schema in `server/sql/schema.sql`. +- Storage: Tencent COS for firmware/admin H5 artifacts. +- Admin console: uniapp + Vue 3 under `admin-console/`, H5 build can be uploaded to COS. + +# Current Deployment Facts + +- Test API base is configured as `https://1426323813-ilxkhlxf4p.ap-guangzhou.tencentscf.com` in both Mini Program and admin console test configs. +- SCF function name used during deployment: `jw-beauty-api`. +- SCF is an HTTP function, not an event function. Use `scf_bootstrap`, not `index.main_handler`, for this function type. +- SCF must be attached to the TencentDB VPC/subnet when using the database private endpoint. +- Real secrets must remain in local `.env` or SCF environment variables. Never commit `server/.env`. # Integration Facts Worth Preserving -- BLE frame format in the document: header `0xAA 0x55`, then length, type, payload, XOR checksum. -- BLE services in the document: `FFE0` device info, `FFE1` data communication, `FFE2` OTA. -- MQTT topics in the document: `$iot/{product_id}/{device_name}/telemetry` and `$iot/{product_id}/{device_name}/event`. -- Cloud data model names called out in the document: `users`, `devices`, `bindings`, `subscriptions`, `sessions`, `treatment_records`, `pd_data`, `operation_logs`. +- BLE frame format implemented in code: header `0xAA 0x55`, length, type, payload, XOR checksum over header/length/type/payload. +- BLE services in the document/code: `FFE0` device info, `FFE1` data communication, `FFE2` OTA. +- Device binding is two-phase: backend bind request creates pending token, Mini Program sends BLE bind, device returns bind success, Mini Program confirms backend binding. +- Device commands are queued in MySQL `device_commands`; Mini Program pulls pending commands and executes BLE commands. +- Current main cloud path is HTTPS API through the Mini Program, not MQTT/IoT direct device-cloud communication. + +# User Profile / Login Reality + +- `wx.login()` only provides a code for backend `openid/session_key` exchange. +- The current login page uses `wx.getUserProfile()` to request WeChat's official profile authorization popup and then stores returned nickname/avatar if WeChat provides them. +- WeChat may still return masked values such as `微信用户` and default avatar. This is platform policy, not a backend bug. +- If reliable nickname/avatar capture becomes required, use the newer `chooseAvatar` + `input type="nickname"` flow, but that is not the current requested UX. +- Phone number authorization is scaffolded through `open-type="getPhoneNumber"` and backend `/api/v1/user/phone`, currently hidden in the login UI. + +# Build And Deploy Commands + +Backend local: + +```bash +cd server +npm install +npm run db:init +npm start +``` + +Admin H5: + +```bash +cd admin-console +npm install +npm run build:h5 +npm run deploy:cos +``` + +Mini Program BLE frame test: + +```bash +cd miniprogram +node scripts/test-ble-frame.js +``` # Working Rules For Future Sessions -- When asked to implement code in this repo, first confirm whether source files have been added since this file was created; right now there is nothing to edit except documentation. -- If implementation details are needed beyond the document, state that they are unspecified instead of guessing architecture, package layout, or command lines. -- Prefer updating this file only after verifying new facts from checked-in config or code, not from assumptions. +- Use current executable config and code as the source of truth before relying on older planning docs. +- Do not reintroduce `wx.cloud`, WeChat Cloud Development functions, or MQTT unless the architecture is explicitly changed again. +- Do not commit `.env`, cloud credentials, database passwords, signed COS URLs, or generated build artifacts. +- Before committing, check `git status --short` and scan staged files for secret-looking values. diff --git a/docs/README.md b/docs/README.md index cd6cd6e..392ba9f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,18 +8,26 @@ | --- | --- | | `requirements/` | 产品说明、系统说明等需求来源文档 | | `design/` | 业务流程、接口、数据库、后台、安全、测试等设计文档 | -| `protocols/` | BLE、云端通信、IoT/MQTT 等协议文档 | -| `planning/` | 开发计划、进度交接、待确认事项、缺口清单 | -| `reviews/` | 代码与文档对比、评审和分析材料 | +| `protocols/` | BLE、云端通信等协议文档；部分 IoT/MQTT 内容为历史设计参考 | +| `planning/` | 开发计划、当前进度交接、待确认事项、缺口清单 | +| `reviews/` | 代码与文档对比、评审和分析材料；旧评审可能是历史快照 | | `prototypes/` | 小程序和管理后台原型文件 | | `reference/` | 原始资料包、UI 导出页、截图等参考材料 | ## 当前入口 +- `planning/PROGRESS.md` — 当前实现和部署状态，以此为准 +- `deploy/tencent-cloud.md` — 腾讯云函数、MySQL、COS 部署说明 - `requirements/软件系统说明.docx` - `requirements/光子美容仪软件系统说明.docx` - `design/01-BLE通信协议明细.md` - `design/02-小程序业务流程与状态机.md` -- `planning/PROGRESS.md` - `planning/需求缺口清单.md` -- `reviews/代码与设计文档对比分析.md` +- `reviews/代码与设计文档对比分析.md` — 历史阶段评审，不能代表当前实现 + +## 当前实现提示 + +- 当前后端是 `server/` 下的腾讯云 HTTP 函数，不是微信云开发函数。 +- 当前小程序通过 HTTPS API 调后端，不再使用 `wx.cloud.callFunction()`。 +- 当前设备不直接连云端 MQTT，设备通信主路径是小程序 BLE 中转。 +- 登录资料授权使用 `wx.getUserProfile()` 官方弹窗；微信可能返回 `微信用户` 等脱敏资料。 diff --git a/docs/planning/PROGRESS.md b/docs/planning/PROGRESS.md index e692d23..aff05c8 100644 --- a/docs/planning/PROGRESS.md +++ b/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 升级流程完善。 + +低优先级： + +- 替换临时管理员密码。 +- 接入真实微信支付。 +- 增加更完整的自动化测试和部署脚本。 diff --git a/docs/reviews/代码与设计文档对比分析.md b/docs/reviews/代码与设计文档对比分析.md index d3d2f8f..9c18a45 100644 --- a/docs/reviews/代码与设计文档对比分析.md +++ b/docs/reviews/代码与设计文档对比分析.md @@ -1,5 +1,7 @@ # 代码与设计文档对比分析 +> 历史快照说明：本文档反映的是早期“微信云开发”阶段的代码评审结论，已不代表当前实现。当前实现已迁移到 `server/` 腾讯云 HTTP 函数 + TencentDB MySQL + COS，小程序通过 HTTPS API 调后端，不再使用微信云开发函数或 MQTT 主链路。当前状态请以 `docs/planning/PROGRESS.md` 和实际代码为准。 + > 基于根目录 01~11 设计文档与当前代码实现（含本轮修改）的逐项对比。 > 日期：2026-04-24