feat: fix product suite reference prompt rule

docs/04-architecture.md

@@ -441,7 +441,7 @@ data/images/<batch_id>/<slug>/<task_id>_<item_id>_new.<ext>    # AI 生成的新
 - T-658b 后 `image_studio_jobs.reference_asset_ids` 以有序 JSON 图片 ID 列表冻结每个商品套图 job 的参考图；新一轮未勾选逐图主图时，第1张为主图、后续最多7张写入快照，勾选时写空数组。历史 `NULL` 行继续按单图任务处理。恢复或重试只读 job 快照，不回读当前原图列表；参考图资产或本地文件缺失时提交前失败，不静默减少提交数量。
 - T-658d 后逐图主图 checkbox 右侧显示可换行中文 helper，说明多SKU应逐图生成、同商品多角度应作为参考图一同提交。常规生成确认框从最终 specs 计算主图/参考图数量；未开启逐图主图且可用原图超过8张时，明确第1张主图加前7张参考图的上限和忽略数量。确认总点数仍只按 job 请求数计算，不因单请求图片数量重复计算。
 - T-647 后商品套图中的「AI帮写」不是②标题生成的复用入口：它使用 `vision_alias` 调 `POST /api/v1/analyze/images`，把当前项目中1至8张可用本地原图按 `source_order` 在一次请求中发送；超过8张时明确只使用前8张，原图勾选状态不改变该输入集合。视觉提示词将这些图片定义为同一商品项目的多角度、细节、包装或场景证据集，要求产出一份商品级联合分析，不按“图1/图2”逐图罗列；结果按商品概述、可确认卖点、适用人群与场景、套图画面要求、待确认或避免编造的信息组织，并把可见差异明确为待确认项，不强行合并为事实。单图上限10MiB、总计上限32MiB，缺图、未下载、超限或未配置别名时不发请求且保留用户现有卖点。读取等待固定120秒、连接等待沿用设置；读超时或网络中断只提示“结果未确认”，不自动重发。成功只显示图片张数、扣点和余额，不显示路径、base64、接口URL、完整提示词或上游原始响应；取消只在请求前/返回后协作生效，不强杀网络线程。
-- `product_suite.render_product_suite_prompt()` 是弹窗预览和真实生成的唯一 renderer；`build_job_specs()` 建立本轮 specs 前只读取一次用户模板并冻结，每个 job 保存最终完整 prompt，运行中修改模板只影响下一轮。新模板使用 `{生成目标}`，其值为内置分类固定目标描述或含实际名称的“生成自定义分类图片：分类名称。”；同时保留 `{套图名称}`、`{补充描述}` 及平台/地区/语言/比例、可选商品ID/主参考图序号、参考图规则、商品卖点和四个只读规则。旧模板必须同时包含 `{套图名称}` 与 `{补充描述}` 才能按兼容路径继续使用；必需变量缺失、未知/未闭合花括号、只读规则变量未独占一行都视为无效。`product_suite_reference_rule()` 是 `{参考图规则}` 的唯一事实来源，变量值都以 `参考图规则:` 开头：逐图主图开启或实际参考图数为0时为单图主参考规则；未开启且快照有1至7张参考图时为“第1张主商品图、第2至N张仅作参考”的多图规则，N 必须等于实际提交总图片数。提示词弹窗按当前可用原图数计算，job 按冻结的 `reference_asset_ids` 渲染，两者共用 renderer。默认模板独占一行，不额外重复标签或序号。四个只读规则覆盖尺寸与长图（含禁止多宫格拼接）、政治标识、价格和尺码；商品主体一致性与禁止编造并入参考图规则。比例仍同时传入 `image_studio_generation.run_jobs(aspect_ratio=...)`，进入 cmhub 请求与输出资产元数据。
+- `product_suite.render_product_suite_prompt()` 是弹窗预览和真实生成的唯一 renderer；`build_job_specs()` 建立本轮 specs 前只读取一次用户模板并冻结，每个 job 保存最终完整 prompt，运行中修改模板只影响下一轮。新模板使用 `{生成目标}`，其值为内置分类固定目标描述或含实际名称的“生成自定义分类图片：分类名称。”；同时保留 `{套图名称}`、`{补充描述}` 及平台/地区/语言/比例、可选商品ID/主参考图序号、参考图规则、商品卖点和四个只读规则。旧模板必须同时包含 `{套图名称}` 与 `{补充描述}` 才能按兼容路径继续使用；必需变量缺失、未知/未闭合花括号、只读规则变量未独占一行都视为无效。`product_suite_reference_rule()` 是 `{参考图规则}` 的唯一事实来源，变量值都以 `参考图规则:` 开头：逐图主图开启时为单图主参考规则；未开启时固定为“使用第一張上傳圖作為主商品圖，其餘圖片只作為參考。”，不随实际参考图数量变化。提示词弹窗与 job 共用 renderer；实际提交的参考图数量仍由冻结的 `reference_asset_ids` 决定。默认模板独占一行，不额外重复标签或序号。四个只读规则覆盖尺寸与长图（含禁止多宫格拼接）、政治标识、价格和尺码；商品主体一致性与禁止编造并入参考图规则。比例仍同时传入 `image_studio_generation.run_jobs(aspect_ratio=...)`，进入 cmhub 请求与输出资产元数据。
 - `image_studio_projects.suite_settings_json` 持久化套图设置，旧数据库由 `db.init_db()` 原位补列，默认 `{}`；`draft_prompt` 继续保存卖点文本。`image_studio_assets` 中有效商品原图最多16张，历史 missing 记录不占有效名额；手工原图不会因再次同步蝦皮 URL 被误标 missing。商品套图原图列表的批量勾选只保存在当前 `SuiteTaskState` 对应的界面上下文，不写库；批量移除由 `remove_original_assets_if_unused()` 一次校验项目归属、原图类型和 job/终选引用，并在单个 SQLite 事务中删除资产行、连续重排 `source_order`。服务不删除本地文件或蝦皮线上图片，任一资产校验失败时整批回滚。
 - T-636 起，`image_studio_projects` 增加 `binding_state`（`draft` / `bound`）和稳定 `storage_key`。既有项目迁移为 `bound`，并以原 `item_id` 回填 `storage_key`；项目目录改用 `storage_key`，因此临时草稿绑定正式商品 ID 后不移动目录、不改写已有资产路径。草稿内部使用 `draft_<uuid>` 作为仅数据库可见的非空 `item_id`，GUI 输入框始终保持空白，用户日志和 cmhub 提示词只使用“临时草稿”或“未绑定商品”，不得暴露该内部值。
 - 在商品套图中，已选账号但未填写商品 ID 时允许输入卖点、导入、拖入或粘贴本地图片。非空卖点在现有防抖稳定后会创建一个可恢复临时草稿并保存到 `image_studio_projects.draft_prompt`；首次有效图片导入也会创建草稿。空白卖点、取消选择和全部导入失败不保留空草稿。只有卖点的草稿同样属于可恢复业务内容；卖点清空且没有资产/job 时仍可按空草稿规则清理。草稿可管理本地图片、AI 帮写、生成套图、查看历史和打开结果目录，但在创建 worker、启动 Chrome 或执行 CDP 前禁止「拉取蝦皮主图」。输入合法数字商品 ID 后，经确认原地绑定同一个 `project_id`；资产、job、selection、提示词、套图设置和 `storage_key` 均保持不变。若同账号目标 ID（含软删除项目）已存在则拒绝覆盖或合并。

