# 230 Client：采购规格面板选择颜色前先归位到顶部

- 类型：缺陷
- 父级大工单：#1
- 所属 MVP / 版本：#2
- 状态：已完成，待用户验收
- 日期：2026-08-14
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/230

## 背景与目标

PDD 可能保留采购规格面板上一次的纵向位置。cg31 的现场页面已经显示尺码区域，但正式颜色标题滑出可视区域。原采购流程直接执行颜色横向扫描，没有先恢复颜色区域，可能找不到目标颜色。

## 最终方案

- 只在采购选择颜色前检查规格面板纵向位置，不修改采集流程。
- 正式颜色标题与至少一个可点击选项同时出现时，直接继续原颜色选择，不执行纵向滑动。
- 当“颜色选择摘要存在、正式颜色标题缺失、第二规格标题已经出现”三项强证据同时成立时，判定面板停在中部。
- 在唯一可靠的 PDD 纵向滚动容器内用手指向下滑，让规格内容返回顶部；每次滑动后重新读取控件树。
- 正式颜色区域出现后立即停止；连续两次结构签名不变或达到八次上限时安全失败。
- “请选择”“已选”“选择颜色后提交”等摘要不作为正式颜色标题。
- 无标题、无滚动属性但原选择器能够处理的历史面板继续走原逻辑，避免影响图片颜色和非滚动规格面板。
- 无法可靠归位时返回 `PURCHASE_PANEL_COLOR_REGION_NOT_FOUND`，不进入地址、提交或不可逆阶段。

## 改了哪些

- `client/src/pdd_u2_purchase_adapter.py`：增加采购专用颜色区域识别、纵向容器定位、有界归位和明确失败诊断。
- `client/test/test_pdd_u2_purchase_adapter.py`：增加脱敏中部面板及 Fake Device，覆盖归位、无需归位和无法归位。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 已在颜色区域时不纵向滑动 | 通过 |
| 初始位于尺码区域时先回到颜色顶部 | 通过 |
| 选择摘要不作为正式颜色标题 | 通过 |
| 归位后复用原颜色和尺码选择 | 通过 |
| 连续结构不变时有界停止 | 通过 |
| 无法归位时明确失败且不继续采购 | 通过 |
| 历史非滚动、图片颜色、地址和提交门禁不受影响 | 通过 |
| 采购专项及 Client 回归 | 专项通过；全量存在 2 项无关既有失败 |

## 测试

- 执行的命令：
  - `C:/Python310/python.exe -m py_compile src/pdd_u2_purchase_adapter.py`
  - `C:/Python310/python.exe -m pytest test/test_pdd_u2_purchase_adapter.py -q --disable-warnings`
  - `C:/Python310/python.exe -m pytest test -q --disable-warnings`
  - `git diff --check -- client/src/pdd_u2_purchase_adapter.py client/test/test_pdd_u2_purchase_adapter.py`
- 结果：语法和差异检查通过；采购 Adapter 专项 51 项全部通过；Client 全量 473 项中 471 项通过。
- **没验证到的部分**：没有对 cg31 或其他真机任务执行归位滑动、颜色选择、地址修改或真实采购。全量测试另有 2 项既有失败，原因是当前版本为 `0.1.2`，旧更新测试仍固定期待 `0.1.0`，与 #230 无关。

## 相关提交

- `fee4028` fix: 采购选色前归位规格面板 (#230)