diff --git a/docs/task/37-规格面板蛇形逐色采价与尺码采集.md b/docs/task/37-规格面板蛇形逐色采价与尺码采集.md new file mode 100644 index 0000000..7e2bc18 --- /dev/null +++ b/docs/task/37-规格面板蛇形逐色采价与尺码采集.md @@ -0,0 +1,95 @@ +# 37 规格面板蛇形逐色采价与尺码采集 + +- 类型:缺陷 +- 父级大工单:#1 +- 所属 MVP / 版本:#2 / MVP +- 状态:待验收 +- 日期:2026-08-08 +- Gitea 工单:http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/37 + +## 背景与目标 + +#36 已经解决商品页反复滑动、无法进入规格面板的问题,但进入面板后的正式 +采集仍先滑动合并规格文字,再逐个按名称搜索颜色。点击后仅凭颜色文字仍在 +控件树中判断选中,并要求 `selected_text` 同时包含颜色和尺码。真机页面的 +`selected_text` 为空,导致所有颜色价格都被判定无效。 + +本任务按已确认业务规则改为:不同颜色可能价格不同,需要逐个颜色采价;尺码 +不影响价格,只收集文字和当前可用状态,不逐个选择尺码。 + +## 最终方案 + +- 进入规格面板后先把颜色横向列表归位到左端。 +- 按完整可见颜色节点的中心 y 坐标动态聚类行,第一行从左到右、下一行从右到 + 左交替遍历。 +- 按颜色名称去重;每次只处理一个颜色,点击后丢弃旧坐标并重新获取控件树。 +- 选择确认优先使用 `selected`、`checked` 或“已选”摘要。页面完全不暴露选择 + 状态时,才使用完整可见、启用、可点击节点未报错的点击作为降级证据。 +- 价格连续读取两次稳定后才记录。同价颜色仍分别点击和保存。 +- 左右边缘需要连续两次没有新颜色且视口不变才确认,并保留滑动次数和总超时 + 上限。 +- 操作顺序采用蛇形以减少往返滑动,最终颜色维度恢复成页面逐行从左到右的 + 自然顺序,便于 Admin 稳定显示。 +- 所有颜色完成后才向下滚动外层面板;尺码只读取、去重,不点击、不采价。 +- `price_granularity` 保持 `color`。颜色与尺码展示组合复用颜色价格, + `price_observed_at` 只记录真实选中的颜色,不虚构尺码。 +- 完整结果继续由现有 Repository 在一个事务中写入 SQLite 和 Outbox,之后才 + 调用 Admin;没有新增数据库迁移或接口。 + +## 修改文件 + +- `client/src/pdd_collect_service.py`:实现蛇形逐色采价、选择确认、价格稳定等待、 + 尺码只读和颜色价格组合组装。 +- `client/test/test_pdd_collect_service.py`:增加两行两视口、同价颜色、空 + `selected_text`、点击未生效和尺码只读测试。 +- `client/test/test_pdd_real_xml_fixtures.py`:验证真实规格 XML 的两行颜色和半露 + 节点过滤。 +- `docs/client/01-requirements.md`:明确当前业务按颜色采价、尺码只读。 +- `docs/client/02-architecture.md`:记录规格面板蛇形采集状态顺序。 +- `docs/client/03-data-model.md`:明确颜色粒度的 `price_observed_at` 和可用状态 + 边界。 +- `docs/client/04-admin-api-contract.md`:明确按颜色采价时不得虚构尺码。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 动态识别颜色行并按蛇形顺序点击 | 通过,假设备顺序为 A、B、C、F、E、D | +| 每个可用颜色只采价一次,相邻视口不重复 | 通过 | +| 每次点击后使用最新 XML | 通过 | +| `selected_text` 为空时按明确降级规则采价 | 通过 | +| 页面暴露选择状态时不把无效点击当成功 | 通过 | +| 相邻颜色同价时仍分别保存 | 通过,A/B 均为 1000 分 | +| 颜色完成后才读取尺码,尺码不点击 | 通过,测试读取 M/L | +| `price_observed_at` 不虚构尺码 | 通过,只包含 `color` | +| 完整结果先保存 SQLite/Outbox 再提交 Admin | 通过,现有链路回归测试通过 | +| 真机完成逐色采价和尺码采集 | 未验证,三星系统安全提示阻塞 | +| 不加购、不下单、不付款 | 通过 | + +## 测试 + +从 `client/` 目录执行: + +```powershell +C:/Python310/python.exe -m py_compile src/pdd_collect_service.py test/test_pdd_collect_service.py test/test_pdd_real_xml_fixtures.py +C:/Python310/python.exe -m unittest discover -s test -p 'test_*.py' -q +``` + +- 语法检查通过。 +- Client 全量 156 项测试通过。 +- 真实 `737116531267_size.xml` 能识别两行完整颜色,并过滤右边只露出一部分的 + 节点。 +- 真机设备 `R28M30T2JWE` 启动验证后出现三星“支付安全 / 关闭 USB 调试”系统 + 提示,控件树没有 PDD 规格区域。根据安全红线,没有自动点击“忽略”。 +- **未验证部分**:人工关闭三星安全提示后的完整真机蛇形逐色采价、向下滚动 + 读取尺码以及最终 `pdd_data` 内容;没有向 Admin 提交本次隔离验证结果。 + +## 遗留问题 + +- 真机安全提示必须由用户手动处理后复验,Client 不得自动绕过。 +- 当前业务只验证颜色价格,不逐个验证颜色与尺码组合的实时库存。如果以后需要 + 组合库存或尺码价格,应另建工单并改用 `price_granularity=sku`。 + +## 相关提交 + +- `9562da9` `fix: 蛇形遍历颜色并逐色采价 (#37)`