diff --git a/T-215.-.md b/T-215.-.md new file mode 100644 index 0000000..e6376b4 --- /dev/null +++ b/T-215.-.md @@ -0,0 +1,154 @@ + +> 同步来源:[`docs/tasks/T-215.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-215.md) · commit `afc651f75a3a` + +--- +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,控制台无错误。