代码与设计文档对比分析
历史快照说明：本文档反映的是早期“微信云开发”阶段的代码评审结论，已不代表当前实现。当前实现已迁移到 server/ 腾讯云 HTTP 函数 + TencentDB MySQL + COS，小程序通过 HTTPS API 调后端，不再使用微信云开发函数或 MQTT 主链路。当前状态请以 docs/planning/PROGRESS.md 和实际代码为准。
基于根目录 01~11 设计文档与当前代码实现（含本轮修改）的逐项对比。
日期：2026-04-24
一、超前实现（文档未规划，代码已实现）
1.1 架构层面
| 项目 |
说明 |
| 微信云开发模式 |
文档基于 SCF + MySQL + Redis + CMQ 架构；代码已迁移至微信云开发（cloud DB + cloud functions），无需 MySQL/Redis/CMQ |
| Mock 开发模式 |
admin-console 的 request.js 内置完整 mock 数据，所有页面可脱离后端独立开发，文档未提及 |
| request.js 双模式 |
小程序 request.js 支持 USE_CLOUD=true 走云函数、false 走 HTTP，文档未规划此适配层 |
| FUNC_MAP 路由映射 |
小程序端将 REST 路径映射到云函数调用的字典，文档未涉及 |
| Pinia 状态管理 |
admin-console 使用 pinia 管理 admin 登录状态，文档仅提到 Vue 3 |
1.2 功能层面
| 项目 |
说明 |
| 操作日志写入 |
auth/device/subscription/treatment/user/admin 六个云函数均已写入 operation_logs，文档仅在 DB 表结构中定义了表，未要求业务层实现 |
| Admin Token 鉴权 |
admin 云函数实现 login + verifyToken 校验（base64 编码），文档的「安全方案」仅列为待设计 |
| CSV 导出 |
5 个管理后台页面（设备/用户/记录/订阅/日志）均实现 CSV 导出下载，文档仅提到「数据导出」为空操作 |
| BLE 15秒超时 + stopScan |
ble-connect 页面加 15 秒扫描超时自动停止，文档未定义扫描超时策略 |
| bind-success 独立页 |
绑定成功后展示 7 天试用提示的独立页面，文档流程图中无此独立步骤 |
| 灵动岛适配 |
所有自定义 header 页面适配 iPhone Dynamic Island（statusBarHeight + 24px），文档未提及 |
| MQTT 客户端框架 |
mqtt.js 已实现基于 WebSocket 的 MQTT 客户端框架（连接/订阅/心跳/重连），虽然未正式启用但框架完备 |
| 系统设置页面 |
settings 页面含基础配置、订阅价格、功能开关（注册/绑定/免费模式/维护模式），文档的「系统设置」仅为占位 |
| Admin Login UI |
完整的登录页 + pinia store + token 持久化，文档仅列「admin 登录方法」为待确认 |
1.3 BLE 协议层
ble.js 已实现了文档 Phase 2 要求的大部分内容：
| 文档要求 |
代码状态 |
| 帧格式 0xAA 0x55 + len + type + payload + XOR checksum |
已实现（buildFrame/parseFrame） |
| 服务 UUID FFE0/FFE1/FFE2 |
已定义 |
| 特征 UUID FFE3~FFE9 |
全部已定义 |
| 命令字节 0x01~0x06 |
全部已定义（SET_PARAMS/START/STOP/QUERY/BIND/UNBIND） |
| 状态上报 0x21~0x33 |
全部已定义（STATUS_REPORT/ACK/TREATMENT_COMPLETE/EXCEPTION/BIND_SUCCESS） |
| 错误码 0x00~0x0C |
全部已定义 |
| ACK/NACK + 序号 + 5秒超时 |
已实现（_pendingAcks + nextSeq） |
| 区域位掩码 bit0-6, 全脸 0x7F |
已实现 |
| 波长值 IR=1/R=2/UV=3/Y=4 |
已实现 |
| 模式 NORMAL=0/SMART=1 |
已实现 |
| 设备信息读取（14字节解析） |
已实现（readDeviceInfo） |
| 护理参数设置（region+wavelength+brightness+duration+mode） |
已实现（setParams） |
| 绑定/解绑（userId+token+timestamp） |
已实现（bindDevice/unbindDevice） |
二、文档规划但未实现
2.1 高优先级未实现（阻塞主链路）
| 编号 |
内容 |
来源 |
说明 |
| N1 |
BLE 真机全流程调试 |
10-Phase2, 08-验收 |
ble.js 协议层完整但未接入真实硬件验证，佩戴检测/护理/绑定全流程需真机测试 |
| N2 |
MQTT 消息处理链路 |
05, 10-Phase4 |
mqtt.js 有框架但未接入 IoT Hub；设备遥测/事件上报、异步写护理记录均未实现 |
| N3 |
IoT 设备注册流程 |
05, 11-C1 |
DeviceSecret 签发流程未实现；workaround: 手动在腾讯云控制台注册 |
| N3b |
iot 云函数（register_device/issue_secret/get_status） |
03 |
3 个 IoT API 均未创建 |
| N4 |
微信支付集成 |
11-C2 |
subscription.purchase 目前是直接创建订阅，未接入微信支付；workaround: 仅试用版可用 |
| N5 |
stats 云函数（4 个统计 API） |
03 |
user_overview/device_overview/treatment_overview/subscription_overview 未创建 |
| N6 |
auto-scan 自动扫描页面 |
02, 10-Phase5 |
treatment-setup 中智能模式跳转 auto-scan 页面，但该页面未创建 |
2.2 中优先级未实现
| 编号 |
内容 |
来源 |
说明 |
| M1 |
devices 独立集合 |
04 |
文档规划 8 张表，代码只实现了 5 张；devices 表未独立创建（设备信息嵌在 bindings 中） |
| M2 |
sessions 集合 |
04 |
护理会话表未创建；treatment_records 直接存储，无 1:N 会话-记录关系 |
| M3 |
pd_data 集合 |
04, 11-DB4 |
PD（光密度）数据表未创建；文档中此表定义也几乎为空 |
| M4 |
OTA 升级流程 |
10-Phase7 |
ble.js 有 FFE7/FFE8/FFE9 characteristic 定义，但 OTA 流程（分块传输、校验、重启）未实现 |
| M5 |
JWT Token 体系 |
07, 10-Phase1 |
文档要求 JWT + 7天有效期 + refresh_token；代码使用简单 openid+timestamp 拼接，无 refresh_token |
| M6 |
refresh_token 机制 |
11-C3 |
登录仅返回 token，无 refresh_token；workaround: auth.refresh 直接用 openid 生成新 token |
| M7 |
管理后台权限模型 |
06, 07 |
无角色/菜单/API/数据范围四级权限；当前所有登录管理员权限相同 |
| M8 |
treatment-done 页同步记录 |
10-Phase5 |
treatment-done 页存在但未调用 treatment.sync 云函数上传护理记录 |
2.3 低优先级未实现
| 编号 |
内容 |
来源 |
说明 |
| L1 |
BLE 分帧（MTU 超长时） |
01 |
文档提到 payload 超 MTU 时需分帧 + 序号；代码未实现 |
| L2 |
重连后重新订阅 notify |
01, 02 |
文档要求 BLE 断连重连后需重新订阅 characteristic notify；代码未处理 |
| L3 |
统一错误码规范 |
03 |
文档规划统一错误码范围，代码各函数自行定义 code 值 |
| L4 |
幂等键 |
03 |
文档要求 record.sync 等接口支持幂等键防重复；代码未实现 |
| L5 |
before/after 快照日志 |
04 |
文档规划 operation_logs 含 before_snapshot/after_snapshot/ip_address/user_agent；代码仅记录 action + detail |
| L6 |
软删除（deleted_at） |
04 |
文档要求全局软删除，代码用 status 字段代替（功能等效但字段不一致） |
| L7 |
操作日志 ip_address |
04, 07 |
云函数无法直接获取客户端 IP；文档未考虑云开发环境的限制 |
| L8 |
管理后台远程控制指令 |
06 |
文档提到管理后台可下发控制指令到设备，完全未实现 |
| L9 |
数据导出权限限制 |
06, 11-L10 |
文档提到导出功能应有权限控制，当前所有管理员均可导出 |
| L10 |
测试用例与 CI/CD |
08 |
无任何测试基础设施，无 CI/CD 配置 |
三、文档与代码有差异（实现方式不同）
| 文档规划 |
代码实际 |
差异说明 |
| MySQL 数据库，BIGINT 自增 PK |
微信云数据库，auto-generated _id |
数据模型保持一致但存储引擎完全不同 |
| 8 张表 |
5 张集合 |
缺少 devices、sessions、pd_data |
| JWT Token |
openid + timestamp 拼接 |
安全性较低但简化了实现 |
| RESTful HTTP API |
云函数 action 路由 |
入口形式不同，功能等价 |
| 4 个 tabBar 页（首页/历史/发现/我的） |
3 个 tabBar 页（首页/历史/我的） |
删除了「发现」页面 |
| SCF + CMQ 异步处理 |
同步云函数 |
无异步队列，记录同步为同步操作 |
| admin 后台部署在腾讯云静态托管 |
uniapp 项目（H5 模式） |
部署方式待定，当前为本地开发 |
| 多环境（dev/test/prod） |
单一云开发环境 |
未区分环境 |
| Redis 缓存 |
无缓存层 |
云开发免费 tier 无 Redis |
四、开发计划完成度（对照 10-开发计划）
| Phase |
内容 |
状态 |
完成度 |
| Phase 1 |
基础设施 & 数据层 |
部分完成 |
60% — 数据库 5/8 表，统一响应格式已有，JWT 未做 |
| Phase 2 |
BLE 通信层 |
协议完成 |
85% — 协议层完整，缺真机验证和分帧 |
| Phase 3 |
云 API 全实现 |
基本完成 |
80% — 缺 IoT 3个 + Stats 4个 API |
| Phase 4 |
MQTT 消息处理 |
未启动 |
10% — 仅有 mqtt.js 框架，未接入 |
| Phase 5 |
小程序 UI |
大部分完成 |
75% — 14/15 页面存在，缺 auto-scan 页，treatment-done 未同步记录 |
| Phase 6 |
管理后台 UI |
基本完成 |
90% — 10 个页面全部存在，含导出和设置 |
| Phase 7 |
OTA 升级 |
未启动 |
5% — 仅有 characteristic 定义 |
| Phase 8 |
安全加固 & 测试 |
部分完成 |
25% — admin 鉴权已加，其余未做 |
整体完成度约 55%，主链路功能框架已搭建完成，关键阻塞项为 BLE 真机调试、MQTT/IoT 接入和微信支付。
五、建议优先级
立即可做（不需要外部依赖）
- 创建 auto-scan 页面（智能模式自动扫描）
- treatment-done 页面调用 treatment.sync 上传护理记录
- 创建 stats 云函数（4 个统计 API，供 dashboard 使用）
- 补充 admin 云函数的 settings action（设置页已存在但后端无处理）
需要硬件/外部配置
- BLE 真机全流程调试（需要真实设备）
- IoT 设备注册 + MQTT 接入（需要腾讯云 IoT Hub 配置）
- 微信支付集成（需要商户号配置）
后续迭代
- JWT Token 替换
- OTA 升级流程
- 权限模型完善
- 测试用例编写
