153 行
9.9 KiB
Markdown
153 行
9.9 KiB
Markdown
# 代码与设计文档对比分析
|
||
|
||
> 历史快照说明：本文档反映的是早期“微信云开发”阶段的代码评审结论，已不代表当前实现。当前实现已迁移到 `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 接入和微信支付。**
|
||
|
||
---
|
||
|
||
## 五、建议优先级
|
||
|
||
### 立即可做（不需要外部依赖）
|
||
1. 创建 auto-scan 页面（智能模式自动扫描）
|
||
2. treatment-done 页面调用 treatment.sync 上传护理记录
|
||
3. 创建 stats 云函数（4 个统计 API，供 dashboard 使用）
|
||
4. 补充 admin 云函数的 settings action（设置页已存在但后端无处理）
|
||
|
||
### 需要硬件/外部配置
|
||
5. BLE 真机全流程调试（需要真实设备）
|
||
6. IoT 设备注册 + MQTT 接入（需要腾讯云 IoT Hub 配置）
|
||
7. 微信支付集成（需要商户号配置）
|
||
|
||
### 后续迭代
|
||
8. JWT Token 替换
|
||
9. OTA 升级流程
|
||
10. 权限模型完善
|
||
11. 测试用例编写
|