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 时视为没有参考图，查看、恢复和重试继续单图提交，不根据当前项目图片列表补图。
• 参考图片文件缺失时，优先保证“提示词数量”和“实际提交数量”一致：该 job 按中文错误失败并记录缺失资产，不静默跳过导致语义不一致。若最终采用“跳过缺失图”，必须同步重新生成并持久化本次尝试的 prompt 与实际资产快照。
• 主图文件缺失继续按现有失败语义处理。

验收要点

• 生成开始后增删、排序上传图片，不影响已创建 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

执行记录

• 待实现。