docs: 归档任务 #37

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)`