# API 版本与废弃策略

MoreLogin 在每份 OpenAPI 文档的 `info.version` 中发布机器可读的契约快照版本。该版本采用日历格式 `YYYY-MM-DD`，标识的是文档契约，而不是请求 URL 里的版本段。

## 兼容性规则

| 变更 | 归类 | 文档处理方式 |
|  --- | --- | --- |
| 新增可选请求字段、响应字段、操作或枚举值 | 增量变更 | 记入变更日志，并更新全部本地化规格 |
| 澄清说明或修正示例，且不改变运行时行为 | 文档修正 | 当它改变了接入指引时记入 |
| 把可选字段改为必填、删除或重命名字段/操作、收窄可接受值、改变既有语义 | 破坏性变更 | 在移除前提供迁移路径与单独版本化的契约 |
| 给操作标注 `deprecated: true` | 废弃 | 记录替代方案、公告日期，以及在获批后记录计划移除日期 |


客户端应在业务逻辑允许的前提下忽略未知的响应字段与枚举值，这能减少增量发布带来的破坏。

## 废弃元数据

OpenAPI 操作是权威的机器可读位置。被废弃的操作必须包含：

- `deprecated: true`
- 说明中指明替代方案，或明确说明没有替代
- API 变更日志中的公告条目
- 仅在产品与网关负责人批准后才写入的计划移除日期


目前不保证统一的最短废弃期。在明确公布移除日期之前，客户端应把该操作视为仍受支持，但应安排迁移。

## 事实来源

运行时行为始终具有权威性。OpenAPI、示例、本地化副本、端点行为清单与变更日志在 CI 中一并校验，以防契约漂移。

## 验证级别

仓库质量门禁通过，证明 OpenAPI 文件、示例、链接、本地化副本和治理产物在仓库内部保持一致。

页面渲染检查通过，证明抽查的文档路由能够加载和显示，且没有客户端错误。

只有使用凭证对已部署 API 执行冒烟测试，才能证明生产行为与发布契约一致。该仓库默认不执行此测试，因此发行说明必须单独注明是否完成了生产验证。