docs/api.md

@@ -438,7 +438,7 @@ export_generation_round(project_id, generation_round_key, parent_dir, path=None,
 - 导出只写 JPEG 图片文件，透明图铺白底；商品目录已存在时只能覆盖受管命名文件或新建带时间目录，不合并、不递归清空。
 - 所有真实网络/CDP/图片生成/下载/转码由 GUI worker 调用；Widget slot 不直接执行长耗时操作。
 - 商品套图默认提示词首行使用 `{套图名称}` 与 `{生成目标}`，结构为“生成目标：{套图名称},{生成目标}”；五个内置分类使用固定目标描述，自定义分类使用“生成自定义分类图片：分类名称。”并注入实际分类名称。旧模板同时包含 `{套图名称}` 和 `{补充描述}` 时继续兼容，预览和 `build_job_specs()` 使用同一 renderer，job 保存最终提示词快照。
-- `product_suite_reference_rule(settings, reference_asset_count)` 是 `{参考图规则}` 的唯一文案来源：逐图主图开启或实际参考图数为0时返回单图规则；未开启且参考图数为1至7时返回“第1张为主商品图、第2至N张仅作参考”的多图规则。`product_suite_prompt_context()`、提示词弹窗预览和 `build_job_specs()` 都使用该 helper；默认模板独占该变量行，不额外重复标签和序号。
+- `product_suite_reference_rule(settings, reference_asset_count)` 是 `{参考图规则}` 的唯一文案来源：逐图主图开启时返回单图规则；未开启时始终返回“参考图规则:使用第一張上傳圖作為主商品圖，其餘圖片只作為參考。”，不随 `reference_asset_count` 变化。`product_suite_prompt_context()`、提示词弹窗预览和 `build_job_specs()` 都使用该 helper；默认模板独占该变量行，不额外重复标签和序号。该固定提示词不改变实际 `reference_asset_ids` 的提交数量和顺序。
 - `ProductSuiteTab._generation_confirmation_message()` 从最终 specs 的 `reference_asset_ids` 计算本次主图与参考图说明；未开启逐图主图且上传超过8张时，必须在确认框显示“参考图仅取前7张”和忽略数量。该说明不改变 `len(specs)`、点数估算或 cmhub 并发计划。
 
 ## gui 模块（`app/gui/` 包，已建，PySide6）

docs/tasks/T-660.md

@@ -1,7 +1,7 @@
 ---
 id: T-660
 title: 商品套图未逐图主图模式使用固定参考图规则文案
-status: TODO
+status: DONE
 phase: 7
 deps: [T-658c]
 created: 2026-07-17
@@ -64,4 +64,7 @@ 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 字体/插件告警，但无测试失败。