OpenAPI 规范

预期结果：为这套系统设计或检查 OpenAPI 规范 (OpenAPI Specification)，并让数据保持正确、安全且容易维护。 用户场景：合作伙伴 API 描述 `POST /claims`、必填的幂等请求头、OAuth 作用域、JSON Schema 规则、201 与问题响应，以及使用假数据的示例。CI 会拦下没有写进文档的破坏性响应。自动生成的客户端仍要审查，不能直接假设正确。 技术概念或控制措施：OpenAPI 规范 (OpenAPI Specification)。 适用理由：把它当成可供审查的契约，用于文档、验证、模拟服务器、客户端生成和兼容性检查。 不应使用的情况：自动生成的文档不能代替真实示例和授权测试。也不能代替运行时验证或清楚的生产环境行为。 工程要求：定义输入、输出、接口约定，以及任何情况下都不能破坏的规则。说明授权与输入检查范围。定义失败、超时、重试和重复执行只生效一次的规则。也要定义数据迁移与兼容限制。 运营要求：加入监控信号与隐藏敏感数据的日志。设置容量上限并写好操作手册。测试恢复与回到上一版的流程。 验收标准：接口约定与失败路径测试通过。重试或部分失败时，数据与授权规则仍正确。性能上限、监控、恢复与回到上一版的方法都已验证。 证据与限制（证据边界）：正式文档仍可能是草案、候选版或最终版。请查看文档状态，也要确认浏览器或平台是否支持。 待确认：程序运行环境、数据位置、流量形态、数据一致需求和安全边界。也要确认兼容周期、服务目标（SLO）与恢复上一版的限制。