diff --git a/docs/task/162-规格面板临时空控件树稳定读取.md b/docs/task/162-规格面板临时空控件树稳定读取.md new file mode 100644 index 0000000..ae4893b --- /dev/null +++ b/docs/task/162-规格面板临时空控件树稳定读取.md @@ -0,0 +1,61 @@ +# #162 Client:规格面板临时空控件树稳定读取 + +- 工单号:#162 +- 类型:缺陷 +- 父级:Epic #1、MVP #2 +- 版本:Client 可运行任务闭环 +- 状态:待验收 +- 日期:2026-08-11 +- Gitea: + +## 背景与目标 + +Client 采集商品 `339317949086` 时已经进入规格面板,但随后读取到 PDD 渲染 +期间的临时空控件树,错误报告为“规格面板没有可识别的规格区域”。失败树中 +PDD 只有空容器,不是真实的新规格结构。 + +目标是在规格操作期间跳过短暂空树,恢复前不继续使用旧坐标;持续无法恢复时 +安全停止并保存可以对照的诊断证据。 + +## 最终方案 + +1. 增加统一的有效规格面板读取方法,单次操作后最多等待 2 秒、最多读取 20 次。 +2. 仅把 `PDD_DATA_SPEC_INCOMPLETE` 当作可能的瞬态空树重试;验证码、登录和 + 售罄等明确页面仍立即停止。 +3. 默认尺码检查、面板回顶、颜色定位和点击、水平滑动及最终尺码采集都先取得 + 最新有效面板,再解析节点和坐标。 +4. 颜色点击后仍优先识别大图页;返回一次后也通过统一方法确认面板恢复。 +5. 记录最后有效规格树与最后异常树。持续空树返回 + `PDD_PAGE_SPEC_PANEL_LOST`,并同时保存两份证据。 + +最终实现与建单方案一致,没有修改颜色、尺码、价格、数据库或 Admin 接口规则。 + +## 改了哪些文件 + +- `client/src/pdd_collect_service.py`:增加稳定读取、规格阶段接入和双份诊断证据。 +- `client/test/test_pdd_collect_service.py`:增加交替空树、持续空树和特殊页测试。 + +## 验收结果 + +- [x] 有效规格面板后出现临时空树时能等待并继续采集。 +- [x] 默认尺码、颜色点击、水平/纵向滑动和尺码采集不直接解析空树。 +- [x] 恢复后重新从最新有效树计算坐标。 +- [x] 持续空树在有限时间内返回 `PDD_PAGE_SPEC_PANEL_LOST`。 +- [x] 失败诊断包含最后有效规格树和最后异常树。 +- [x] 验证码等明确特殊页面不会被瞬态重试吞掉。 +- [x] 精确测试、Client 全量测试和语法检查通过。 +- [ ] 用户使用真机重新采集商品 `339317949086` 验收。 + +## 测试 + +在 `client/` 目录执行: + +```powershell +C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_collect_service.py" +C:/Python310/python.exe -m unittest discover -s test -p "test_*.py" +C:/Python310/python.exe -m py_compile src/pdd_collect_service.py test/test_pdd_collect_service.py +``` + +结果:采集服务 53 项通过,Client 完整 410 项通过,语法检查通过。 + +未验证到的部分:未使用真机重新采集;未执行采购、下单或付款。