cmautobuy/docs/task/159-修复售罄页误识别规格面板.md

# #159 Client：修复售罄推荐页误识别为规格面板

- 工单号：#159
- 类型：缺陷
- 父级：Epic #1、MVP #2
- 版本：Client 可运行任务闭环
- 状态：已完成，用户验收通过
- 日期：2026-08-11
- Gitea：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/159>

## 背景与目标

Client 采集商品 `757123298435` 时，点击购买入口后 PDD 显示“商品已售罄，
推荐以下相似商品”。旧代码把推荐商品列表解析成颜色，随后在空白过渡页面报
“规格面板没有可识别的规格区域”。

目标是准确报告商品不可用，并保证推荐商品不会被解析或点击。

## 最终方案

1. 增加页面级售罄短语检测。命中后返回现有错误码
   `PDD_GOODS_UNAVAILABLE`，诊断原因记录为 `out_of_stock`。
2. 规格面板等待必须确认可靠面板证据，解析出任意规格维度不再单独作为成功
   条件。
3. 可滚动面板通过“已选/请选择摘要”“提交选择提示”或“滚动容器内的真实规格
   标题”确认，继续兼容旧版滚动面板。
4. 没有对应规格标题的嵌套 `RecyclerView` 不再默认命名为“颜色分类”，避免把
   推荐商品卡片当成颜色。
5. 新增脱敏售罄推荐页固件，同时验证空白 PDD 树不会被识别为规格面板。

最终实现与建单方案一致，没有修改 Admin 接口、数据库、`pdd_data` 或颜色价格
业务规则。

## 改了哪些文件

- `client/src/pdd_collect_service.py`：增加售罄检测并收紧规格面板识别。
- `client/test/test_pdd_collect_service.py`：增加售罄、推荐卡片和空白树测试。
- `client/test/fixtures/pdd_sold_out_recommendations.xml`：脱敏售罄页固件。

## 验收结果

- [x] 本次真实售罄 XML 返回 `PDD_GOODS_UNAVAILABLE`。
- [x] 推荐商品没有被解析成颜色，也不会被点击。
- [x] 空白过渡树不会被当成规格面板。
- [x] 规格等待不再仅凭任意 `dimensions` 判定成功。
- [x] 旧版可滚动和新版非滚动规格面板测试继续通过。
- [x] 采集服务精确测试、Client 完整测试和语法检查通过。
- [ ] 用户使用真机重新采集商品 `757123298435` 验收。

## 测试

在 `client/` 目录执行：

```powershell
C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_collect_service.py"
C:/Python310/python.exe -m unittest discover -s test -p "test_*.py"
C:/Python310/python.exe -m py_compile src/pdd_collect_service.py test/test_pdd_collect_service.py
```

结果：采集服务45项通过，Client完整402项通过，语法检查通过。本次真实售罄
XML 只读复验返回 `PDD_GOODS_UNAVAILABLE` 和 `page_reason=out_of_stock`。

未验证到的部分：未使用真机重新采集；未执行采购、下单或付款。