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

id, title, status, phase, deps, created

id	title	status	phase	deps	created
T-658b	商品套图多图参考任务快照与历史兼容	DONE	7	T-658a	2026-07-17

T-658b 商品套图多图参考任务快照与历史兼容

问题 / 背景

多图生成不能在运行时依赖当前商品原图列表，否则生成开始后增删、排序或删除图片会改变本轮任务内容。每个生图 job 需要保存有序的参考资产快照，并让重试、恢复继续使用同一快照。

方案

生成规则矩阵（定稿，2026-07-17 讨论，T-658a/b/c/d 共同事实来源）

场景	白底图	场景图 / 模特场景图 / 细节说明图 / 卖点图 / 自定义分类	每请求提交内容
不勾选「每张上传图分别作为主图生成」	第 1 张为主图，按配置数量生成	同左	主图 + 其余上传图按序作为参考图（最多 7 张参考）
勾选	第 1 张为主图，按配置数量生成	每张上传图分别为主图，各生成配置数量	仅当前主图单图提交，无参考图

• 白底图默认数量 1（DEFAULT_CATEGORY_COUNTS 现状），允许用户调整，勾选与否都按配置数量生成——「勾选时白底图/其他分类的主图选择与数量」为现行代码行为，本任务不改，列出仅为规则留档。
• 张数合计与点数估算逻辑（suite_total_count()）不变；多图参考不增加点数（cmhub 单次请求扣一次点）。
• 上传仅 1 张时，勾选与否行为一致（单图提交，无空参考数组）。

快照与迁移

• build_job_specs() 为每个 spec 增加 reference_asset_ids，使用有序整数列表，不包含 source_asset_id。
• 不勾选逐图主图时，使用第 1 张资产作为 source_asset_id，后续最多 7 张作为参考；勾选时保存空列表。
• 在 image_studio_jobs 增加可空 reference_asset_ids TEXT，使用既有 additive、幂等迁移方式。
• 扩展 ImageStudioJob、create_job()、读取、列表和恢复路径，保证字段完整传递。
• 创建 job 时校验参考资产属于同一商品项目、顺序稳定且没有重复主图；以 JSON 快照落库。
• 历史 job 的该字段为 NULL 时视为没有参考图，查看、恢复和重试继续单图提交，不根据当前项目图片列表补图。
• 参考图片文件缺失时定死为 fail-fast：该 job 按中文错误失败并列出缺失资产，不静默跳过。理由：跳过会导致「提示词声称 N 张、实际提交少于 N 张」的语义不一致；而“跳过后重写 prompt 与快照”违反 T-637 的冻结语义（历史重试必须使用原快照，不得重写），两条弥补路径都不可取。用户可删除该 job 后重新生成来获得与当前图片状态一致的新任务。
• 主图文件缺失继续按现有失败语义处理。

验收要点

• 生成开始后增删、排序上传图片，不影响已创建 job。
• 重试和恢复读取数据库快照，不读取当前图片列表。
• 新列重复迁移不会报错；旧数据库和历史 NULL job 均可正常读取。
• 参考资产跨项目、重复主图、非法 JSON 有明确中文错误处理。
• 参考图缺失时不会出现 prompt 声称 N 张但实际提交少于 N 张的情况。

边界（不改什么）

• 不修改 cmhub payload 结构的具体构造逻辑，接口提交由 T-658a 负责。
• 不修改提示词模板和 GUI 控件。
• 不改变点数、并发、轮询和蝦皮更新流程。

验证

py -3.10 -m unittest tests.test_image_studio tests.test_product_suite
py -3.10 -m unittest tests.test_image_studio_generation
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check

执行记录

• 2026-07-17：新增 image_studio_jobs.reference_asset_ids TEXT additive 迁移，并扩展 ImageStudioJob、create_job() 与快照解析校验；历史 NULL 保持单图语义。
• 2026-07-17：build_job_specs() 在未勾选逐图主图时冻结第1张后的最多7张参考图；GUI worker、计划签名和单图重试均传递原 job 快照。
• 2026-07-17：运行时仅在尚未提交 cmhub 的 job 读取参考图快照；资产或本地文件缺失时提交前失败，不静默减少图片数量。已有 task_id 的任务继续只轮询下载，不要求历史参考文件仍存在。
• 2026-07-17：补充 schema/历史 NULL、跨任务快照、参考图提交顺序和缺失参考图不提交的测试；同步架构/API 文档。
• 验证通过：py -3.10 -m unittest tests.test_product_suite tests.test_image_studio tests.test_image_studio_generation（46项）、py -3.10 -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check。