docs: 归档任务 #126

docs/task/126-简化待付款订单核单条件.md

@@ -0,0 +1,68 @@
+# 126 简化待付款订单核单为编号和时间唯一匹配
+
+- 类型：需求
+- 父级大工单：#1
+- 所属 MVP / 版本：MVP 后续真实采购核单
+- 状态：已完成，待用户验收
+- 日期：2026-08-10
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/126>
+
+## 背景与目标
+
+PDD 待付款订单详情稳定提供订单编号和下单时间，但不提供 `goods_id`，规格、
+数量和金额的无障碍文字格式也不稳定。旧核单要求订单页面重复提供这些字段，导致
+已经找到唯一正确订单仍转人工处理。
+
+本任务按用户确认的业务规则简化核单：订单页面只负责订单编号、下单时间和待付款
+状态；其他采购数据使用任务与下单前确认快照。
+
+## 最终方案
+
+- 核单候选必须有非空订单编号、有效下单时间和 `unpaid` 状态。
+- 下单时间必须位于本地 `order_submitted_at` 前后 5 分钟；点击结果异常而没有保存
+  `order_submitted_at` 时，使用点击前的 `irreversible_action_at` 作保守时间基准。
+- 时间窗口内只有一个符合候选才生成成功结果；多个候选、缺少编号或时间、超出窗口
+  和非待付款状态均转人工处理。
+- `goods_id` 来自任务；确认规格、数量、单价和总价来自下单前持久化的
+  `final_confirmation`，并校验确认规格和数量与任务请求一致。
+- 订单编号和下单时间只来自 PDD 订单页面，不使用任务参数补写。
+- 不改变不可逆安全边界，不支付、不取消订单、不重新下单，也不重置历史人工任务。
+
+## 改了哪些
+
+- `client/src/pdd_purchase_reconcile_adapter.py`：核单查询增加本地下单时间基准。
+- `client/src/purchase_reconcile_service.py`：简化候选匹配条件并区分订单页与确认快照的数据来源。
+- `client/test/test_pdd_u2_purchase_reconcile_adapter.py`：验证最简候选和 5 分钟边界。
+- `client/test/test_purchase_recovery.py`：覆盖唯一候选、多个候选、缺失字段、超时、
+  非待付款及确认快照结果。
+- `docs/client/01-requirements.md`、`02-architecture.md`、`03-data-model.md`、
+  `04-admin-api-contract.md`、`06-quality-security.md`：同步长期核单规则。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 唯一编号、时间和待付款候选在前后 5 分钟内通过 | 通过 |
+| 订单页缺少商品、规格、数量和金额不影响核单 | 通过 |
+| 多候选、缺少编号/时间、超时和非待付款转人工 | 通过 |
+| 商品与确认数据来自任务和下单前快照 | 通过 |
+| 不产生支付、取消订单或重新下单操作 | 通过 |
+| Client 自动化测试通过 | 通过，355 项 |
+
+## 测试
+
+- 执行的命令：
+  - `C:/Python310/python.exe -m py_compile src/pdd_purchase_reconcile_adapter.py src/purchase_reconcile_service.py`
+  - `C:/Python310/python.exe -m unittest discover -s test -p test_purchase_recovery.py -v`
+  - `C:/Python310/python.exe -m unittest discover -s test -p test_pdd_u2_purchase_reconcile_adapter.py -v`
+  - `C:/Python310/python.exe -m unittest discover -s test -v`
+  - `git diff --check`
+- 结果：语法检查通过；定向核单测试共 19 项通过；完整 Client 测试 355 项全部
+  通过；差异检查通过。
+- **没验证到的部分**：没有新建真实订单验证完整自动上报。尝试只读扫描已有人工
+  任务时，手机当前页面没有再次显示订单编号，未得到候选；没有修改任务状态、写入
+  结果、支付、取消订单或重新下单。
+
+## 相关提交
+
+- `399aa0e` fix: 简化待付款订单核单条件 (#126)