jw-beauty/docs/planning/12-待办事项决策分类.md

待办事项决策分类

更新时间：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