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

id, title, status, phase, deps, created

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

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

问题 / 背景

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

方案

• 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

执行记录

• 待实现。