docs: 归档任务 #122

docs/task/122-只读核单多视口证据合并.md

@@ -0,0 +1,64 @@
+# 122 修复只读核单前台误判并合并订单详情多视口字段
+
+- 类型：缺陷
+- 父级大工单：#1
+- 所属 MVP / 版本：MVP 后续真实采购核单
+- 状态：已完成，待用户验收
+- 日期：2026-08-10
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/122>
+
+## 背景与目标
+
+真实采购进入待付款订单详情后，部分设备会让 `app_current()` 错误返回
+系统设置包名。同时，商品、规格、数量和金额位于订单详情上半屏，订单号和
+下单时间位于下半屏。旧代码因此会中断核单，或只得到字段不完整的候选。
+
+本任务让核单优先使用可靠控件树判断 PDD 前台，并在确认页面只有一个订单
+上下文时合并相邻视口证据。最终候选仍必须通过原有严格匹配。
+
+## 最终方案
+
+- 控件树内至少有 3 个 PDD 包节点时，直接认定 PDD 在前台；证据不足时才调用
+  `app_current()` 兜底。
+- 页面只有一组“去支付”操作且至多一个订单号时，才允许累积订单详情字段。
+- 每次向下滚动后合并商品编号、规格、数量、金额、订单号、下单时间和付款状态。
+- 订单号或其他关键字段冲突时立即放弃跨视口合并，保留原有人工核对结果。
+- 不改变最终严格匹配，不点击支付或取消订单，也不提供重新下单入口。
+
+原工单给出的定向测试命令把 `client/test` 当作 Python 包，但该目录没有
+`__init__.py`。实际验证改用 `unittest discover`，测试范围不变。
+
+## 改了哪些
+
+- `client/src/pdd_u2_purchase_reconcile_adapter.py`：增加控件树前台判断、单订单
+  详情识别、部分证据解析和无冲突合并。
+- `client/test/test_pdd_u2_purchase_reconcile_adapter.py`：增加多视口合并、错误
+  前台结果和多订单防误合并测试。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 可靠 PDD 控件树不受错误 `app_current()` 影响 | 通过 |
+| 同一订单上下屏字段能合并为完整候选 | 通过 |
+| 合并结果继续执行现有严格匹配 | 通过 |
+| 多订单或关键字段冲突时不跨订单合并 | 通过 |
+| 不包含支付、取消订单或再次下单操作 | 通过 |
+| Client 自动化测试通过 | 通过，349 项 |
+
+## 测试
+
+- 执行的命令：
+  - `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 -p test_purchase_recovery.py -v`
+  - `C:/Python310/python.exe -m unittest discover -s test -v`
+  - `git diff --check`
+- 结果：定向测试分别通过 6 项和 8 项；完整 Client 测试 349 项全部通过；
+  差异检查通过。
+- **没验证到的部分**：没有用真实 Android 设备重新执行自动核单。当前旧任务已经
+  进入 `reconcile_manual_review`，按安全状态机不会因本次升级自动重试；未修改其
+  数据库状态，也未点击支付、取消订单或再次下单。
+
+## 相关提交
+
+- `a8f8e73` fix: 合并只读核单多视口证据 (#122)