docs: 归档任务 #166

docs/task/166-兼容款式与套餐规格.md

@@ -0,0 +1,73 @@
+# #166 Client：兼容款式与套餐规格分组
+
+- 工单号：#166
+- 类型：缺陷
+- 父级：Epic #1、MVP #2
+- 版本：Client 可运行任务闭环
+- 状态：待验收
+- 日期：2026-08-11
+- Gitea：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/166>
+
+## 背景与目标
+
+商品 `757123298435` 的规格面板使用“款式”和“套餐”两个分组。原解析器不认识
+“套餐”标题，把套餐按钮继续归入前面的款式区域，最终将套餐组合错误写入
+`color`。本任务让 Client 正确拆分并保存这两个规格。
+
+## 最终方案
+
+- 规格解析器增加“花色”和“套餐”标题别名。“款式/花色/颜色”映射为主规格
+  `color`；前面已有主规格时，“套餐”映射为第二规格 `size`。
+- 只有“套餐”一个分组时，将其作为主规格 `color`，保证现有逐主规格采价流程仍
+  能工作；额外第三维度生成独立 key，并由采集流程明确拒绝，不静默合并。
+- 最终 dimensions 保留页面原始名称“款式”“套餐”，SKU 仍使用稳定的
+  `color` / `size` 字段。
+- 默认选中的套餐沿用第二规格安全取消流程，取消后回到顶部采集所有款式。
+- 采购确认面板和规格选择区域同步识别“款式/套餐”。只有套餐时选择区域可以用
+  套餐标题兜底；款式和套餐同时存在时始终优先款式。
+- 保持原价格规则不变：只逐个主规格采价，不采集款式与套餐的组合价格。
+
+## 改了哪些文件
+
+- `client/src/pdd_collect_service.py`：增加套餐分组、上下文 key 映射及原始分组名称
+  保留。
+- `client/src/pdd_u2_purchase_adapter.py`：采购面板证据词兼容款式和套餐。
+- `client/src/util/select_color_size.py`：套餐作为单规格时可作为主规格区域兜底。
+- `client/test/test_pdd_collect_service.py`：增加款式套餐、单独套餐、默认套餐取消、
+  三维规格拒绝和完整采集测试。
+- `client/test/test_pdd_u2_purchase_adapter.py`：增加采购面板识别回归测试。
+
+## 验收结果
+
+- [x] 款式选项只进入 `color`，套餐文字不再混入颜色。
+- [x] 套餐选项进入 `size`，并保留原始分组名称。
+- [x] 默认选中的套餐可以安全取消，再采集全部款式。
+- [x] 只有套餐一个维度的商品仍能作为主规格采集。
+- [x] 不支持的额外维度不会被静默合并。
+- [x] 采购面板能识别“款式/套餐”，现有颜色尺码测试没有回归。
+- [x] 没有修改数据库、Admin 接口及价格粒度。
+- [x] 精确测试、Client 全量测试和语法检查通过。
+- [ ] 用户使用真机商品 `757123298435` 确认最终款式和套餐数据。
+
+## 测试
+
+在 `client/` 目录执行：
+
+```powershell
+$env:QT_QPA_PLATFORM="offscreen"
+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_pdd_u2_purchase_adapter.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 src/pdd_u2_purchase_adapter.py src/util/select_color_size.py test/test_pdd_collect_service.py test/test_pdd_u2_purchase_adapter.py
+Remove-Item Env:QT_QPA_PLATFORM
+```
+
+结果：采集服务 58 项、采购适配器 26 项、Client 完整 420 项测试通过，语法检查
+通过。
+
+**没验证到的部分**：未使用真机重新采集商品 `757123298435`；未执行真实采购、
+下单或付款；套餐价格仍按已确认规则不单独采集。
+
+## 相关提交
+
+- `9c7e715` 兼容款式与套餐规格分组。