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

18 KiB
Raw Blame History

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'。请在库中为管理员账号补齐:
    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 查询。