ai-safety-platform/docs/adr/ADR-006-api-idempotency.md

ADR-006：运行创建与恢复的幂等性

状态

已接受

决策

• 所有 GET 接口只读取本地状态，天然可安全重试。
• provider 的 GET、POST、PATCH、DELETE 配置接口遵循 HTTP 自身语义；同一角色重复创建返回 409。
• POST /providers/{provider_id}/check 不修改配置，但会调用上游模型，重试可能产生额外调用，因此由调用方按需重试。
• POST /runs 支持可选 Idempotency-Key。平台持久化键及请求参数指纹；相同键和相同参数返回同一运行，不重复投递任务；相同键不同参数返回 409。
• POST /auth/refresh 强制使用 Idempotency-Key。同一旧 refresh token 和同一键稳定派生后继 token，并使用持久化消费状态返回相同 access token 过期时间；旧 token 换键视为重放攻击并撤销整个会话。
• 未进入续约窗口的 refresh 返回 409，不消费 token 或占用幂等键；到达窗口后可使用新键正常续约。
• POST /runs/{run_id}/resume 以已持久化结果为检查点；当前进程内运行中的重复恢复不再投递任务。
• POST /runs/{run_id}/retry-errors 仅接受 completed_with_errors：删除 execution_status=error 的结果后立即把状态改为 pending；同一请求再次到达时返回 409，不会重复清理成功结果或 verdict=fail 的已完成结果。
• POST /runs/{run_id}/results/{execution_id}/retry 删除指定结果后立即把 Run 改为 pending；同一请求的重复提交返回 409，不会再次删除或投递。
• PATCH /runs/{run_id} 是幂等取消：已进入终态时返回 409；DELETE 只接受终态运行，重复删除返回 404。

约束

幂等键唯一性由 SQLite 唯一约束保证，适用于多请求并发。恢复任务的活动标记是进程内状态；多进程任务执行需要引入共享任务队列或数据库租约后再扩展。