From 88adee77438870425d0121824e7ac7904d51f179 Mon Sep 17 00:00:00 2001 From: Guoguo Date: Tue, 28 Apr 2026 09:01:18 -0700 Subject: [PATCH] docs: add audit report and prioritized action items MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/reviews/代码质量审计报告-20260428.md: full audit results and fix summary - docs/planning/12-待办事项决策分类.md: action items split by decision owner (hardware team / product team / ops / independent) --- docs/planning/12-待办事项决策分类.md | 91 ++++++++++++++++++++++ docs/reviews/代码质量审计报告-20260428.md | 94 +++++++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 docs/planning/12-待办事项决策分类.md create mode 100644 docs/reviews/代码质量审计报告-20260428.md diff --git a/docs/planning/12-待办事项决策分类.md b/docs/planning/12-待办事项决策分类.md new file mode 100644 index 0000000..fed9117 --- /dev/null +++ b/docs/planning/12-待办事项决策分类.md @@ -0,0 +1,91 @@ +# 待办事项决策分类 + +更新时间：2026-04-28 + +基于全面代码审计和文档合规校验，将所有待办事项分为两类：你可以独立完成的，以及需要与团队（硬件/产品/后端运维）协商后才能推进的。 + +--- + +## 一、需要团队协商的事项 + +### 1. 需要硬件/固件团队确认 + +| 事项 | 为什么需要协商 | 找谁 | +|------|---------------|------| +| BLE XOR 校验范围 | 代码对整帧做 XOR（含帧头 0xAA 0x55），文档建议不含帧头。如果固件按文档实现，所有 BLE 通信都会校验失败。**必须对齐** | 固件工程师 | +| 佩戴检测/自动扫描的命令字 | 代码复用 queryStatus 轮询，文档定义了独立的 START_WEARING_CHECK / START_AUTO_SCAN 命令。需确认固件是否实现了这些独立命令 | 固件工程师 | +| 暂停/恢复护理命令 | 文档列了 PAUSE_TREATMENT / RESUME_TREATMENT，代码未实现。需确认固件是否支持、产品是否需要 | 固件 + 产品 | +| 设备端 PD 数据格式 | 目前扫描数据是占位符。需要确认设备端会以什么格式、通过哪个 characteristic 发送真实 PD 数据 | 固件工程师 | +| OTA 固件升级协议 | 后端固件管理已实现，但小程序端 OTA 传输流程完全缺失。需要确认 OTA 分块大小、校验方式、断点续传策略 | 固件工程师 | +| DeviceSecret 使用方式 | 数据库存了 device_secret 但代码从未校验。需确认设备认证是否需要 secret，以及 secret 在什么环节验证 | 固件 + 后端架构 | + +### 2. 需要产品团队确认 + +| 事项 | 为什么需要协商 | 当前状态 | +|------|---------------|---------| +| "发现"页面是否需要 | 文档要求有美容百科和公告，代码已删除。需确认是 MVP 砍掉了还是后续要补 | 已删除 | +| 护理记录详情页 | 文档要求 record.detail 接口和详情页，代码只有列表。需确认用户是否需要查看单次护理详情 | 未实现 | +| 微信支付接入时间 | 目前购买流程是弹窗提示联系管理员。需确认何时接入微信支付、是否需要提前准备商户号 | 手动开通 | +| 用户禁用功能 | 文档提到用户禁用，管理后台没有禁用按钮。需确认是否需要 | 未实现 | +| 仪表盘可视化 | 目前只有 4 个数字卡片，文档提到趋势图。需确认 MVP 是否需要图表 | 仅数字 | +| 多管理员和角色权限 | 目前只有一个 admin 账号，无角色区分。需确认是否需要多管理员、是否需要分权限 | 未实现 | + +### 3. 需要运维/部署团队确认 + +| 事项 | 为什么需要协商 | 当前状态 | +|------|---------------|---------| +| API 限流策略 | 代码层无限流。腾讯云 API 网关可以配置限流，需确认是在网关层做还是代码层做 | 完全没有 | +| 生产环境 JWT 密钥管理 | 代码已加了启动校验（默认值会报错），但密钥本身需要有人生成并配置到 SCF 环境变量 | 需要配置 | +| 生产环境数据库密码 | .env 不入库，需要有人在 SCF 环境变量中配置真实的数据库连接信息 | 需要配置 | +| CORS 白名单 | 当前 `Access-Control-Allow-Origin: *`。如果 Admin 后台有固定域名，应限制为该域名 | 全开 | +| TLS 版本确认 | 代码依赖腾讯云 API 网关的 TLS 配置，需确认网关最低 TLS 版本是否为 1.2+ | 未确认 | + +--- + +## 二、你可以独立完成的事项 + +### P0 — 建议尽快做 + +| 事项 | 工作量 | 说明 | +|------|--------|------| +| 密码哈希改 bcrypt | 2h | 安装 bcrypt，改 hashPassword 函数，重新生成 admin 密码。纯代码变更，不影响业务逻辑 | +| 命令重试机制 | 2h | 在 ble.js 的 writeCommand 外包一层 retry（最多 3 次），纯前端改动 | +| BLE 断连自动重连 | 3h | 在 onBLEConnectionStateChange 回调中加重连逻辑 + 重新订阅 notify，纯前端改动 | +| 治疗页监听断连事件 | 1h | treating.js 监听 ble 的 disconnected 事件，提示用户设备断开 | +| Token 续期 | 3h | 实现 /auth/refresh 接口（验证旧 token，签发新 token），小程序端在 token 快过期时自动续期 | +| record.detail 接口 | 1h | 在 treatment.js 加一个 GET /api/v1/treatment/:record_id 路由，查单条记录 | + +### P1 — 可以排期做 + +| 事项 | 工作量 | 说明 | +|------|--------|------| +| 敏感数据脱敏 | 3h | admin 接口返回用户列表时，手机号脱敏（138****1234），openid 不返回给前端 | +| 设备端 secret 校验 | 2h | 在 /device/bind 接口中校验 device_secret（需要先确认硬件方案，见上方协商项） | +| CORS 限制 | 0.5h | response.js 中根据请求 Origin 判断，只放行 admin 后台域名 | +| 操作日志补充审计字段 | 2h | writeLog 增加 user_agent、target_type、target_id 参数 | +| 管理员管理页面 | 4h | admin-console 加管理员列表/新增/编辑/禁用页面，后端加 CRUD 接口 | +| 前端角色权限过滤 | 3h | AdminLayout 根据 role 过滤菜单项，页面中根据 role 控制按钮显隐 | +| 全局状态机 | 4h | 抽取小程序全局状态管理器，统一管理 BLE 连接/绑定/护理状态流转 | +| 软删除机制 | 3h | 给关键表加 deleted_at 字段，修改删除逻辑为 UPDATE SET deleted_at，查询加 WHERE deleted_at IS NULL | + +### P2 — 锦上添花 + +| 事项 | 工作量 | 说明 | +|------|--------|------| +| 仪表盘趋势图表 | 4h | 后端加按天/周/月的统计接口，前端用 echarts/ucharts 画图 | +| 高风险操作二次确认 | 2h | 给远程指令、手动创建订阅等操作加 Modal 确认 | +| 多端登录限制 | 2h | 登录时记录 token 版本号，旧 token 自动失效 | +| BLE 分帧/粘包 | 4h | 实现分包发送和接收端拼装（OTA 实现时必须做） | +| 数据库字段名对齐文档 | 6h | 批量 rename（start_time->started_at 等），改动面大，需要前后端联动 | +| 统一错误码规范 | 2h | 定义错误码枚举文件，所有 routes 引用统一常量 | + +--- + +## 建议的推进顺序 + +``` +第一步：拿着"硬件团队确认"清单开会，尤其是 XOR 校验范围 — 这决定 BLE 能不能通 +第二步：拿着"产品团队确认"清单，砍掉不需要的项，明确 MVP 边界 +第三步：你独立完成 P0（密码哈希、重试、断连重连、Token 续期） +第四步：根据协商结果推进 P1 +``` diff --git a/docs/reviews/代码质量审计报告-20260428.md b/docs/reviews/代码质量审计报告-20260428.md new file mode 100644 index 0000000..0eecb74 --- /dev/null +++ b/docs/reviews/代码质量审计报告-20260428.md @@ -0,0 +1,94 @@ +# 代码质量审计报告 + +审计时间：2026-04-28 +审计范围：server/、miniprogram/、admin-console/ 全部源码 + 设计文档合规性 + +## 审计结果总览 + +### 代码质量（修复前 -> 修复后） + +| 模块 | 修复前 CRITICAL | 修复后 CRITICAL | 修复的问题数 | +|------|----------------|----------------|-------------| +| Server 后端 | 4 | 0 | 13 | +| 小程序 | 7 | 0 | 14 | +| Admin 管理后台 | 5 | 0 | 16 | +| 文档一致性 | 6 | 3 (已知差距) | 3 | + +42 个文件修改，+495 / -1216 行（净减少 721 行），经两轮独立审查验证通过。 + +### 文档合规校验 + +| 校验维度 | 符合 | 部分符合 | 未实现 | +|----------|------|----------|--------| +| BLE 通信协议 | 4/10 | 2/10 | 2/10 | +| API 接口 | 9/17 | 6/17 | 2/17 | +| 数据库表结构 | 0/8 | 6/8 | 2/8 | +| 安全与鉴权 | 4/15 | 4/15 | 7/15 | +| 小程序业务流程 | 3/9 | 6/9 | 0/9 | +| 管理后台功能 | 5/9 | 4/9 | 0/9 | + +--- + +## 已修复的问题 + +### Server（13 项） + +1. JWT 密钥生产环境强制校验（不允许默认值） +2. 订阅 verify 改为 admin-only（堵免费订阅漏洞） +3. 设备命令结果上报增加设备归属校验 +4. 设备事件上报增加设备归属校验 +5. 护理记录同步增加设备归属校验 +6. 移除 admin token 从请求 body 读取 +7. 管理员设置接口增加 key 白名单 +8. 管理员创建订阅增加用户存在性校验 +9. COS getObjectUrl 改为 callback-based Promise +10. 固件检查增加版本比较逻辑 +11. 绑定返回真实订阅状态（替代硬编码 trial） +12. 分页参数增加边界保护（pageSize 上限 100） +13. 提取公共工具函数（limitClause, toMysqlDate, formatDate） + +### 小程序（14 项） + +1. 扫描 PD 假数据替换为占位符 +2. 护理完成标记为 client_timer 来源 +3. mock.js 禁用 +4. auto-scan 增加 onUnload 清理 BLE 监听器 +5. wear-check 增加 onUnload 清理 BLE 监听器 +6. ble-connect 增加 onUnload 清理 BLE 监听器 +7. index 页 ble.off 传入具体回调（不再清除所有监听器） +8. subscription status 类型统一为数字 +9. BLE 扫描回调累积修复（offBluetoothDeviceFound） +10. 历史统计数据跨页累加 +11. subscribe-success 从参数读取实际套餐信息 +12. treatment-done 从参数读取实际护理模式 +13. BLE 断连检测（onBLEConnectionStateChange） +14. 购买流程替换为联系管理员弹窗 + +### Admin 管理后台（16 项） + +1. AdminLayout 退出功能修复（require->import, logout->clearToken） +2. 删除全部 mock 数据和 getMockData 函数 +3. Dashboard 假数据替换为真实 API 调用 +4. Dashboard monthly_revenue 替换为 subscription_count +5. 订阅统计 || 改为 ?? 修复 0 值显示 +6. Token 增加 7 天过期校验 +7. 设备状态码统一（"库存"改为"未激活"） +8. 用户页"记录"链接指向正确页面 +9. 订阅 createForm.user_id 类型修复 +10. 所有 catch 块增加错误提示 Toast +11. 订阅状态文本统一 +12. 删除无效的"记住登录状态"复选框 +13. 提取公共 CSS 到 common.css（减少 900+ 行重复） +14. 提取 formatDate 到 utils/format.js +15. AdminLayout 显示真实管理员名称 +16. 移除未使用的 uview-plus 依赖 + +--- + +## 剩余差距 + +详见 `docs/planning/12-待办事项决策分类.md`，分为： +- 需要硬件团队确认的 6 项（BLE 协议细节） +- 需要产品团队确认的 6 项（功能范围） +- 需要运维确认的 5 项（部署配置） +- 可独立完成的 P0 共 6 项、P1 共 8 项、P2 共 6 项