diff --git a/docs/task/173-正式采购下单前更新地址标记.md b/docs/task/173-正式采购下单前更新地址标记.md new file mode 100644 index 0000000..a14313b --- /dev/null +++ b/docs/task/173-正式采购下单前更新地址标记.md @@ -0,0 +1,74 @@ +# #173 Client:正式采购下单前更新地址采购编号标记 + +- 工单号:#173 +- 类型:需求 +- 父级:#1 / #2 +- 版本:Client 可运行任务闭环 +- 状态:待验收 +- 日期:2026-08-12 +- Gitea: + +## 背景与目标 + +正式采购完成规格和数量选择后,需要在不可逆下单前进入 PDD 收货地址页面, +把程序生成的旧地址末尾标记替换为本次采购编号。采购编号继续使用任务现有的 +`remote_task_id`,Admin 接口和字段不变。 + +本功能只用于正式采购;采集任务和演练兼容路径不修改地址。个人信息和原始 +无障碍 XML 不进入代码、Git、日志、工单、测试或文档。 + +## 最终方案 + +1. `PddLivePurchaseAdapter` 增加下单前地址更新接口,普通演练接口不包含该操作。 +2. 服务层在规格、数量和价格验证通过后,将 `remote_task_id` 传给 live Adapter。 +3. Adapter 使用最新控件树依次确认唯一地址入口、修改按钮、详细地址输入框、 + 保存按钮和返回按钮。 +4. 只替换程序格式明确的末尾标记,保留地址主体,并生成 + `地址主体_采购编号`;地址中间合法的连字符不会被截断。 +5. 保存后回读确认新标记,再返回规格面板。服务层重新复核规格、数量、价格、 + 库存和唯一提交按钮,之后才允许写入不可逆标记并单击一次下单。 +6. 任一步不唯一、页面超时、输入或回读不一致时,保存明确采购失败;此时没有 + 不可逆标记,也不会下单。 + +与建单方案一致。实现时根据真实 XML 只读结构检查补充了兼容处理:返回按钮的 +图标文字和 `content-desc` 分开匹配,避免合并文本后无法识别。 + +## 改了哪些文件 + +- `client/src/pdd_purchase_adapter.py`:增加 live 地址更新边界。 +- `client/src/pdd_u2_purchase_adapter.py`:实现地址定位、后缀替换、保存回读和返回。 +- `client/src/purchase_task_service.py`:把地址步骤接入正式采购且保持在不可逆之前。 +- `client/test/test_pdd_u2_purchase_adapter.py`:增加脱敏 Fake 页面和地址流程测试。 +- `client/test/test_purchase_task_service.py`:验证 live 调用及失败不进入不可逆阶段。 +- `client/test/test_task_dispatcher.py`:更新 live 测试 Adapter 契约。 +- `docs/client/01-requirements.md`:补充正式采购地址步骤和隐私边界。 +- `docs/client/02-architecture.md`:补充 Adapter 边界与安全顺序。 + +实现提交:`c719fd3`。 + +## 验收结果 + +- [x] 只有正式采购执行地址更新,演练和采集不执行。 +- [x] 使用现有 `remote_task_id` 生成末尾 `_采购编号`。 +- [x] 旧程序标记可安全替换,地址主体保持不变。 +- [x] 地址入口、修改、保存和回读失败时在不可逆阶段前停止且不下单。 +- [x] 返回规格面板后继续原有最终复核、不可逆标记和单次提交门禁。 +- [x] Git、日志、工单和测试不包含真实个人信息或原始 XML。 +- [x] 精确测试、Client 全量测试和语法检查通过。 + +## 测试 + +从 `client/` 执行: + +```powershell +C:/Python310/python.exe -m py_compile src/pdd_purchase_adapter.py src/pdd_u2_purchase_adapter.py src/purchase_task_service.py +C:/Python310/python.exe -m unittest discover -s test -p "test_*.py" +``` + +结果:语法检查通过;全量 432 项测试通过。 + +另对用户提供的四份本地 XML 做只读、脱敏结构检查,地址入口、修改按钮、详细地址 +输入框、保存按钮和返回按钮均得到唯一候选。原始 XML 未暂存、未提交。 + +**未验证到的部分:**没有连接真机执行地址修改,没有执行真实下单或付款;PDD 保存后 +页面跳转、输入长度限制和不同 App 版本的实际表现需由用户真机验收。