30 Client 领取 Admin 创建的采集任务

类型：需求（跨模块联调）
父级大工单：#1
所属 MVP / 版本：#2 / MVP
状态：已完成，用户验收通过
日期：2026-08-07
Gitea 工单：#30

背景与目标

Admin 已能创建并展示采集任务，但 Client 的 HTTP Gateway 只有登记能力，“获取任务”按钮也没有事件处理，所以任务一直停在待分配状态。

本任务接通一次安全的单次领取流程：用户点击一次，只领取一个采集任务，在后台保存到本地 SQLite，然后刷新任务表格。不连接手机、不执行采集，也不领取采购任务。

最终方案

新增 TaskClaimGateway 窄接口，任务页不依赖登记和结果提交能力。
HttpAdminGateway.claim_next 请求 /api/v1/client/tasks/claim，请求头包含 Client 编号和请求编号。
claim 固定声明 supported_types: ["collect"] 和 purchase_mode: dry_run。
Admin 返回 204 时返回 None，作为“暂无任务”处理。
使用真实 Admin 字段名显式创建 AdminTask，不使用字典自动展开。
ClaimTaskWorker 使用 QObject + moveToThread，在后台完成配置读取、HTTP 请求和 SQLite 写入。
当前 Client 编号或 Android 设备号未保存时，不发送 claim，并提示先去设置页保存。
AdminTask 显式转换成 NewClaimedTask，原始任务内容保存在 admin_payload。
本地保存成功后才通知主线程刷新表格。
重复任务显示“本地已有”；本地保存失败时状态和 InfoBar 都包含任务编号。
每次点击只请求一次，领取期间禁用按钮，结束后恢复“获取任务”。
窗口关闭会断开 UI 结果信号；如果 claim 已经成功，Worker 仍优先完成本地保存。
不修改 Mock Gateway、PDD 页面 UI 文件、主窗口、设置页和 Android 自动化代码。

改了哪些文件

client/src/admin_gateway.py：增加任务领取窄接口。
client/src/http_admin_gateway.py：实现 HTTP claim、204 和真实字段映射。
client/src/pdd_ui_event.py：增加领取 Worker、单次领取接线、保存和状态反馈。
client/test/test_http_admin_gateway.py：覆盖真实报文、请求头、204、错误响应和 collect-only 能力。
client/test/test_pdd_ui_event.py：覆盖领取保存、表格刷新、重复任务、保存失败、配置缺失、重复点击和关闭安全。
docs/client/04-admin-api-contract.md：记录 claim 已实现以及领取后本地保存失败缺口。
docs/client/05-ui-specification.md：记录单次领取的过渡交互。

验收结果

验收标准	结果
真实 Admin 报文正确映射到 `AdminTask`	通过
204 返回 `None`，界面显示中性提示	通过
claim 请求头和请求地址正确	通过
只声明 `collect`，不领取采购任务	通过
HTTP 错误保留可读信息和 request_id	通过
点击一次只领取一个任务	通过
HTTP 与 SQLite 写入均在后台 Worker	通过
保存成功后刷新表格	自动测试和真实联调通过
重复任务不作为异常	通过
保存失败提示包含任务编号	通过
窗口关闭后不访问 UI，已领取任务仍落库	通过
按钮保持“获取任务”，不进入持续循环	通过
不调用 uiautomator2、ADB、采购或下单	通过
不修改工单排除的文件	通过
两份长期文档同步	通过

测试

执行命令：

# client 目录
C:/Python310/python.exe -m pytest test -q --tb=short --disable-warnings
C:/Python310/python.exe -m compileall -q src test

# admin 目录
go test ./... -count=1

另外执行了离屏主窗口启动/关闭和任务文件 git diff --check。

结果：Client 全量 130 项测试通过；Admin 全量 Go 测试通过；语法、离屏冒烟和差异检查通过。
真实联调首次点击：任务 COL-ce3fefe75ff3c2b0 从 Admin pending 变为 claimed，分配 Client 与本机已保存编号一致；Client SQLite 保存为 collect/claimed，表格显示 1 行。
真实联调第二次点击：Admin 返回 204，页面显示“暂无可领取的采集任务”，按钮保持“获取任务”。
联调使用独立 18080 临时 Admin 进程，完成后已停止；原 8080 热重载进程未改动。
没验证到的部分：没有验证远程 Admin、认证 Token、真实网络超时、磁盘真的写满、Windows 高对比度和 200% 缩放；没有连接手机，没有执行采集、采购或下单。

已知缺口

Admin 返回任务时已经把它改为 claimed。如果随后本地 SQLite 写入失败，当前版本只能持续显示任务编号并要求人工处理，尚无自动补偿或服务端回收机制。

4.9 KiB Raw Blame History