# 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` 安全领取并分派采购任务