docs: 归档任务 #191

docs/task/191-稳定地址表单后单次点击保存.md

@@ -0,0 +1,74 @@
+# 191 稳定地址表单后单次点击保存
+
+- 类型：缺陷
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 Client 可运行任务闭环
+- 状态：已完成，待用户验收
+- 日期：2026-08-12
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/191>
+
+## 背景与目标
+
+正式采购任务 cg16 修改详细地址后点击保存，但页面一直停留在地址编辑页，最终报告
+地址页面切换超时。原流程在地址回读一次后立即点击保存，表单或保存目标可能仍在
+变化。目标是在可逆阶段等待地址表单稳定，同时保持保存按钮只点击一次。
+
+## 最终方案
+
+- 地址输入后循环读取最新控件树，只有目标地址完全一致、页面仍是编辑页、保存按钮
+  唯一且坐标连续两次相同，才进入保存准备状态。
+- 达到稳定条件后等待 0.3 秒，再读取最新控件树复核相同条件；复核失败就重新等待，
+  不使用旧坐标。
+- 保存按钮仍只点击一次；点击后的最长约 10 秒、每 0.2 秒读取一次的原有页面轮询
+  保持不变。
+- 保存前页面持续不稳定时不点击，返回 `PURCHASE_ADDRESS_SAVE_NOT_READY`；地址值始终
+  回读不一致时保留 `PURCHASE_ADDRESS_INPUT_MISMATCH`。
+- 单次保存后始终停留编辑页时返回 `PURCHASE_ADDRESS_SAVE_NOT_EFFECTIVE`，其他页面
+  仍返回原地址页面超时错误。
+- 诊断只记录页面类型、地址是否匹配、候选数量和稳定次数，不记录地址原文。
+
+最终实现与建单方案一致，并保留了原地址回读不一致错误码，避免改变既有错误语义。
+
+## 改了哪些
+
+- `client/src/pdd_u2_purchase_adapter.py`：增加保存前稳定状态机和保存未生效错误分类。
+- `client/test/test_pdd_u2_purchase_adapter.py`：增加地址异步刷新、保存坐标变化、持续不
+  稳定、保存点击丢失以及单次点击保护测试。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 地址、编辑页和保存目标连续两次稳定 | 通过 |
+| 短暂等待后使用最新控件树再次复核 | 通过 |
+| 保存按钮始终只点击一次 | 通过 |
+| 保存前不稳定时不点击并安全失败 | 通过 |
+| 保存后继续使用原有有界轮询 | 通过 |
+| 始终停留编辑页时返回保存未生效错误 | 通过 |
+| 诊断不包含姓名、手机号或地址原文 | 通过 |
+| 地址后缀、浮层、返回和下单门禁不变 | 通过 |
+| 采购 Adapter 专项测试通过 | 通过 |
+| Client 全量测试全部通过 | 未通过：470 项中 2 项为既有版本号断言失败，与本工单无关 |
+
+## 测试
+
+- 执行的命令：
+
+```powershell
+C:/Python310/python.exe -m py_compile src/pdd_u2_purchase_adapter.py test/test_pdd_u2_purchase_adapter.py
+C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_u2_purchase_adapter.py"
+$env:QT_QPA_PLATFORM="offscreen"
+C:/Python310/python.exe -m unittest discover -s test -p "test_*.py"
+Remove-Item Env:QT_QPA_PLATFORM
+git diff --check
+```
+
+- 结果：采购 Adapter 48 项全部通过，语法检查和差异检查通过。Client 全量运行 470
+  项，468 项通过；2 项失败是工作区已有 `src/version.py` 为 `0.1.2`，而两个旧更新
+  测试固定期待 `0.1.0`，本工单未修改该用户改动。
+- **没验证到的部分**：未连接真机执行新的正式采购任务；PDD 地址表单真实异步时间、
+  单次保存是否返回地址面板，以及后续提交和核单闭环需要用户真机验收。
+
+## 相关提交
+
+- `27a0e8c` fix: 稳定地址表单后单次保存 (#191)