# 依赖版本兼容性审计基线（v1.0）

- 版本：v1.0
- 日期：2026-03-27
- 状态：生效（发布前强制 Gate）
- 目标：把“依赖可用”升级为“依赖可审计、可回滚、可阻断”
- 关联文档：
  - `docs/technical_architecture_optimized_v2_2026-03-18.md`
  - `docs/acceptance_gate_single_source_v1_2026-03-18.md`
  - `docs/subapi_integration_risk_controls_execution_tasks_v1_2026-03-17.md`

---

## 1. 审计对象与冻结策略

| 层 | 对象 | 冻结规则 |
|---|---|---|
| Runtime | Go / Node / JDK / Python | 仅允许 LTS 或已验证小版本 |
| Data | PostgreSQL / Redis | 生产固定主版本，升级必须灰度 |
| 服务依赖 | subapi / provider SDK | 固定精确版本（`X.Y.Z`） |
| 第三方库 | go mod / npm / maven | 锁文件变更必须触发兼容测试 |
| OS 镜像 | 基础镜像 digest | 必须可追溯到 SBOM |

---

## 2. 必交付证据

每次发布候选版本必须提供：

1. `SBOM`：`reports/dependency/sbom_<date>.spdx.json`
2. `锁文件差异`：`reports/dependency/lockfile_diff_<date>.md`
3. `兼容矩阵`：`reports/dependency/compat_matrix_<date>.md`
4. `风险清单`：`reports/dependency/risk_register_<date>.md`

无上述四项，发布门禁直接阻断。

---

## 3. 兼容性审计流程（分阶段）

### 3.1 Pre-Merge（开发合并前）

1. 检查 `go.mod/go.sum`、`package-lock.json/pnpm-lock.yaml`、`pom.xml` 变化。
2. 依赖变更自动分类：Patch/Minor/Major。
3. Major 变更必须附“兼容影响评估 + 回滚预案”。

### 3.2 Nightly（每日）

1. 运行依赖漏洞扫描（CVE/SCA）。
2. 运行契约回归（Schema/Behavior）。
3. 生成依赖健康趋势（新增高危漏洞数）。

### 3.3 Pre-Release（发布前）

1. 运行完整兼容回归（兼容三重 Gate + SUP Gate）。
2. 校验运行时与数据层版本匹配矩阵。
3. 通过后冻结候选构建包与镜像 digest。

### 3.4 Post-Release（发布后 24h）

1. 监控新增依赖告警、崩溃、性能回退。
2. 若触发 P0/P1 依赖事故，执行自动回滚到上一稳定版本。

---

## 4. 阻断规则（必须）

1. `dependency_compat_audit_pass_pct < 100%`：阻断发布。
2. 新增 Critical CVE 且无缓解：阻断发布。
3. Major 依赖变更无回滚演练记录：阻断发布。
4. subapi/provider SDK 精确版本未锁定：阻断发布。
5. 依赖清单与运行镜像不一致：阻断发布。

---

## 5. 推荐版本兼容矩阵（首版）

| 组件 | 基线版本 | 兼容范围 | 备注 |
|---|---|---|---|
| Go | 1.21.x | 1.21.x | 不跨主版本 |
| PostgreSQL | 15.x | 15.x | SQL 与索引以 PG15 语法为准 |
| Redis | 7.x | 7.x | 限流与缓存行为基于 Redis7 验证 |
| subapi | 精确 `X.Y.Z` | 同 patch | Minor 升级需完整回归 |
| Node（前端） | 20.x LTS | 20.x | 锁文件必须纳入审计 |

---

## 6. 与发布门禁对齐

1. 依赖兼容审计结果接入 `acceptance_gate_single_source` 指标 `M-017`。
2. 分阶段测试质量接入指标 `M-018`。
3. 任一未达标，不得进入 `GO` 结论。