cmbuyer/docs/tasks/T-205.md

---
id: T-205
title: purchase attempt、事件与执行摘要 API
phase: 2
deps: [T-210]
status: TODO
created: 2026-08-04
vikunja_task_id: 35
context_ref: cd47d0c
work_branch: task/t-205-attempt-events
needs_device: false
needs_human_review: false
write_paths:
  - docs/tasks/T-205.md
  - admin/migrations/00007_attempt_events.sql
  - admin/internal/migrations/migrations_test.go
  - admin/internal/attempts/**
  - admin/internal/taskclaim/**
  - admin/internal/server/**
  - admin/cmd/server/**
  - admin/README.md
  - docs/api.md
  - docs/04-architecture.md
---

<!-- BEGIN VIKUNJA EXPORT id=35 synced=2026-08-04T14:41:47Z sha256=870653415736bd7756b058467f0d6ea0114a78dba1c97ed62115067e07c32e8a -->
## 问题 / 背景

T-302 负责创建并租赁唯一 purchase attempt，T-103 提供已取证的规格选择与闸门一能力。后续单趟执行需要把每个安全步骤以最小结构化事件追加到采购服务，并在围栏前失败时形成不可覆盖的执行摘要。T-205 只记录既有 claim/attempt 的事实和安全失败；不创建 attempt、不释放授权、不建立提交围栏、不点击或付款。

## 关联需求与交互

- 功能：F-006、F-007。
- 用户故事：US-003、US-004、US-005。
- 依赖：T-210；T-107/T-204/T-302/T-301 由 T-210 传递满足。
- 后续消费者：T-206 状态视图、T-307 客户端 attempt sink、T-305 围栏前 dry-run、T-208 提交围栏。
- API：`POST /api/v1/tasks/{id}/events`、`POST /api/v1/purchase-attempts/{aid}/fail`。

## 方案

1. 新增 `00007_attempt_events.sql`，保存 append-only attempt events、批次幂等请求和必要执行摘要；事件以 attempt 内单调序号、事件 id/批次 id、固定 step/outcome/reason、服务端接收时间及允许的最小字段组成。数据库约束禁止更新/覆盖旧序号、跨 task/attempt 或围栏后继续写。
2. 复用 T-302 的统一 claim validator：每个请求都绑定当前设备 Bearer、session、task、attempt、generation、claim token 和未过期租约；认证在 body 前，业务事务在线性化位置再次验证设备 ACTIVE、claim/authorization/attempt 归属与状态。旧 generation/token、跨设备/会话、租约或授权过期均不能写事件。
3. 事件 API 只接受有界批次和严格 JSON。每个事件的 step/outcome/reason 来自版本化白名单，不接收自由页面文本、XML、地址、手机号、路径、token、选择器、坐标或动作脚本。金额为规范正十进制字符串，数量为正整数；未知字段、额外 JSON、序号缺口/倒退/重复异载荷全部拒绝。
4. 同一 batch id 同载荷在响应丢失/服务重启后重放原结果；同键异载荷冲突。一个事务内校验整批连续性、步骤状态机和 summary 兼容性后全批追加，任一事件非法则零写入。
5. 三条成功步骤固定为：`GATE_1_PASSED` 只携带 color、size、unit_price 和 `SKU_PANEL_GATE_1` asset id；`GATE_2_PASSED` 只携带 color、size、quantity、unit_price 和 `SKU_PANEL_GATE_2` asset id；`GATE_3_PASSED` 只携带 color、size、quantity、confirm_amount、submit_control_text、submit_control_match_count、submit_control_enabled 和 `ORDER_CONFIRM_GATE_3` asset id。每个 asset 必须属于同一 task/attempt/device/generation 且 kind 精确匹配；缺失、错 kind、跨归属或证据未明确成功时整批零写入。
6. 第一个明确的执行开始事件只允许把 attempt `CLAIMED→ORDERING`、task `CLAIMED→ORDERING`；不得隐式续租。后续事件只在 ORDERING 中追加。规格、两次规格面板价格、数量读回、确认页金额仅由对应固定成功 step 写入 summary，不能由客户端直接覆盖已有摘要。
7. 围栏前 fail API 只接受固定 reason：`DEVICE_UNAVAILABLE`、`APP_VERSION_MISMATCH`、`PRODUCT_OPEN_FAILED`、`SKU_PANEL_UNAVAILABLE`、`SKU_SELECTION_MISMATCH`、`GATE_1_PRICE_INVALID`、`QUANTITY_MISMATCH`、`GATE_2_PRICE_INVALID`、`ORDER_CONFIRM_UNAVAILABLE`、`GATE_3_MISMATCH`、`SUBMIT_CONTROL_NOT_UNIQUE`、`CLAIM_NOT_CURRENT`、`AUTHORIZATION_EXPIRED`、`EVIDENCE_UPLOAD_UNRESOLVED`、`PAGE_RESULT_UNKNOWN`、`STEP_TIMEOUT`、`DRY_RUN_COMPLETED_BEFORE_FENCE`，以及已记录的最后安全步骤。幂等地把当前 attempt 置 FAILED、task 置 NEEDS_MANUAL，并写终止事件/finished_at。authorization 和 claim 保持占用，等待 T-207 人工检查后显式关闭；失败请求不自动回 DRAFT、不释放、不转领。`EXTERNAL_PAYMENT_HANDOFF`、`SECURITY_CHALLENGE` 与 `UNKNOWN` 是围栏后 result observation，不得作为围栏前失败码。
8. 已失败、已围栏、存在 order_submission、claim/授权/租约不再有效时拒绝新事件或新的失败结果。围栏相关状态只能由 T-208 创建，T-205 不读取或返回 `click_permitted`。
9. 原始截图继续走 T-204/T-306；事件只引用服务端已有的受控 evidence asset id（如需要），不得上传文件或枚举本地证据目录。完整 XML 永不上传。

## 验收要点

- Migration 覆盖升级/重开、外键/唯一/append-only 约束、既有事实与安全降级保护。
- 覆盖严格 HTTP/JSON、body 前认证、claim/session/generation/token/lease/authorization 校验和跨设备拒绝。
- 覆盖批次原子性、序号连续、并发追加、相同 key 重放、异载荷冲突、服务重启恢复。
- 覆盖步骤状态机及 summary 单向写入；闸门金额保持十进制字符串，冲突值不得覆盖。
- 覆盖 `CLAIMED→ORDERING` 唯一转换、固定失败到 NEEDS_MANUAL、重复失败幂等、失败后无事件、授权/claim 不释放。
- 静态检查确认没有 selector/coordinate/free script、claim 创建/续租、围栏、提交订单点击、付款或自动重试能力。
- `go test ./...`、`go test -race ./...`、`go vet ./...`、`go build ./...`、完整 init、上下文校验与 diff-check 全部通过。

## 执行记录

### 2026-08-04T13:44:42Z · ila

2026-08-04 与 T-302 恢复契约定值：第一个执行开始事件在同一事务把 attempt/task 从 CLAIMED 转为 ORDERING，并把 task.version 恰好递增一次；后续事件不再递增。T-302 同会话恢复只接受 ORDERING 且当前版本等于领取快照版本+1，其他版本漂移转人工。

### 2026-08-04T14:39:03Z · ila

2026-08-04 契约收紧：T-205 改为依赖 T-210、迁移 00007；冻结 GATE_1/2/3_PASSED 的完整字段与对应 evidence kind，并冻结围栏前失败码和 DRY_RUN_COMPLETED_BEFORE_FENCE。围栏后 observation 不得伪装成围栏前失败。
<!-- END VIKUNJA EXPORT -->

## 边界

- T-205 只向 T-302 已创建且由当前设备/会话持有的 attempt 追加固定结构事件和摘要；不得创建
  purchase attempt、领取任务、续租、签发或释放授权。所有权、generation、claim token、租约、
  authorization 与状态任一不匹配时零业务写入。
- 事件必须 append-only、attempt 内严格连续且批次全有或全无；重放只能返回原结果。任何旧序号、
  缺口、异载荷、跨 attempt、跨设备或并发冲突不得覆盖、跳过或重排既有事实。
- 只接收版本化白名单中的 step/outcome/reason 及该步骤必需的规范金额、正整数数量和受控引用。
  不接收自由页面文本、完整 XML、地址、手机号、本机路径、token、动作脚本、选择器或坐标。
- 三条成功步骤只能是 `GATE_1_PASSED`、`GATE_2_PASSED`、`GATE_3_PASSED`，且分别引用同一
  task/attempt/device/generation 下精确 kind 为 `SKU_PANEL_GATE_1`、`SKU_PANEL_GATE_2`、
  `ORDER_CONFIRM_GATE_3` 的已成功 asset。缺证据、错 kind、跨归属或上传结果不明时零事件写入。
- 实际规格、闸门一/二单价、数量读回和确认页金额只能由对应固定成功步骤首次写入执行摘要；后续
  冲突值必须拒绝，不能最后写入者覆盖。闸门三还必须首次固定提交控件精确文案、匹配数和启用态；
  金额始终是十进制字符串，不用浮点数。
- 第一个执行开始事件必须在同一事务中把 attempt/task 从 `CLAIMED` 转为 `ORDERING`，并把 task
  `version` **恰好递增一次**；后续事件不得继续递增。T-302 的同会话恢复只可把 ORDERING 解释为
  领取快照版本加一，其他版本漂移必须转人工，不能用“状态是 ORDERING”跳过版本一致性。
- 围栏前失败只把 attempt 置 `FAILED`、task 置 `NEEDS_MANUAL` 并留下终止事实；authorization 与
  claim 保持占用，等待 T-207 人工检查。不得自动回 `DRAFT`、释放、重新授权、转领或重试页面动作。
- 围栏前 reason 必须来自任务方案冻结的精确白名单，包含 `DRY_RUN_COMPLETED_BEFORE_FENCE`；
  `EXTERNAL_PAYMENT_HANDOFF`、`SECURITY_CHALLENGE` 与 `UNKNOWN` 只属于围栏后 result observation，
  不得伪装成可恢复的围栏前失败。
- 不实现或引用 submission fence、`click_permitted`、订单结果、提交订单点击。不得编写支付、免密
  支付、先用后付或任何扣款控件代码；第一趟试选/围栏前路径不得可达下单函数。
- 不在 T-210 三种证据 kind 之外继续扩展截图，不上传 XML/manifest/目录，不接触真机页面判据或
  client 代码。