Contracts 实施计划
维护跨仓接口规范、示例和兼容边界
归档内容，只读，不代表现行方案。现行文档见文档总览。
目标与范围
维护跨仓接口规范、示例和兼容边界。保留仓库结构，以 new-api 来源规范及 OceanWay 精确切片替换旧契约；业务模型与运行实现归各服务。
需求输入与确认
从接口需求总表选择正在交付的接口，核对 router/controller/middleware。区分上游参考、字段草案、已实现切片与已联调版本；旧发布包不自动获得新实现资格。
设计与原型
以成功、拒绝、重复、超时未知和恢复样例验证契约。明确身份上下文、计量单位、分页、错误、幂等作用域及可重试性；不以生成大而全的未来协议阻塞具体服务。
API 与文档交付
交付固定源 OpenAPI、来源哈希、精确请求/响应 Schema、内部协议及兼容差异。Go/TypeScript 客户端按实际消费者需求生成与验证，生成物不能宣称为已发布 SDK。详见接口组织和替换基线。
实施步骤与交付物
| 步骤 | 实施内容 | 交付物与退出条件 |
|---|---|---|
| CT-01 来源与目录 | 固定上游规范及哈希，路由按 Owner 分类，登记缺口 | 原规范可追溯；引用和操作清单完整 |
| CT-02 身份与 Key | 将已实现切片补为精确字段规范；全局交接随 Core 设计补齐 | 登录、Key、权限错误样例与实现一致 |
| CT-03 调用与账务 | 授权/预留、价格版本、用量、结算/查询与释放语义 | Core/Edge 用同一组幂等、冲突和恢复样例 |
| CT-04 产品与运营 | 本人价格/账本、客户协议配置、财务命令与权限响应 | CA 操作到接口缺口逐项闭合；敏感字段边界明确 |
| CT-05 媒体与产品关联 | 任务/尝试/结果/费用状态、网关 ID 与业务引用 | 轮询、取消、部分成功与未知核对样例 |
| CT-06 消费者与版本 | 按稳定切片生成所需客户端，做兼容检查及发布准备 | 消费方可编译并调用；破坏性变更显式版本化 |
依赖与接入顺序
与 Core、Edge 的每个交付批次同步；产品私有业务 API 由产品仓负责，涉及共享协议的部分进入 Contracts。对应 CE-00/05 及各服务切片，发布由消费者联调结果驱动。
验收标准
- 所有引用解析、样例校验与来源完整性通过；字段与实际 DTO、权限一致。
- 重复请求、单位与错误语义在调用双方一致；既有兼容范围有回归证据。
- 文档导出的规范与仓库源一致；未实现和未发布部分明确标识。
待定项与后续范围
内部接口提案必须随实现核验；客户端包名、发布版本与事件机制按实际消费确定，不恢复旧全量 B1 协议为前置。
本文定义计划，不累积执行日志。实际版本、完成状态和验证证据见项目进度；任务状态登记到本机工作台，并关联本文步骤。