lislgosms/docs/api-dependency-advisory-matrix-20260828.md

API 依赖公告治理矩阵（2026-08-28）

结论

本轮重新执行 npm audit --omit=dev --json，审计对象从 9 项降至 5 项：Swagger、js-yaml、fast-uri 和 brace-expansion 的可安全升级路径已完成；剩余 5 项全部属于 Prisma CLI 的同一条开发/迁移工具链，不进入 API 运行时请求处理路径，且审计给出的唯一自动修复是把 Prisma 7.9.0 降级到 6.12.0，属于破坏性主版本变更，因此本轮不执行 audit fix --force。

已修复公告

公告/包	原路径	处理	回归要求
js-yaml / GHSA-5p4m-2wfm-xmqj	@nestjs/swagger -> js-yaml < 4.3.1	升级 @nestjs/swagger 至 11.4.7，并锁定 js-yaml 4.3.1	API build、Swagger 启动、全量 Jest
fast-uri / GHSA-7p8r-x3mc-p8w7	OpenAPI/JSON schema 依赖树	override 至 3.1.5	API build、全量 Jest
brace-expansion / GHSA-rgw5-rvv9-x895	Excel/归档工具的 minimatch 兼容链	兼容适配器升级到有界实现 5.0.9	security:verify 中真实 require 与 legacy minimatch 验证
@nestjs/swagger 聚合项	由 js-yaml 引起	随上述升级关闭	同上

暂留公告

审计项	实际路径	运行时暴露面	决策
prisma	根开发依赖 prisma@7.9.0	仅生成客户端和执行迁移；API 运行时使用 @prisma/client	暂留，等待 Prisma 7/8 提供无破坏升级
@prisma/config	prisma -> @prisma/config -> deepmerge-ts	CLI 解析受控本地配置，不接受 HTTP 用户递归对象	暂留并监控上游
deepmerge-ts / GHSA-ggr8-5vv4-36mx	同上	不在 API 请求路径调用	暂留；禁止用不可信配置执行 Prisma CLI
@prisma/dev	prisma -> @prisma/dev -> valibot	Prisma CLI 开发工具链	暂留并监控上游
valibot / GHSA-5qjj-4xww-7phc	同上	不在 API 请求路径调用	暂留并监控上游

门禁与复核

• tools/security/verify-dependency-mitigations.mjs 固定验证修复版本及 brace CommonJS 兼容行为。
• 部署仍使用受控 package-lock.json 和 npm ci，不执行 npm audit fix --force。
• 每次依赖升级重新运行两份 lock 的审计、API/前端构建、API 全量测试和真实测试环境健康检查。
• Prisma 上游出现保持主版本兼容的修复后，优先在独立分支验证 prisma generate、95 项迁移、PostgreSQL 连接和全量回归，再关闭暂留项。