Files
ws_health/doc/api-review-plan.md
T
likandtrae-solo-agent d23aa48159 docs: 新增 api 审查整改计划
按根因拆为 5 批 30 项,记录小程序端影响、验证方式与四个产品决策结论。
2026-10-24 22:00:25 +08:00

247 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# api 审查整改计划(health + user)
> 来源:2026-10-24 对 `api/` 的静态审查(30 项)。
> 本文是整改的唯一执行清单:每项含位置、方案、小程序端影响、验证方式与状态。
> 仓库结构:根仓库 + `api/user`、`api/health`、`ui/wxapp_escort`、`ui/wxapp_escort_admin` 各自独立 git,提交按仓库分开。
## 一、执行原则
1. **根因合并**:同一根因的多处问题一次改完、一次提交,不做零散单点补丁。
2. **先契约后运行时后清理**:先服务端契约(鉴权/校验/字段),再运行时防护(限流/WS/超时),最后死代码与技术债。
3. **每次改动必须核对小程序端**:`ui/wxapp_escort`(用户端)与 `ui/wxapp_escort_admin`(管理端)是否调用该接口、是否依赖被改字段/错误文案/HTTP 语义。
4. **客户端兼容优先**:能不破前端就不破;必须破时同步改前端,并在同一批次内提交。
5. **不引入行为性回归**:响应包结构 `{code,msg,data}` 与 HTTP 200 约定暂不改变(见 D4)。
6. **每批一次提交**:提交信息用简洁短句,说明「为什么」。
## 二、批次总览
| 批次 | 主题 | 条目 | 交付判定 |
|---|---|---|---|
| B1 | 权限与密钥止血 | P0-1、P0-2、P1-3、P1-4、P1-5 | 注册不可自授管理员;密钥出库;用户不可越权写订单字段 |
| B2 | Agent 数据隔离与出网 | P1-6、P2-6、P2-7、P2-12、P2-14 | 订单查询按 userId;SSRF 不可绕过;沙箱 deny 补齐 |
| B3 | 服务端契约加固 | P1-2、P2-3、P2-4、P2-5、P2-9、P2-10、P2-11、P2-13、P2-15 | 错误对外收敛;token CSPRNG;校验与状态机单点化 |
| B4 | 运行时防护 | P1-7、P2-1、P2-2、P2-8、P2-16 | WS 有界、写接口限流、token 不入 URL/日志 |
| B5 | 债务清理与测试 | P3-1 ~ P3-6、P2-17 | 死代码删除、数据外置、health 基础测试 |
> 表中编号与下方逐项卡片一致。P0=阻断、P1=高、P2=中、P3=低。原审查中的 30 条按根因重排后编号如下。
## 三、逐项卡片
### B1 权限与密钥止血
**P0-1 注册接口可自授管理员(阻断)**
- 位置:`api/user/handler/users.js`(`register` 的 `app` 校验与落库)、`api/user/handler/users.js`(`userList` 的 admin 判定)、`api/health/routes/index.js`(`requireAdmin`)。
- 方案:`/user/register` 不再接受客户端 `app`;注册时 `app` 只允许服务端写入空对象。管理身份改由服务端维护的 `app.role`(或独立的 `roles` 字段)判定,`requireAdmin` 同时校验 `app` 内管理员键与 `role === 'admin'`(双条件,后续可收紧到单条件)。
- 小程序端影响:用户端 `utils/api.js` 未调用 `/user/register`(仅 `wxSignin`/`update`/`wxgetphonenumber`/`signout`),无影响;管理端需确认登录来源(`wxSignin`),确认其管理员标记来自数据库而非注册入参。
- 验证:以新用户调用 `/user/register` 并在 body 带 `app:{"wxapp-escort-admin":{}}`,随后请求 `/health/escort-record`(管理端接口)应返回 403/「无权限」。
**P0-2 微信密钥与数据库口令入库(阻断)**
- 位置:`api/user/conf.json`(git 已跟踪)、`api/user/.gitignore`。
- 方案:`api/user/.gitignore` 增加 `conf.json`;`git rm --cached api/user/conf.json`;本地保留文件并在仓库内提供 `conf.example.json`(占位值);线上配置维持 `/etc/ehason/conf.json` 外置。密钥需由所有者轮换(本次只做代码侧止血)。
- 小程序端影响:无(配置在服务端)。
- 验证:`git ls-files api/user | Select-String conf.json` 输出为空;服务仍能读取本地 `conf.json` 启动。
**P1-3 用户可写服务侧字段(高)**
- 位置:`api/health/handler/escort_record.js`(`OWNER_UPDATE_FIELDS` 及 `updateRecord`)。
- 方案:用户侧白名单收窄为 `notes.patientNote`、`hospital.*`、`schedule.date`、`schedule.startTime`(点号路径白名单);禁止 `notes.escortNote`、`notes.medicalSummary`、`attendant`、`payment*`、`status`、`duration*`、`endTime`、`totalPrice`。管理员仍走管理端字段集。
- 小程序端影响:`pages/escort/recorddetail.js` 只提交 `notes.patientNote` 与 `hospital.*`/`schedule.*`,兼容;无需改前端。
- 验证:普通用户 `PUT /health/escort-record/:id` 带 `notes.escortNote` 应返回 400;带 `notes.patientNote` 正常。
**P1-4 下单可自填陪诊员(高)**
- 位置:`api/health/handler/escort_record.js`(`createRecord` 落库字段)。
- 方案:`createRecord` 显式覆盖 `attendant`(普通用户置空,管理员可按入参);`userId`、`status`、`payment` 继续服务端强制。
- 小程序端影响:`pages/escort/itemdetail.js` 不下发 `attendant`,无影响。
- 验证:普通用户下单带 `attendant:{name:'伪造'}`,落库后 `attendant` 为空且列表不展示该值。
**P1-5 订单改档案未校验归属(高)**
- 位置:`api/health/handler/escort_record.js`(`updateRecord` 的 `healthProfileId` 处理)。
- 方案:`updateRecord` 收到 `healthProfileId` 时复用 `createRecord` 的归属校验(`profile.userId === ctx.user._id`);校验通过后同步刷新 `patient` 快照(与下单同一函数)。
- 小程序端影响:`recorddetail.js` 修改档案走跳转档案页,不提交 `healthProfileId`,无影响。
- 验证:A 用户把订单改到 B 的档案返回 400/403;改到自己的档案后 `patient` 同步更新。
### B2 Agent 数据隔离与出网
**P1-6 订单工具按手机号隔离可被绕过(高)**
- 位置:`api/health/agent/infra/tools/db/escort_record_query.js`、`api/health/agent/infra/tools/db/escort_record_set.js`、`health_profile_*` 工具。
- 方案:隔离键从 `patient.mobile` 改为 `record.userId`(工具上下文已有登录用户);`userId` 缺失时直接报「未登录」而不是回退全量。档案工具同理按 `userId`。
- 小程序端影响:无(Agent 内部工具)。
- 验证:A 登录后通过 WS 让 bot 查订单,返回仅 A 的 `userId` 记录;改 `profile.mobile` 后结果不变。
**P2-6 Agent 搜索正则未转义(中)**
- 位置:`api/health/agent/infra/tools/db/escort_record_query.js`、`escort_record_query_admin.js`。
- 方案:新增 `escapeRegex` 公共函数,关键词一律先转义再 `$regex`;长度截断 64 字符。
- 小程序端影响:无。
- 验证:关键词输入 `((((((` 不报错、不超时。
**P2-7 SSRF 防护可绕过(中)**
- 位置:`api/health/agent/infra/tools/web/url_guard.js`、`http_get.js`、`http_post.js`、`fetch.js`。
- 方案:`fetch` 统一 `redirect:'manual'` 并自行跳转(每跳重新校验,最多 3 跳);请求前用 `dns.promises.lookup(host, {all:true})` 校验所有解析地址;超时由服务端固定上限(如 15s)而非入参;响应体流式读取并在 2MB 截断。
- 小程序端影响:无。
- 验证:构造 302 指向 `127.0.0.1`、DNS 解析到内网的域名、超大响应,均应被拒或截断。
**P2-12 沙箱未 deny `.git`(中)**
- 位置:`api/health/agent/infra/restricted_fs_backend.js`。
- 方案:deny 列表补充 `.git`、`.env`、`*.pem`、`*.key`、`conf.json`(含子路径),并在 `_isDenied` 中对不区分大小写匹配。
- 小程序端影响:无。
- 验证:Agent 尝试读取 `.git/config`、`.env` 被拒。
**P2-14 env 工具黑名单不全(中)**
- 位置:`api/health/agent/infra/tools/system/envs.js`。
- 方案:从「关键字黑名单」改为「白名单 + 关键字兜底」:默认只暴露非敏感变量;`*_PASS`、`*_KEY`、`*_URI`、`*_DSN` 一律脱敏;`env_set` 从导出中移除(无调用方)。
- 小程序端影响:无。
- 验证:设置 `MONGODB_URI`、`FOO_PASS` 后调用工具均返回 `***`。
### B3 服务端契约加固
**P1-2 内部错误原文回传(高)**
- 位置:`api/health/utils/responseUtil.js`、`api/user/utils/api_response.js` 及各 handler 的 `internalError(ctx, err.message)`。
- 方案:`internalError` 对外固定「服务器繁忙,请稍后重试」,真实 `err.stack` 仅进日志(带 `requestId`);`ctx.app.emit('error')` 统一兜底。保留 `code` 语义不变。
- 小程序端影响:前端只读 `msg` 做 toast,文案变通用不影响逻辑;`request.js` 的 401 处理不依赖 `msg`。
- 验证:构造类型错误请求,响应不含堆栈/Mongo 连接串,日志含完整堆栈。
**P2-3 token 用 Math.random(中)**
- 位置:`api/user/handler/users.js`(`genToken`)。
- 方案:改 `crypto.randomBytes(32).toString('hex')`;保留 sha256 入库与 15 天有效期。
- 小程序端影响:无(token 仍是字符串)。
- 验证:单测断言长度与字符集;旧 token 在库中仍可校验。
**P2-4 手机号无唯一索引 + 注册竞态(中)**
- 位置:`api/user/models/schema/user.js`、`api/user/handler/users.js`(`register`)。
- 方案:`profile.mobile` 加 `unique` 稀疏索引;注册改为直接 `create` 并捕获 `E11000` 返回「手机号已注册」,去掉「先查后插」。
- 小程序端影响:`pages/mine/profileedit.js` 允许用户改手机号;若改到他人号码会被拒 → 需同步改为提示「该手机号已被使用」。**待决策 D1。**
- 验证:并发两次同号注册仅成功一次;用户改号冲突返回明确文案。
**P2-5 登录用户枚举(中)**
- 位置:`api/user/handler/users.js`(`signin`)。
- 方案:不存在与密码错误统一为「账号或密码错误」。
- 小程序端影响:仅文案;前端未见对具体文案的分支判断。
- 验证:两种失败路径响应完全一致。
**P2-9 档案校验缺失(中)**
- 位置:`api/health/models/schema/health_profile.js`、`api/health/handler/health_profile.js`(`create`/`update`)。
- 方案:`update` 加 `runValidators:true`;`create` 校验 `name`/`mobile` 必填且手机号格式;每人档案上限(如 20)防止滥用。
- 小程序端影响:`pages/health/profileedit.js` 已做同样的必填与手机号校验,正常输入不受影响;上限提示需前端 toast 透传 `msg`(现成逻辑)。
- 验证:非法 `sex`/负数身高返回 400;第 21 个档案返回明确文案。
**P2-10 管理端 Agent 绕过状态机(中)**
- 位置:`api/health/agent/infra/tools/db/escort_record_set.js`。
- 方案:状态迁移校验抽成 `utils/recordState.js`(HTTP handler 与 Agent 工具共用);工具侧不再直接改 `status`,改为调用同一迁移函数;`payment` 枚举补 `refunding`。
- 小程序端影响:无(管理端 Agent 行为约束,管理端页面仍走 HTTP)。
- 验证:工具把 `completed` 改回 `in_progress` 应被拒;合法迁移成功。
**P2-11 进行中订单仍可改排期/医院(中)** — 已在 B1 随字段白名单完成
- 位置:`api/health/handler/escort_record.js`(`ownerEditableFields`)、`ui/wxapp_escort/pages/escort/recorddetail.{js,wxml}`。
- 方案:`in_progress` 仅允许 `notes.patientNote`;`pending`/`confirmed` 允许医院与排期,非 `pending` 改期写入 `schedule.scheduleUpdatedAt` 审计时间;前端把单一 `canEditOrder` 拆为 `canEditBooking` / `canEditNote`,进行中只保留备注入口。
- 小程序端影响:已同步修改订单详情页入口显隐,与后端白名单一致。
- 验证:`in_progress` 订单改医院返回 400;`confirmed` 改期成功且带审计时间。
**P2-13 财务记录硬删除(中)**
- 位置:`api/health/handler/escort_record.js`(`deleteRecord`)。
- 方案:硬删除仅限 `pending` 且未支付;其余状态改为 `cancelled` + `deletedAt` 软删除标记,列表默认过滤。**待决策 D3。**
- 小程序端影响:用户端删除按钮本就只对未支付开放;管理端删除入口需按状态禁用并提示。
- 验证:已支付订单删除返回 400;未支付硬删成功。
**P2-15 ResponseUtil 恒 200(中)**
- 位置:`api/health/utils/responseUtil.js`、health `app.js` 错误兜底。
- 方案:保持业务 `code` 与 HTTP 200 不变,另加 `X-Biz-Code` 响应头与结构化日志,供 nginx/监控按 biz code 告警。**待决策 D4(是否改真实 HTTP 状态码)。**
- 小程序端影响:若改真实状态码,`request.js` 需按 `statusCode` 分流,风险高;默认不改。
- 验证:日志含 `bizCode`、`requestId`;响应头存在。
### B4 运行时防护
**P1-7 WS 无上限无并发控制(高)**
- 位置:`api/health/websocket.js`。
- 方案:`maxPayload: 256KB`;每连接维护发送队列(同连接串行处理 chat);单用户消息频次限制(如 10 条/分钟);`close/error` 清理计时器与订阅。
- 小程序端影响:`utils/websocket.js` 帧结构不变;正常文本远小于上限。前端已按 `{source,type,content,id}` 分发,无需改。
- 验证:>256KB 帧被关闭;快速连发 20 条只有 10 条进入 Agent;断线后 Map 无残留。
**P2-1 token 可走 query 并落日志(中)**
- 位置:`api/health/routes/index.js`(`requireAuth`)、`api/health/app.js`、`api/user/app.js`(请求日志)。
- 方案:只接受 `token` 请求头(可兼容剥 `Bearer `),移除 query token;访问日志改记录 `ctx.path` 并对 `token` 参数脱敏。
- 小程序端影响:`utils/request.js` 使用请求头传 token,无影响;确认 WebSocket 握手走的是帧内 token(非 URL)。
- 验证:`?token=` 请求返回 401;日志中不出现 token 明文。
**P2-2 health 写接口无限流(中)**
- 位置:`api/health/routes/index.js`。
- 方案:接入与 user 服务同款的进程内限流(按 token/IP):下单 5 次/分钟、改单 20 次/分钟、AI 30 次/分钟。
- 小程序端影响:正常用户不会触发;超限返回「操作过于频繁,请稍后再试」,前端 toast 已兼容。
- 验证:脚本连发下单,第 6 次返回限流 code。
**P2-8 陪诊师列表分页未夹紧(中)**
- 位置:`api/health/handler/employee.js`。
- 方案:`pageSize` 夹紧 1~50,`page` 下限 1。
- 小程序端影响:`attendantlist` 当前固定小页尺寸,无影响。
- 验证:`pageSize=10000` 实际返回 ≤50。
**P2-16 微信接口无超时(中)**
- 位置:`api/user/handler/users.js`(`wxSignin`/`wxgetphonenumber` 的 fetch)。
- 方案:统一 `AbortSignal.timeout(8000)`;失败区分「微信服务不可用」与「凭证无效」。
- 小程序端影响:失败文案更准确;前端只 toast。
- 验证:断网/超时返回明确文案而非挂起。
### B5 债务清理与测试
**P2-17 health 无测试(中)**
- 位置:`api/health/package.json`、新增 `api/health/test/`。
- 方案:先用内存/mock 方式覆盖纯逻辑:状态迁移、时长与费用派生、字段白名单、档案归属校验;不引入数据库依赖。
- 小程序端影响:无。
- 验证:`npm test` 通过(沿用 user 服务的测试框架)。
**P3-1 requireAuth 不剥 Bearer**
- 位置:`api/health/routes/index.js`。方案:与 user 服务对齐(剥前缀);前端传裸 token,兼容。
**P3-2 thread_id 恒 undefined**
- 位置:`api/health/agent/bots/bot-escort/agent.js`。方案:由会话创建方显式传入 `threadId`;缺失时用 userId 派生。
**P3-3 死代码**
- 位置:`api/health/utils/authToken.js`、`api/health/utils/passwdCrypto.js`、`api/health/agent/infra/tools/system/{fs_info,os_info,os_network_info,os_socket_info,hardware_info,installed_software}.js`、`envs.js` 的 `setEnvTool`。
- 方案:确认零引用后删除;`escort_record_query_admin.js` 更名导出避免与普通版同名。
**P3-4 数据内嵌**
- 位置:`api/health/resource/fudan_hospital_ranking.js`(5439 行)。方案:数据外置为 JSON 并 `require`,逻辑保留在 js。
**P3-5 用户服务不可用被当作未登录**
- 位置:`api/health/utils/user_service.js`。方案:区分 401(无效 token)与网络/5xx(返回 503 与「服务暂不可用」)。
**P3-6 其他一致性**
- `koa-cors` 换 `@koa/cors`;`health/app.js` 去掉对 `app._router` 的内部赋值;health 启动期资源加载失败不阻塞进程。
## 四、待决策项
| 编号 | 问题 | 决策(2026-10-24 已确认) |
|---|---|---|
| D1 | 用户自助改手机号 | **A 允许,冲突时提示**「该手机号已被使用」;手机号不再是数据隔离键 |
| D2 | 已支付/进行中订单改期 | **A 进行中禁改排期/医院(仅可改就诊人备注);已支付可改并写审计时间** |
| D3 | 管理员删除订单 | **A 未支付硬删;其余软删除**(`cancelled` + `deletedAt`,列表默认过滤) |
| D4 | HTTP 状态码 | **A 维持 200,新增 `X-Biz-Code` 响应头**,不改小程序请求层 |
## 五、执行状态
| 批次 | 状态 | 提交(仓库:哈希) | 备注 |
|---|---|---|---|
| B1 | 已完成(待运行验收) | 见提交记录 | 已完成 P0-1、P0-2、P1-3、P1-4、P1-5,并顺带完成 P2-11 |
| B2 | 待开始 | - | - |
| B3 | 待开始 | - | - |
| B4 | 待开始 | - | - |
| B5 | 待开始 | - | - |
### B1 上线前置(必须人工执行)
1. **管理员重新授权**:管理端身份改为 `app.wxapp-escort-admin.role` 包含 `'admin'`。请在库中为管理员账号补齐:
```js
db.users.updateOne(
{ "profile.mobile": "<管理员手机号>" },
{ $set: { "app.wxapp-escort-admin.role": ["admin"] } }
)
```
`role` 缺失的历史账号当前仍放行并打印告警,补齐后即可删除兼容分支(`api/user/middleware/auth.js`、`api/health/utils/permissions.js`)。
2. **密钥轮换**:`api/user/conf.json` 已从索引移除,但历史提交中仍存在微信 AppSecret 与数据库口令,需轮换这两份密钥;是否清理 git 历史由仓库所有者决定。
3. **重启进程**:`api/user` 与 `api/health` 均需重启(conf 与 schema 改动不走热更新)。
## 六、验证与验收
1. 每批完成后:`node -e "import('...')"` 或现有 `npm test` 做语法/单测冒烟;health 无测试脚本时先补最小冒烟。
2. 小程序端影响核对该批涉及的接口清单(上文「小程序端影响」),需改前端时同步提交并记录。
3. 全量完成后在微信开发者工具中回归:登录 → 选档案 → 下单 → 支付提示 → 订单详情改信息 → 取消 → AI 客服问答。
4. 管理端回归:管理员登录 → 全量订单列表 → 状态变更 → 删除订单 → 管理 Agent 查询。