From d23aa481599b7ec866d2f93bf9a32bbeb232c66c Mon Sep 17 00:00:00 2001 From: lik Date: Sat, 24 Oct 2026 22:00:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20api=20=E5=AE=A1?= =?UTF-8?q?=E6=9F=A5=E6=95=B4=E6=94=B9=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按根因拆为 5 批 30 项,记录小程序端影响、验证方式与四个产品决策结论。 --- doc/api-review-plan.md | 246 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 doc/api-review-plan.md diff --git a/doc/api-review-plan.md b/doc/api-review-plan.md new file mode 100644 index 0000000..6c67701 --- /dev/null +++ b/doc/api-review-plan.md @@ -0,0 +1,246 @@ +# 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 查询。