baozaotumao2025
20 lines
1.9 KiB
Markdown
20 lines
1.9 KiB
Markdown
# 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 唯一约束保证，适用于多请求并发。恢复任务的活动标记是进程内状态；多进程任务执行需要引入共享任务队列或数据库租约后再扩展。
|