docs: 归档任务 #72

docs/task/72-安全领取并分派采购任务.md

@@ -0,0 +1,62 @@
+# 72 安全领取并分派 Admin 采购任务
+
+- 类型：需求
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 Client 可运行任务闭环（MVP）
+- 状态：已完成，待用户验收
+- 日期：2026-08-10
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/72
+
+## 背景与目标
+
+#71 已提供本地采购演练服务，但自动获取仍只会领取采集任务。
+本任务建立统一任务分派器，只在采购演练运行环境已就绪时声明采购
+能力，并保证 Admin 任务先持久化再访问手机。
+
+## 最终方案
+
+- 新增 `TaskDispatcher`，严格按“补交 Outbox → 本地任务 → 领取新任务”串行处理。
+- 能力由分派器统一构造。默认只声明 `collect`；已保存 Android 设备且
+  显式注入采购 Adapter 时才声明 `purchase`，`purchase_mode` 始终为 `dry_run`。
+- HTTP 边界和本地映射双重校验采购任务的 `goods_id`、动态 `options`、
+  `quantity` 和 `max_price_cent`。
+- 领取成功后先写入 SQLite，持久化成功后才根据任务类型分派。
+- 本地已有采购任务但采购演练执行器未就绪时，明确停止领取新任务。
+- 保留“重新执行”只重新采集的原有规则，采购不从该入口启动。
+
+## 改了哪些文件
+
+- `client/src/task_dispatcher.py`：能力构造、领取、落库和按类型分派。
+- `client/src/admin_gateway.py`、`client/src/http_admin_gateway.py`：收紧默认能力并校验采购响应。
+- `client/src/task_repository.py`：按执行能力读取最早本地任务。
+- `client/src/pdd_ui_event.py`：自动获取工作线程改用统一分派器。
+- `client/test/`：增加能力门禁、协议校验、分派和 Qt 工作线程测试。
+- `docs/client/`：同步架构、Admin 契约和界面行为。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 未就绪时只声明采集能力 | 通过 |
+| 就绪时声明采购，且始终是 dry_run | 通过 |
+| 采购安全字段不完整时拒绝执行 | 通过 |
+| Admin 任务先落库再分派 | 通过 |
+| 采集和采购任务按类型交给对应服务 | 通过 |
+| 补交 Outbox 时不重跑手机操作 | 通过 |
+| 采购任务不能通过手动重新执行启动 | 通过 |
+
+## 测试
+
+- 执行的命令：
+  - `C:/Python310/python.exe -m unittest discover -s test`
+  - `C:/Python310/python.exe -m py_compile src/admin_gateway.py src/http_admin_gateway.py src/task_dispatcher.py src/pdd_ui_event.py`
+  - 设置 `QT_QPA_PLATFORM=offscreen` 后创建并关闭 `MainWindow`
+- 结果：Client 全量 200 项测试通过；语法检查通过。离屏主窗口进程在退出 Qt
+  时异常终止，未将该项记为通过。
+- **未验证到的部分**：未连接真实 Admin、Android 设备和 PDD 页面。生产入口目前
+  没有注入具体手机采购 Adapter，所以默认应用仍只声明采集能力；采购路径
+  使用测试 Adapter 验证。
+
+## 相关提交
+
+- `f201bcc` 安全领取并分派采购任务