---
id: T-215
title: Admin 候选确认与一次性下单授权
phase: 2
deps:
  - T-214
status: DONE
created: 2026-07-28
context_ref: 56e7a2b
work_branch: null
write_paths:
  - docs/tasks/T-215.md
  - docs/00-ai-start-here.md
  - docs/02-requirements.md
  - docs/04-architecture.md
  - docs/06-tasks.md
  - docs/07-user-stories.md
  - docs/08-interaction-checklist.md
  - docs/api.md
  - docs/current-state.md
  - docs/routes.md
  - backend-api/migrations/**
  - backend-api/internal/domain/**
  - backend-api/internal/usecase/**
  - backend-api/internal/repository/sqlite/**
  - backend-api/internal/transport/httpapi/**
  - backend-api/internal/transport/webui/**
---

## 问题 / 背景

T-214 已给每个候选建立 execution-scoped `candidate_key`，但任务仍由手机上的采购员
提交 human review 并结束。新需求要求 Admin 采购员查看 Top 5 后选择商品，再把明确
授权同步给同一台 Roubao 设备；候选列表或 URL 本身不能成为下单许可。

本任务实现后台选择、逐候选理由和不可变的一次性授权。它不实现设备拉取或拼多多
点击；T-216 才把待投递授权转换为设备命令。

## 冻结合约

### 等待确认

1. 当前 execution 首次成功保存非空候选批次后，任务在同一事务从 `RUNNING` 进入
   `WAITING_CONFIRMATION`，增加 task version，并追加 `CANDIDATES_READY` 事件。
2. 设备 heartbeat 在该状态继续有效，但不能凭候选回传重新开始页面动作。空候选
   仍允许现有 `NO_MATCH/MANUAL_REQUIRED` 终态，不创建授权。
3. Admin 只能为当前活跃 execution、当前 task content hash 和 v7 identity 完整的
   observation 授权；取消已请求、授权到期、终态或旧 execution 一律拒绝。

### Admin 决策与授权

新增管理会话鉴权、CSRF/幂等保护的
`POST /api/v1/tasks/{task_id}/order-authorizations`：

```json
{
  "execution_id": "uuid",
  "task_content_sha256": "64-char-lowercase-hex",
  "expected_task_version": 4,
  "candidate_key": "64-char-lowercase-hex",
  "reason_schema_version": 1,
  "primary_reason_code": "SELECTED_BEST_MATCH",
  "note": "",
  "supersedes_authorization_id": null,
  "items": [
    {
      "candidate_key": "selected-key",
      "label": "ACCEPT",
      "primary_reason_code": "SKU_MATCH",
      "reason_codes": ["SKU_MATCH", "IMAGE_MATCH"],
      "note": ""
    },
    {
      "candidate_key": "rejected-key",
      "label": "REJECT",
      "primary_reason_code": "NOT_BEST_MATCH",
      "reason_codes": ["NOT_BEST_MATCH"],
      "note": ""
    }
  ]
}
```

1. `items` 必须按 candidate key 恰好覆盖当前 execution 的全部 observation，且只有
   顶层 `candidate_key` 对应项为 `ACCEPT`。理由沿用 T-208 schema v1 allowlist 和
   `OTHER` 备注规则；无预算任务仍禁止价格类理由。
2. 仓储在一个 immediate transaction 内把 candidate key 映射回原 ordinal，追加一版
   `candidate_human_reviews`（`actor_device_id=NULL`），再创建一条不可变
   `order_authorizations`。不得信任请求传入的 ordinal、SKU、数量、价格或 URL。
3. 授权快照由服务端读取：task/execution/content hash、candidate key、review ID/
   version、原始 SKU、任务数量、候选规格摘要、组合价格和四个身份指纹。数量只能来自
   原始任务，Admin 不能在选品表单中改写。
4. 授权初始状态为 `PENDING_DELIVERY`，版本从 1 递增；同一 execution 同时最多一条
   active 授权。相同幂等键和请求返回原结果，不新增 review、授权或事件。
5. 设备领取前允许 Admin 改选，但请求必须引用当前 active
   `supersedes_authorization_id`；旧授权原子变为 `SUPERSEDED`，review/授权历史均不
   覆盖。非当前引用、已投递或已执行授权拒绝修改。
6. 每次创建或改选追加 `ORDER_AUTHORIZATION_CREATED` 任务事件，事件只记录授权 ID、
   版本和 candidate key 的短前缀，不记录第三方 URL 或页面全文。

### Admin API/Web

1. Admin 任务详情返回结构化 observations、当前/历史 review 和 order authorization，
   每项展示标题、SKU 摘要、组合价格、受控详情/规格截图、candidate key 和模型理由。
2. `WAITING_CONFIRMATION` 且存在候选时显示单选候选、选择理由、对其余候选批量拒绝
   理由、可选备注和“确认商品并授权下单”按钮。表单服务端展开为逐候选 items。
3. 页面必须明确“仅授权创建待付款订单，不授权付款”；没有可授权候选、数据版本冲突
   或已有不可修改授权时禁用提交并给出可操作状态。
4. Admin API/Web 不请求第三方商品/图片 URL，也不提供由浏览器直接触发设备动作的
   通道。

## 数据模型

v8 新增：

- `order_authorizations`：授权 ID、task/execution、版本、candidate key、内容 hash、
  review、原始 SKU/数量、候选 SKU/价格、四个指纹、状态、创建人、时间和可空
  supersedes ID。
- `admin_order_authorization_requests`：管理员、幂等键、请求 hash、task 和授权引用。

状态预留 `PENDING_DELIVERY/DELIVERED/ACKNOWLEDGED/EXECUTING/CONSUMED/FAILED/
REVOKED/SUPERSEDED`；T-215 只产生 `PENDING_DELIVERY` 和 `SUPERSEDED`。存在授权数据
时 v8 destructive down 必须失败。

## 验收要点

- [x] 非空候选批次原子进入 `WAITING_CONFIRMATION`，重复回传不重复增加事件/version。
- [x] Admin 请求只用 candidate key，完整覆盖候选且每项接受/拒绝都有合法理由。
- [x] review、授权、旧授权 supersede、任务事件和幂等记录原子提交。
- [x] 跨任务/execution、旧 hash/version、伪造 key、缺 identity 和并发双授权被拒绝。
- [x] 授权数量/SKU/价格/指纹均由服务端快照，Admin 不能篡改。
- [x] Admin API/Web 可选候选、查看证据和理由，明确只创建待付款订单且不授权付款。
- [x] v8 migration、Go test/race/vet、根验证和管理页面桌面/移动视口通过。

## 边界

- 不让设备拉取或确认授权；属于 T-216。
- 不重新打开拼多多、选择 SKU/数量或进入订单确认页；属于 T-217。
- 不提交订单、读取订单号或付款；属于 T-218/T-219。
- 不使用 URL、ordinal、模型推荐或旧手机 review 直接代替 Admin 明确授权。

## 执行记录

- 2026-07-28：T-214 实现提交 `56e7a2b` 后领取。决定复用
  `WAITING_CONFIRMATION`，并把 Admin review 与一次性授权放在同一事务；设备投递和
  页面动作继续保持为后续独立权限层。
- 2026-07-28：完成 v8 migration、候选就绪原子状态迁移、Admin API/SSR 表单、
  不可变授权快照、修订/幂等/并发保护和审计历史。`go test ./...`、
  `go test -race ./...`、`go vet ./...` 与根 `init.ps1` 通过。
- 2026-07-28：真实 Gin handler、嵌入模板和 CSS 在 Playwright `1440x900`、
  `390x844` 通过；均无横向溢出，主要控件高度至少 44px，控制台无错误。