18 KiB
api 审查整改计划(health + user)
来源:2026-10-24 对
api/的静态审查(30 项)。 本文是整改的唯一执行清单:每项含位置、方案、小程序端影响、验证方式与状态。 仓库结构:根仓库 +api/user、api/health、ui/wxapp_escort、ui/wxapp_escort_admin各自独立 git,提交按仓库分开。
一、执行原则
- 根因合并:同一根因的多处问题一次改完、一次提交,不做零散单点补丁。
- 先契约后运行时后清理:先服务端契约(鉴权/校验/字段),再运行时防护(限流/WS/超时),最后死代码与技术债。
- 每次改动必须核对小程序端:
ui/wxapp_escort(用户端)与ui/wxapp_escort_admin(管理端)是否调用该接口、是否依赖被改字段/错误文案/HTTP 语义。 - 客户端兼容优先:能不破前端就不破;必须破时同步改前端,并在同一批次内提交。
- 不引入行为性回归:响应包结构
{code,msg,data}与 HTTP 200 约定暂不改变(见 D4)。 - 每批一次提交:提交信息用简洁短句,说明「为什么」。
二、批次总览
| 批次 | 主题 | 条目 | 交付判定 |
|---|---|---|---|
| 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、healthapp.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 上线前置(必须人工执行)
- 管理员重新授权:管理端身份改为
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)。 - 密钥轮换:
api/user/conf.json已从索引移除,但历史提交中仍存在微信 AppSecret 与数据库口令,需轮换这两份密钥;是否清理 git 历史由仓库所有者决定。 - 重启进程:
api/user与api/health均需重启(conf 与 schema 改动不走热更新)。
六、验证与验收
- 每批完成后:
node -e "import('...')"或现有npm test做语法/单测冒烟;health 无测试脚本时先补最小冒烟。 - 小程序端影响核对该批涉及的接口清单(上文「小程序端影响」),需改前端时同步提交并记录。
- 全量完成后在微信开发者工具中回归:登录 → 选档案 → 下单 → 支付提示 → 订单详情改信息 → 取消 → AI 客服问答。
- 管理端回归:管理员登录 → 全量订单列表 → 状态变更 → 删除订单 → 管理 Agent 查询。