cmshoppe/docs/tasks/T-658d.md

---
id: T-658d
title: 商品套图多图参考 GUI 与全流程回归
status: DONE
phase: 7
deps: [T-658a, T-658b, T-658c]
created: 2026-07-17
---

# T-658d 商品套图多图参考 GUI 与全流程回归

## 问题 / 背景

多图参考会改变用户对「每张上传图分别作为主图生成」选项的理解。需要在商品套图界面和生成确认流程中明确说明两种模式，同时验证多图提交不会破坏历史任务、点数展示、异步轮询和其他模块。

## 方案

- 在逐图主图勾选项旁增加中文 helper：
  `多款式/多SKU图请勾选；同一商品多角度图不勾选，其余图将作为参考图一同提交。`
- 生成确认弹窗说明当前模式、主图与参考图数量、配置生成张数和预计请求点数。
- 上传超过 8 张时明确提示仅使用前 7 张参考图，其余不参与本轮生成。
- 以 `1180x760` 和最小窗口尺寸检查 helper、确认文案不截断、不重叠。
- 增加端到端回归：不勾选多角度图、勾选多 SKU 图、单图、3 图、9 图、历史 NULL job、重试恢复和参考图缺失。
- 验证取消、失败、自动重试、轮询、点数展示和生成历史不受影响。
- 验证 ② AI 生成封面、AI 帮写、③ 更新蝦皮、CDP 流程不受影响。
- **发布门槛**：本任务是 T-658a/b/c/d 发布单元的收口——全部验收通过前不得打包发布安装程序（a/b 先行落地的中间版本存在提示词与实际提交不符的窗口）。

## 验收要点

- 用户能在生成前理解两种参考图模式及实际图片数量。
- 多图请求失败时显示中文可操作提示，不暴露内部接口路径或原始堆栈。
- 9 张图片只提交主图加 7 张参考图，并在确认框和日志中说明。
- 全流程测试通过，历史单图任务仍可查看、恢复和重试。
- GUI 最小窗口下布局稳定，所有用户可见文字符合中文规则。

## 边界（不改什么）

- 不修改 cmhub 服务端协议、计费、并发和轮询策略。
- 不修改 ③ 更新蝦皮、CDP、主图拉取和 AI 帮写的业务逻辑。
- 不实现多 SKU 自动识别或多图联合生成拼图。

## 验证

```bash
py -3.10 -m unittest tests.test_product_suite_gui
py -3.10 -m unittest tests.test_product_suite tests.test_image_studio tests.test_image_studio_generation
py -3.10 -m unittest discover -s tests
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check
```

## 执行记录

- 2026-07-17：在「每张上传图分别作为主图生成」右侧新增可换行中文 helper，说明多SKU逐图生成与同商品多角度参考图两种使用场景；在 1180x760 下覆盖布局断言。
- 2026-07-17：生成确认框根据最终 specs 展示主图/参考图提交语义；未开启逐图主图且上传超过8张时，明确“前7张参考图”和忽略数量，点数估算仍只按 job 请求数。
- 2026-07-17：补充 helper、9张原图上限提示及确认框文案的 GUI 测试；同步路由、架构和 API 文档。
- 验证通过：`py -3.10 -m unittest tests.test_product_suite_gui`（58项）、`py -3.10 -m unittest discover -s tests`（587项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。离屏 Qt 的字体/插件警告不影响测试结果。