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

## 验证

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

## 执行记录

- 待实现。