zhy.he/jw-beauty
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

docs: add audit report and prioritized action items

浏览代码 
- 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)
这个提交包含在：
Guoguo
2026-04-28 09:01:18 -07:00
父节点 b80e872600
当前提交 88adee7743
共修改 2 个文件，包含 185 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
docs/planning/12-待办事项决策分类.md
+91
查看文件
@@ -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
```
docs/reviews/代码质量审计报告-20260428.md
+94
查看文件
@@ -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 项