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