refactor: strengthen client boundaries and quality gates

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

@@ -0,0 +1,31 @@
+# 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 连接和全量回归，再关闭暂留项。