docs(t215): freeze admin order authorization contract

This commit is contained in:
QiuSW
2026-07-28 12:25:26 +08:00
parent 56e7a2be33
commit 16c2ea410a
10 changed files with 272 additions and 16 deletions
+20
View File
@@ -259,6 +259,26 @@ T-204 已实现的 `TASK_CREATED`、`TASK_CANCELED` 事件包含可空
`cancel_requested=true`,只有 App 在安全检查点调用 `cancel-ack` 后才进入
`CANCELED` 并结束 execution。
### `POST /api/v1/tasks/{task_id}/order-authorizations`
T-215 起由有效 ADMIN 会话对当前 `WAITING_CONFIRMATION` execution 创建一次性待投递
授权。Cookie API 请求必须带 `X-CSRF-Token` 和 `Idempotency-Key`;请求体见
[`T-215`](tasks/T-215.md)。关键规则:
- 顶层和每个 item 只引用 v7 `candidate_key`,不得用 ordinal 或 URL 选品。
- `items` 恰好覆盖当前 execution 全部 observation,只有顶层 key 对应项为
`ACCEPT`;所有项必须包含 T-208 schema v1 合法理由。
- `execution_id`、task content hash 和 expected task version 必须同时匹配;服务端
从任务/observation 读取 SKU、数量、候选规格、价格和身份指纹写入授权快照。
- 首次成功返回 `201` 和 `PENDING_DELIVERY` 授权;同 key 同 body 重放返回相同
授权并带 `replayed=true`,同 key 不同 body 返回 `409`。
- 未投递前改选必须引用当前 `supersedes_authorization_id`;旧授权变为
`SUPERSEDED`。已投递或不是最新授权时返回 `409`。
Admin `GET /api/v1/tasks/{task_id}` 同时返回当前及历史
`order_authorizations`。授权仅允许 T-216 设备命令领取,不代表浏览器可以直接操作
手机,也不授权付款。
## 设备与领取
### `POST /api/v1/devices/heartbeat`