cmroubao/docs/tasks/T-205.md

---
id: T-205
title: 实现原子 claim、租约和状态机
phase: 2
deps:
  - T-203
  - T-204
status: DONE
created: 2026-07-26
context_ref: 49db5b8
work_branch: main
write_paths:
  - README.md
  - backend-api/**
  - docs/00-ai-start-here.md
  - docs/02-requirements.md
  - docs/03-tech-stack.md
  - docs/04-architecture.md
  - docs/05-coding-rules.md
  - docs/07-user-stories.md
  - docs/08-interaction-checklist.md
  - docs/api.md
  - docs/current-state.md
  - docs/routes.md
  - docs/tasks/T-205.md
  - progress.md
---

## 问题 / 背景

T-203 已能创建 `PENDING` 任务，T-204 已建立 BUYER + 预授权设备联合身份，但 App
还不能安全领取任务。现有正式文档只给出接口草图，未解决 claim token 只返回一次时
如何在响应丢失后安全重放，也没有固定设备就绪新鲜度、运行中租约过期、取消确认和
并发领取的精确语义。T-206 在这些合约固定前不能接入 HTTP TaskSource。

## 关联需求与交互

- 功能：F-003、F-007。
- 用户故事：US-003、US-006。
- 交互：IX-005、IX-008；本任务只实现后端，Android 页面接入属于 T-206。
- 架构/API：任务状态机、`devices/heartbeat`、`claim-next`、`start`、任务 heartbeat、
  `reference-image`、`release` 和取消安全停止。

## 已定合约

1. 所有设备接口只接受有效 BUYER Bearer token；认证上下文中的 `user_id/device_id`
   是权威身份。请求中的 `device_id` 必须与上下文一致，不能代表其他设备。
2. App 在发起 claim 前生成独立的 256 bit Raw URL `X-Claim-Token` 并先安全保存，
   同时生成独立 `Idempotency-Key`。服务只保存 claim token 的 SHA-256，响应不回显
   原值；网络结果不确定时必须复用同一组值。
3. claim 幂等记录按用户、设备、操作和 key 隔离，请求 hash 包含 claim token hash。
   每次成功领取递增 `claim_generation`。同 key 同请求在同一 generation 的租约仍
   属于该设备时返回同一任务；同 key 不同请求返回 `409`；原领取已释放、取消或被
   过期回收时返回稳定 `409 CLAIM_REPLAY_EXPIRED`。无任务的首次结果记录为
   `NO_TASK`，同 key 重放仍返回 `204`。
4. 设备 heartbeat 记录服务端时间、App/Android/拼多多版本和两个确定性就绪位：
   无障碍已连接、拼多多已安装。客户端上报的活跃任务只用于一致性检查，服务端任务
   归属是权威。heartbeat 超过 2 分钟或任一就绪位为 false 时禁止领取。
5. 领取在单个 SQLite immediate transaction 内完成。若当前设备自己仍有一条已过期
   `CLAIMED`，先回收该任务，避免设备唯一归属冲突；否则在 `PENDING` 或已过期
   `CLAIMED` 中按创建时间最早、ID 最小选择。一个任务只能归属一台设备；同一设备
   只允许一个未过期 `CLAIMED` 或任意 `RUNNING/WAITING_CONFIRMATION` 任务。
6. 初始 claim 租约默认 10 分钟。只有当前用户、当前设备、匹配 token hash 且租约
   未过期时可以 start、release、heartbeat 或确认取消。所有到期计算只使用服务端
   UTC 时钟，不信任 `client_time`。
7. `start` 只允许 `CLAIMED -> RUNNING`，在同一事务创建唯一 execution attempt，
   并把运行租约改为默认 90 秒；请求携带 claim 响应的 `expected_version`，
   `Idempotency-Key` 同请求重放返回同一 execution。
8. 运行 heartbeat 每 30 秒计划调用，只有 `RUNNING/WAITING_CONFIRMATION` 且
   execution/generation 匹配时才更新 step、`last_seen_at` 和 90 秒运行租约。
   过期运行租约拒绝续租和后续自动操作，任务保持当前非终态且绝不自动回到队列，
   防止失联设备与新设备重复执行；恢复/失败归档后置。
9. `release` 只允许未过期 `CLAIMED -> PENDING`，请求必须匹配 `expected_version`，
   并清除用户、设备、token 和租约。已开始任务不能 release。过期 `CLAIMED` 可由
   下一次 claim 原子回收。
10. 管理取消 `PENDING/CLAIMED` 时立即进入 `CANCELED`；`RUNNING` 或
    `WAITING_CONFIRMATION` 只设置取消请求，不伪装为已停止。任务 heartbeat 返回
    `cancel_requested=true`，App 在安全检查点以 `expected_version` 调用
    `cancel-ack` 后才进入 `CANCELED` 并结束 execution。
11. 每次状态迁移递增 `version` 并追加带 actor 的任务事件；heartbeat 只更新租约和
    当前 step，不追加高频事件。claim/start/heartbeat/transition 响应都返回当前
    `version`、`claim_generation`、服务端时间和租约到期时间。终态不可回退，非法
    状态、错误设备、错误 token、execution 不匹配和过期租约使用彼此稳定但不泄露
    其他任务内容的错误码。
12. 三个时长通过配置提供安全默认值和上下界：claim lease 10 分钟、运行 lease
    90 秒、设备 heartbeat TTL 2 分钟。T-205 不启动后台定时清理器。
13. 参考图不暴露资产存储路径。App 只能通过 claim 响应中的 task-scoped URL，
    携带当前 BUYER token、设备身份、`X-Claim-Token` 和 `claim_generation` 读取；
    服务端同时校验当前状态和未过期租约，并返回 `private, no-store` JPEG。

## 方案

1. 新增 `00004_claims_and_lifecycle.sql`，扩展任务 claim/cancel 字段、设备就绪字段，
   增加 execution 与生命周期幂等表，并扩展任务事件枚举；迁移必须可空兼容历史数据。
2. 在 domain 增加 claim、execution、状态迁移和就绪实体；在独立
   `LifecycleService` 中完成输入校验、token hash、服务端时钟、错误映射和响应模型。
3. SQLite repository 使用显式事务完成 claim/reclaim、start、release、heartbeat、
   取消请求/确认和幂等重放；所有条件更新同时校验状态、归属、token、租约和版本。
4. Gin 增加独立 BUYER 设备路由组，复用 T-204 Bearer middleware；handler 只解析
   header/body、读取认证 principal、调用 usecase 和映射稳定响应。
5. 管理取消从仅 PENDING 扩展为上述安全语义；管理详情返回 claim、execution 和
   取消请求的非秘密摘要，永不返回 claim token/hash。
6. claim 响应只给出 task-scoped 参考图 URL；图片 handler 在读取本地资产前重新
   授权当前 claim，避免长期资产 URL 或跨任务枚举。

## 验收要点

- [x] migration 可 up/down/up，历史任务保持可读，数据库不存在原始 claim token。
- [x] heartbeat 身份、版本长度、就绪位和新鲜度校验正确，客户端不能冒充设备。
- [x] 多 goroutine/多连接并发 claim 同一任务时精确一个成功，不重复分配。
- [x] 同一设备不能领取第二条活跃任务；不同设备可以领取不同任务。
- [x] claim 首次响应丢失后用同 key/token 重放得到同一任务；冲突/过期重放被拒绝。
- [x] 无任务的幂等重放保持 204，不因稍后新增任务改变旧请求结果。
- [x] start 精确创建一个 execution；重复 start 同 key 返回同一 execution。
- [x] 错误设备、错误 token、过期 CLAIMED 租约、非法状态均不能 start/release。
- [x] 当前 claim 才能读取参考图，错误 token/generation/设备或过期租约均被拒绝。
- [x] RUNNING heartbeat 续租并返回取消标志；过期运行租约不会回队列或被其他设备领取。
- [x] 管理取消活跃任务只请求停止；App 安全确认后才进入 CANCELED。
- [x] 事件 actor、version、execution attempt 和状态迁移可审计，响应/日志不泄露秘密。
- [x] Go test/race/vet/gofmt、迁移/HTTP 并发 smoke、根脚本全部通过。

## 边界

- 不实现 Android HTTP TaskSource、token 安全存储、前台服务或页面；属于 T-206。
- 不实现候选、执行证据、批量事件、完成/失败结果归档；属于 T-207。
- 不实现后台通知、WebSocket、跨实例锁、自动重试或多设备调度运营页面。
- 不把过期 `RUNNING` 自动回到 `PENDING`，也不允许任何路径提交订单或支付。
- 不提交运行数据库、claim/access token、真实设备心跳或私有订单样本。

## 执行记录

### 2026-07-26：任务开始

- 基于提交 `49db5b8` 开始，工作区干净；T-203/T-204 依赖均已完成。
- codebase-memory MCP 本轮仍未暴露 graph 工具，按项目规则回退到 `rg` 和定点读取。
- 先固定 client-generated claim token、安全幂等重放、就绪 TTL、租约过期与取消确认
  语义，避免在迁移和 handler 写完后再改变跨端协议。

### 2026-07-26：实现与验证完成

- 新增 migration 00004、生命周期领域/用例/SQLite 仓储和 BUYER Gin 路由；管理端
  取消扩展为 `PENDING/CLAIMED` 立即取消、`RUNNING/WAITING_CONFIRMATION`
  请求安全停止，并在任务详情展示非秘密 claim/execution 摘要。
- `go test -count=1 ./...` 共 192 个测试通过；全包 `go test -race -count=1 ./...`、
  `go vet ./...`、`gofmt -d .`、三入口 Windows 构建和根 `init.ps1` 均通过。
- migration CLI 完成 `status -> up -> up -> down -> up`，第二次 up 无重复应用；
  两个独立数据库连接和真实 TCP 并发 claim 都验证同设备精确一个成功。
- Playwright 连接真实 Gin/SQLite 流程验证任务详情在 1440x900、390x844、360x800
  无横向溢出、破图或弹窗重叠；运行中“请求安全停止”分支由 SSR 测试覆盖。
- 独立审查发现并修复 start 后 claim 幂等重放被误判过期的问题；同设备优先恢复
  自己过期 CLAIMED 的亲和策略已补充文档和测试。未发现 High 严重度问题。