From a2fc1501c4d94d58ccf637c829400ac0bbb28cc2 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Fri, 7 Aug 2026 16:43:49 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?=
 =?UTF-8?q?#30?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../30-client-领取-admin-创建的采集任务.md    | 90 +++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 docs/task/30-client-领取-admin-创建的采集任务.md

diff --git a/docs/task/30-client-领取-admin-创建的采集任务.md b/docs/task/30-client-领取-admin-创建的采集任务.md
new file mode 100644
index 0000000..8d0b160
--- /dev/null
+++ b/docs/task/30-client-领取-admin-创建的采集任务.md
@@ -0,0 +1,90 @@
+# 30 Client 领取 Admin 创建的采集任务
+
+- 类型：需求（跨模块联调）
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 / MVP
+- 状态：待验收
+- 日期：2026-08-07
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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、采购或下单 | 通过 |
+| 不修改工单排除的文件 | 通过 |
+| 两份长期文档同步 | 通过 |
+
+## 测试
+
+执行命令：
+
+```powershell
+# 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 写入失败，当前版本只能持续显示任务编号并要求人工处理，尚无自动补偿或服务端回收机制。
+
+## 相关提交
+
+- `51062f4` `feat: 领取 Admin 采集任务并保存本地 (#30)`
+