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

id, title, status, phase, deps, created

id	title	status	phase	deps	created
T-658d	商品套图多图参考 GUI 与全流程回归	DONE	7	T-658a T-658b T-658c	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 自动识别或多图联合生成拼图。

验证

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 的字体/插件警告不影响测试结果。