feat: 完善真实采购订单核对与恢复 (#100)

2026-08-10 16:54:06 +08:00
parent 16107aaa18
commit df67b0eaaa
16 changed files with 1134 additions and 103 deletions
@@ -371,7 +371,9 @@ Admin 侧必须无条件接受，见 [04](04-admin-api-contract.md) §6.1。
  `claimed`；恢复执行必须创建新的 `attempt_id`，不会存在两条并发运行。
 - `irreversible_action_at` 有值时，启动恢复立即转为 `manual_review / reconcile_purchase`。
  `PurchaseReconcileService` 只能调用独立的只读 Adapter，不会调用采购 Adapter。
- 核对到唯一候选也仍需人工最终确认；未找到、多候选或结果不确定均保持人工处理。
+- 核单按商品编号、完整规格、数量、确认总价、提交时间范围和未付款状态严格匹配。
+  只有唯一候选会原子写入采购结果与 Outbox；未找到、多候选、字段不符、非未付款
+  或结果不确定均保持人工处理。
 - Admin 提交失败只重试 Outbox，不再次操作拼多多。

 ## 9. PDD 适配边界
@@ -392,9 +394,14 @@ reconcile_purchase(task, run) -> PurchaseResult | ManualReview
 `irreversible_action_at` 事务，再允许 Adapter 点击一次；之后无论点击结果是否明确，
 都只进入订单核对。该接口不提供付款或取消订单方法。
 采购规格使用完整 `options` 对象精确比较，不假定只有颜色和尺码两个维度。
-只读核对另用 `PddPurchaseReconcileAdapter`，只暴露 `read_order_match`
+只读核对另用 `PddPurchaseReconcileAdapter`，只暴露 `read_order_candidates`
 和 `close`，不暴露选规格、设数量、下单或付款方法。

+正式只读核单由 `pdd_u2_purchase_reconcile_adapter.py` 实现，只允许使用白名单
+导航进入个人中心、我的订单和待付款列表，以及返回和滚动。它只提取核单所需的
+订单编号、商品编号、规格、数量、总价、下单时间和付款状态，不保存收货人、地址
+或电话。最终匹配由领域服务完成，不能让页面解析层单独决定采购成功。
+
 正式 Client 由 `pdd_u2_purchase_adapter.py` 分别实现演练和 live 接口，并在
 `ui_main.py` 注入工厂。Adapter 通过 `PddDeviceService` 独占连接，每次判断
 都重新读取当前包名和控件树。当前 Admin 下发的 `color` 和 `size`
@@ -444,6 +444,7 @@ CREATE TABLE app_settings (
 | `running` | `cancelled` | 用户停止，且已到安全点、未进入不可逆阶段 | 任务协调器 |
 | `result_pending` 结果待提交 | `succeeded` | Admin 返回 `accepted: true` | 结果提交服务 |
 | `result_pending` | `manual_review` | 重试次数超上限仍提交不上去 | 结果提交服务 |
+| `manual_review / reconcile_purchase` | `result_pending` | 严格核对到唯一未付款订单，结果和 Outbox 已在同一事务落库 | 只读核单服务 |
 | `retry_wait` 重试等待 | `running` | 重新启动获取任务，或用户确认“重新执行”；**本地直接重跑**并新建 `task_runs` 记录 | 任务协调器 / 人 |
 | `retry_wait` | `failed` | 超过最大重试次数，且从未进入不可逆阶段 | 任务协调器 |
 | `retry_wait` | `manual_review` | 超过最大重试次数，但**曾经进入过不可逆阶段** | 任务协调器 |
@@ -588,6 +589,7 @@ CREATE TABLE app_settings (
    "confirmation_reached": true,
    "order_submitted": false,
    "payment_attempted": false,
+    "payment_status": null,
    "order_no": null,
    "ordered_at": null,
    "ordered_at_raw": null,
@@ -601,7 +603,10 @@ CREATE TABLE app_settings (
 `order_submitted=false`、`payment_attempted=false` 和
 `match_status=not_submitted`；只表示已经安全到达最终提交前确认页。

-真实下单后 `mode` 为 `live`，`match_status` 只能是 `matched`、`ambiguous` 或 `not_found`。只有 `matched` 可以自动报告采购成功。
+真实下单成功核对后 `mode` 为 `live`、`payment_status` 为 `unpaid`、
+`match_status` 为 `matched`。只有商品编号、完整规格、数量、总价、时间范围和未付款
+状态全部一致，且候选唯一时才生成采购结果。无候选、多候选、字段不符或非未付款
+订单只保存脱敏诊断并进入人工处理，不生成成功 `pdd_data`。

 ## 9. JSON 兼容规则

@@ -314,7 +314,11 @@ Idempotency-Key: task-id:attempt-id:result-v1
 }
 ```

-采购结果把 `result_type` 换成 `purchase`，其余结构相同。
+采购结果把 `result_type` 换成 `purchase`，并按 [03 数据模型 §8.2](03-data-model.md)
+携带 `purchase`。真实采购成功必须同时满足 `mode=live`、
+`order_submitted=true`、`payment_attempted=false`、`payment_status=unpaid`、
+`match_status=matched`，并包含非空订单编号和带时区下单时间。0 个或多个候选、
+字段不符及非未付款订单改走 §7 人工处理，不得提交采购成功结果。

 响应：

@@ -222,6 +222,8 @@ class TaskTableModel(QAbstractTableModel):
 详情面向采购人员，任务类型、状态、当前步骤和错误说明优先使用中文。数据库中的 `current_step` 等内部值只用于业务判断和日志，不直接显示；遇到尚未适配的新步骤时显示“未知步骤”。
 采购演练和恢复至少要明确显示“演练已在提交前停止”、“结果待提交”、
 “只允许核对订单”和“需要人工处理”；不能只用颜色表达安全状态。
+真实提交后的详情还要区分“订单已提交，只允许核对未付款订单”、
+“已提交待付款，等待向 Admin 上报”和“订单结果不确定或存在多个候选”。

 采集规格按下面顺序展示：

@@ -92,6 +92,8 @@ PDD 解析测试优先使用脱敏的 XML 固件，不要求每次连接真实
 - 关键手机动作前已持久化 `current_step`。
 - 无不可逆标记的中断会先关闭旧运行，新运行使用新 `attempt_id`。
 - 有不可逆标记的中断只调用只读核对，采购 Adapter 调用次数为 0。
+- 只读核单按商品、完整规格、数量、总价、时间和未付款状态全部精确匹配；只有唯一候选生成成功 Outbox。
+- 无候选、多候选、字段缺失或不符、非未付款状态只转人工，不产生采购成功结果。
 - 已落库 Outbox 只补交，不重跑手机流程。
 - 停止、设备断开、验证码、登录失效和结果不确定都保留稳定错误和诊断。
 - `execution_mode=live` 只允许采购任务，且 Client 不得自行升级 Admin 下发的模式。