feat: 安全领取并分派采购任务 (#72)

2026-08-10 00:05:40 +08:00
parent 460619392f
commit f201bcc4bf
12 changed files with 789 additions and 76 deletions
@@ -89,7 +89,7 @@ client/
 | 目录分层 | domain / application / infrastructure / workers / ui | 平铺在 `src/` 下：`db.py`、`db_schema.py`、`task_repository.py`、`settings_repository.py`、`task_models.py` 等，另有 `src/util/`、`src/demo1/` |
 | 主按钮文案 | 「开始自动获取」⇄「停止自动获取」 | 已按持续串行模式实现 |
 | Admin 网关 | `AdminGateway` + Mock/HTTP 两实现 | 登记、领取、结果和失败提交已实现 |
-| 任务应用服务 | `CollectTaskService` / `PurchaseTaskService` | 采集已接入自动获取；采购已实现本地 `dry_run` 演练，领取与分派由后续工单接入 |
+| 任务应用服务 | `TaskDispatcher` / `CollectTaskService` / `PurchaseTaskService` | 自动获取先补交 Outbox，再按领取时间执行本地任务，最后按安全能力领取并分派新任务 |
 | Outbox 提交 | 从 `outbox_events` 取件重试 | 采集结果与失败已实现，重试不重复采集 |
 | PDD 自动化 | `infrastructure/pdd/` 适配层 | `pdd_device_service.py` 与 `pdd_collect_service.py` 已接入采集主链 |

@@ -330,6 +330,11 @@ Client 与 Admin 的任务交互只有三种调用：领一个任务、提交结
 6. Outbox 提交成功、Admin 返回 `accepted: true` 后标记 `succeeded`。
 7. 回到第 1 步领下一个任务。**同一时间只做一个任务。**

+`TaskDispatcher` 是能力声明的唯一入口。没有可用采购演练 Adapter、没有已保存
+Android 设备或本地持久化未准备好时，只声明 `collect`；条件满足时才声明
+`collect,purchase`，且 `purchase_mode` 永远是 `dry_run`。领取响应必须先完整校验并
+写入 SQLite，Repository 提交成功后才能分派，避免任务已在 Admin 领取却在本地丢失。
+
 中途 Admin 是否取消了这个任务、是否重派给了别人，Client 不查也不管，做完照样提交——
 Admin 侧必须无条件接受，见 [04](04-admin-api-contract.md) §6.1。

@@ -199,10 +199,16 @@ POST /api/v1/client/tasks/claim

 无可领取任务时返回 `204 No Content`。

-Client 的 `HttpAdminGateway.claim_next` 已实现本接口。当前只声明
-`supported_types: ["collect"]`，一次调用最多领取一个采集任务；采集结束后通过
+Client 的 `HttpAdminGateway.claim_next` 已实现本接口，并原样序列化应用层已经
+安全确认的 `ClaimCapabilities`。没有采购演练 Adapter 或设备未准备好时只声明
+`supported_types: ["collect"]`；条件满足时声明 `collect,purchase`，但
+`purchase_mode` 固定为 `dry_run`。一次调用最多领取一个任务，结果或失败通过
 本页 §6 或 §7 提交，完整请求会先进入本地 Outbox。

+采购响应在写入本地前必须校验非空 `goods_url`、`goods_id`、动态 `options`、
+正整数 `quantity` 和正整数分 `max_price_cent`。字段不完整时停止新的领取并向
+操作员显示协议错误；不得让不完整任务进入手机执行。
+
 `[必须]` **`204` 不是错误。** Client 要把它当"暂时没活干"处理，
 不要报错，也不要因此触发重试风暴。首次 claim 通常返回 204；如果该编号已经预先分配任务，也可以直接返回 200。

@@ -64,7 +64,8 @@
 才向 Admin 领取一条。领取、手机采集和提交都在单独的工作线程完成，一轮结束且
 线程完全退出后，由主线程的单次定时器安排下一轮。暂无任务时默认 5 秒后重试；
 可恢复的 Admin 错误按 5、10、20、30 秒退避。需要人工处理、不可恢复错误、设备
-或配置错误会停止自动获取。当前仍不执行采购任务。
+或配置错误会停止自动获取。采购演练执行器和 Android 设备都准备好时，可以领取
+采购任务；界面必须明确显示“演练”，任何路径都不得显示成真实下单。

 ### 4.2 搜索与筛选

@@ -86,6 +87,7 @@
 - 确认后只执行选中的稳定任务编号，不领取新任务，不先处理其他任务或 Outbox。
 - 重新采集在工作线程运行。执行期间禁用“获取任务”和“重新执行”，完成后刷新列表。
 - 每次重新采集创建新的执行记录和幂等键；当前结果更新，旧结果保存在历史执行记录中。
+- 采购任务始终不能通过“重新执行”入口启动；需要处理时由自动获取的安全恢复流程决定。
 - “等待重试”当前没有倒计时。自动获取因可恢复采集错误停止时，底部状态显示
  “重试已暂停”，并提示选择任务点击“重新执行”或重新启动获取任务。