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

---
id: T-658b
title: 商品套图多图参考任务快照与历史兼容
status: TODO
phase: 7
deps: [T-658a]
created: 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 控件。
- 不改变点数、并发、轮询和蝦皮更新流程。

## 验证

```bash
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
```

## 执行记录

- 待实现。