# 264 兼容纵向颜色规格列表并安全选择目标

- 类型：缺陷
- 父级大工单：#96
- 所属 MVP / 版本：#97 真实采购首单闭环（不支付）
- 状态：已完成
- 日期：2026-08-18
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/264

## 背景与目标

cg52 的 PDD 颜色规格使用单列纵向滚动列表，目标位于首屏以下。原颜色选择器
把可滚动颜色区域统一按横向列表处理，左右滑动无法移动纵向容器，最终误报目标
颜色不存在。本任务让 Client 先判断颜色列表方向，再安全遍历并精确选择目标。

## 最终方案

- 根据同一滚动区域内可点击候选的左上角分布判断单列纵向或单行横向布局。
- 方向证据只读取边界对应滚动容器的后代节点，并要求候选完整落在容器内；
  排除跨越容器的大面积父节点和容器外悬浮控件。
- 颜色标题优先在同一滚动容器内定位，避免商品页背景中的同名文字干扰。
- 多行网格只在容器长宽给出强证据时确定方向；正方形等证据不足的网格不滑动、
  不点击。
- 纵向列表从颜色列表起点向下有界扫描；横向列表继续先归左、再向右扫描。
- 每次滑动后重新读取控件树和页面签名，到达边界后停止。
- 找到目标后继续沿用精确匹配、唯一繁简等价匹配、安全点击范围和选中状态确认，
  不使用近似颜色代替任务规格。
- 不修改任务原始规格、AI 解析、数据库、Admin 接口及任何不可逆下单门禁。

首次实现后，用户真机验收发现方向判断混入了规格容器外的悬浮控件和大面积
clickable 父节点，导致方向返回不明确。修订后把候选和标题证据收窄到同一滚动
容器，真实 cg52 控件树只读判定从 `None` 变为 `vertical`。没有把包含商品原文的
诊断文件提交 Git，自动化测试使用带外部悬浮控件的结构等价脱敏数据。

## 改了哪些

- `client/src/util/select_color_size.py`：增加颜色滚动方向判断、纵向归位和有界扫描。
- `client/test/test_select_color_size.py`：覆盖纵向、横向、网格不确定、网格强方向和
  到达边界仍不存在目标等场景。
- `docs/client/06-quality-security.md`：补充颜色布局方向判断和禁止近似选款的稳定规则。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 单列纵向列表只上下滑动并能选中首屏以下目标 | 通过 |
| 单行横向列表继续只左右滑动 | 通过 |
| 多行网格仅在方向证据明确时扫描 | 通过 |
| 方向不明时不滑动、不点击 | 通过 |
| 到达边界仍不存在目标时不选择近似颜色 | 通过 |
| 现有繁简匹配、重复候选和选中确认安全规则保持 | 通过 |
| cg52 当前控件树能排除外部控件并只读判断为纵向 | 通过 |
| 不改变不可逆标记、提交订单及付款门禁 | 通过 |

## 测试

- 执行的命令：
  - `C:/Python310/python.exe -m py_compile src/util/select_color_size.py test/test_select_color_size.py`
  - `C:/Python310/python.exe -m pytest -q test/test_select_color_size.py test/test_pdd_u2_purchase_adapter.py`
  - `C:/Python310/python.exe -m pytest -q test`
  - 设置 `QT_QPA_PLATFORM=offscreen` 后实例化 `MainWindow`
  - `git diff --check`
- 结果：修订后定向测试 75 项全部通过；离屏界面冒烟输出 `OK`；全量测试 519 项通过、
  2 项失败。两项失败均为工作区既有版本号 `0.1.2` 与测试固定期望 `0.1.0`
  不一致，与本任务无关。
- **没验证到的部分**：没有让真机 cg52 自动点击目标颜色、继续选择尺码或提交订单；
  真机只执行了控件树读取和方向判定，未产生订单。

## 相关提交

- `d69c9cc` 修复颜色布局方向判断和纵向扫描
- `2e40bc6` 收窄方向和标题证据，排除容器外控件污染