# API 兼容性治理策略

本策略用于管理 Ineed Java 框架中的公开废弃 API。目标不是“看到 `@Deprecated` 就删除”，而是让每个兼容入口都有明确替代项、负责人、引用证据和可复查期限。

当前事实清单由 Phase 53.4 的 `53.4-deprecated-api-registry.json` 维护，并由 `53.4-compatibility-gate.mjs` 从生产 Java 源码重建和校验。

## 扫描边界

Gate 扫描以下五个逻辑根：

1. `java/ineed-core`
2. `java/ineed-parent`
3. `java/ineed-modules-parent`
4. `java/ineed-project-parent`
5. `java/ineed-modules`

扫描排除 `.git`、`.worktrees`、`target` 和 `src/test` 中的 `@Deprecated` 声明。接口声明和实现类 override 按包名、声明类型、方法名及参数类型生成稳定 ID；override 只作为声明项的证据，不另计公开 API。

## 状态机

公开废弃 API 只能处于以下状态之一：

- `retained_external_compatibility`：外部源码或二进制兼容 fixture 仍要求保留。
- `retained_active_usage`：生产或测试仍存在活跃引用。
- `qualified_removal`：满足全部移除前置条件，可进入最窄删除变更。
- `removed`：源码声明已经删除，并保留历史治理记录。

新增 `@Deprecated` 时必须在同一变更中登记 replacement、迁移步骤、owner、证据命令、`review_on` 和 `removal_not_before`。未知声明、重复 ID、wildcard 路径、缺失日期或未绑定 source HEAD 都会使 gate 失败。

## 保留与复查

`review_on` 是下一次强制复查日期，不是自动删除日期；到期后必须重新扫描引用和 compatibility fixture，并更新分类或下一次复查安排。`removal_not_before` 是允许移除的最早日期，必须晚于或等于 `review_on`。

保留项必须持续满足：

- replacement 在当前生产源码中真实存在；
- 迁移步骤能把调用方带到精确 replacement，而不是只给模糊说明；
- owner 对兼容成本和消费方迁移负责；
- evidence command 使用结构化 executable/argv 和精确路径，不使用 glob 或 shell command string；
- source 路径、行号和所属仓库 HEAD 与当前 inventory 一致。

## 删除前置条件

只有同时满足以下四项，registry 才能把条目标记为 `qualified_removal`：

1. **Replacement exists**：replacement 已在生产源码中存在并可被调用。
2. **Zero live references**：生产引用和普通测试引用均为零；不能只运行一次宽泛 grep 就宣称安全。
3. **Compatibility fixture cleared**：外部/legacy consumer compile fixture 已删除、替代或明确证明不再要求旧入口。
4. **Targeted regression passes**：最窄 consumer compile 与目标 Maven regression 全部通过。

满足四项后仍必须遵守 `removal_not_before`。实际删除应作为单独、可回滚的变更，重新运行 registry/source 双向校验，并检查源码兼容与二进制兼容影响。方法签名、默认方法、继承关系或异常类型的改变，即使仓库内引用为零，也可能破坏已编译的外部消费方。

## Nginx 兼容记录的历史示例

以下是现有治理记录的历史条目，用于说明登记字段；不是随 Core 文档发布而更新的业务模块当前状态。执行 Operations 迁移前，重新读取所属仓库与登记表的当前证据。

`NginxCommandExecutor.test(NginxDiscoveryRequest)` 当前分类为 `retained_external_compatibility`：

- replacement：`test(NginxConfigValidationRequest)`；
- 迁移方式：调用方提供精确 revision/config artifact，再构造 exact validation request；
- owner：Operations Nginx；
- `review_on`：`2026-10-31`；
- `removal_not_before`：`2026-12-31`；
- 阻塞原因：`NginxConfigLifecycleTest` 仍编译 legacy-only implementor，证明旧方法继续承担外部源码兼容。

该记录当时未满足移除条件。实际是否允许删除必须重新验证引用、兼容 fixture 和时间约束，不能直接用这段历史摘要作决定。

## 与 Scalar/OpenAPI 文档治理的边界

本 registry 只管理 Java 生产 `@Deprecated` API。Scalar/OpenAPI 文档路径、operation summary、schema 或消费者契约由独立的 API documentation contract 管理，不能把文档状态混入本清单，也不能用本清单替代文档契约验证。