cmshoppe/docs/tasks/T-660.md

---
id: T-660
title: 商品套图未逐图主图模式使用固定参考图规则文案
status: DONE
phase: 7
deps: [T-658c]
created: 2026-07-17
---

# T-660 商品套图未逐图主图模式使用固定参考图规则文案

## 问题 / 背景

T-658c 为未勾选「每张上传图分别作为主图生成」的多图任务，按实际参考图数量生成扩展的 `{参考图规则}`。运营需要提示词模板中的变量值保持固定、简洁，避免上传图片数量变化时预览和最终提示词出现不同序号及数量描述。

## 需求定稿

当未勾选「每张上传图分别作为主图生成」时，`{参考图规则}` 的变量值统一为：

```text
参考图规则:使用第一張上傳圖作為主商品圖，其餘圖片只作為參考。
```

该文案不随实际上传数量或 cmhub 最终提交的参考图数量变化。勾选「每张上传图分别作为主图生成」时，继续使用现有单图规则，不在本任务调整。

## 实现方案

- 修改 `app/product_suite.py` 中统一生成 `{参考图规则}` 的 helper：逐图主图模式保持现有单图规则；未逐图主图模式一律返回上述固定繁体中文文案。
- `build_job_specs()` 与提示词设置弹窗继续复用同一 helper，确保预览与实际 job prompt 完全一致。
- 保留 T-658a/T-658b 已完成的多图 `images` payload、最多 8 张图片限制、主图/参考图排序及快照逻辑；本任务只改 prompt 文案，不改变实际图片提交行为。
- 同步更新与商品套图提示词规则相关的架构/API 文档，替换 T-658c 中已过期的“按第 1 张、第 2 至 N 张”表述。

## 验收要点

- [ ] 未勾选逐图主图时，上传 1 张、3 张、8 张原图，预览和最终 job prompt 中的 `{参考图规则}` 都严格为固定文案。
- [ ] 勾选逐图主图时，仍为既有的「当前上传图片是本任务唯一主参考图」规则。
- [ ] 提示词设置弹窗预览与 `build_job_specs()` 生成的最终 prompt 一致。
- [ ] 多图 `images` 请求、参考图冻结快照、8 张上限、生成数量和点数计算均不变。

## 测试要求

- 更新 `tests/test_product_suite.py`：覆盖未逐图主图的 1 张、3 张、8 张输入均返回固定规则，逐图主图规则不回退。
- 更新 `tests/test_product_suite_gui.py`：覆盖提示词设置弹窗多图预览与实际 job prompt 一致。

## 文档同步

- 实现时更新 `docs/04-architecture.md`、`docs/api.md` 及必要的 `docs/routes.md`，使其与固定文案语义一致。
- 不修改冻结的 `docs/06-tasks.md`。

## 边界（不改什么）

- 不修改 cmhub 请求 payload、数据库 schema/迁移、图片上传/下载、任务快照、生成并发或计费。
- 不修改蝦皮 CDP、采集、更新、Excel 或账号流程。
- 不新增提示词占位符，也不改变现有提示词模板的其它变量。

## 验证

```bash
py -3.10 -m unittest tests.test_product_suite tests.test_product_suite_gui
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check
```

## 执行记录

- 2026-07-17：`product_suite_reference_rule()` 改为仅在勾选「每张上传图分别作为主图生成」时使用既有单图规则；未勾选时无论实际参考图数量均返回固定文案“参考图规则:使用第一張上傳圖作為主商品圖，其餘圖片只作為參考。”。
- 2026-07-17：保留 `reference_asset_ids` 快照、最多 8 张图片提交与确认提示的原有逻辑；提示词设置弹窗预览和 `build_job_specs()` 继续共用同一 helper。
- 2026-07-17：补充 1、3、8 张原图实际 job prompt 与多图预览一致性回归测试；同步架构和 API 文档。
- 验证通过：`py -3.10 -m unittest tests.test_product_suite tests.test_product_suite_gui`（67 项）、`py -3.10 -m unittest discover -s tests`（588 项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。离屏 GUI 测试有 Qt 字体/插件告警，但无测试失败。