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
@@ -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
|
||||
```
|
||||
在新工单中引用
屏蔽一个用户