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 管理，不能把文档状态混入本清单，也不能用本清单替代文档契约验证。