feat: snapshot product suite reference assets

docs/04-architecture.md

@@ -438,6 +438,7 @@ data/images/<batch_id>/<slug>/<task_id>_<item_id>_new.<ext>    # AI 生成的新
 - 并发数、重试、分辨率、jpg 质量、模型/Key 均来自设置（`data/config.json` 的 `ai` 段；Key 存 `data/config/cmhub.json` 或 direct 兼容清单）。T-547 后标题并发和图片并发都限制为 1..5，失败重试次数限制为 0..10；旧 `config.json` 或手工配置的超限值会在加载/保存时夹紧。设置仍只展示一个「图片并发」设置；cmhub 模式下②运行日志显示“图片并发 X，cmhub实际生图并发 Y，下载并发 Y”。
 - 商品套图固定使用设置保存的 cmhub 生图 alias。T-651 后，常规新一轮生成先完成历史确认，再按最终 `build_job_specs()` 在后台读取或复用短期模型目录缓存，最后才显示数量和扣点确认；逐图主图开启时白底图仅使用第一张原图，其他分类按每张原图展开。固定分类顺序为白底图、场景图、模特场景图、细节说明图、卖点图；默认数量为1、2、0、0、2，新增分类不因升级自动产生任务。只有当前生图别名存在唯一无条件 `points_cost` 时显示单张与总预估点数，总数严格按 planned job 数量计算；目录不可用或价格有条件时不显示数字。确认默认、Esc 或关闭均取消，计划在读取期间发生变化时不提交旧 specs；单图重试和恢复不进入该常规确认。预估不落库、不预扣，实际扣点仍以 job 的 cmhub 响应为准。T-637 后套图提示词事实来源分为：安装包只读默认 `app/default_prompts/product_suite/base.txt`、用户全局模板 `data/prompts/product_suite/base.txt`、`app/product_suite.py` 中的分类目标、结构化上下文与只读规则常量。用户模板首次缺失或为空时，必须先按完整占位符契约校验内置模板，再通过原子写入初始化；已有用户模板不被升级静默覆盖。模板无效时在创建 project/job/worker 和调用 cmhub 前阻断新一轮生成，单张历史重试继续使用原 `image_studio_jobs.prompt` 快照。
 - T-658a 后商品套图异步生图提交统一使用 `images` 数组，单图也使用单元素 `{"image_base64": ...}`，不再提交顶层 `image_base64`。提交层最多传 8 张本地图片，单图原文件上限10MiB、编码后总输入上限32MiB；超限在请求前以中文错误阻断，后续多图参考的资产快照和提示词语义由 T-658b/T-658c 负责。
+- T-658b 后 `image_studio_jobs.reference_asset_ids` 以有序 JSON 图片 ID 列表冻结每个商品套图 job 的参考图；新一轮未勾选逐图主图时，第1张为主图、后续最多7张写入快照，勾选时写空数组。历史 `NULL` 行继续按单图任务处理。恢复或重试只读 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/主参考图序号、参考图规则、商品卖点和四个只读规则。旧模板必须同时包含 `{套图名称}` 与 `{补充描述}` 才能按兼容路径继续使用；必需变量缺失、未知/未闭合花括号、只读规则变量未独占一行都视为无效。`{参考图规则}` 的变量值以 `参考图规则:` 开头：`per_image_primary=true` 时为“参考图规则:当前上传图片是本任务唯一主参考图；保持商品主体、款式、颜色和关键细节准确；不编造用户与参考图均未提供的信息。”，否则为“参考图规则:使用第一張上傳圖作為主商品圖，其餘圖片只作為參考。”。默认模板独占一行，不额外重复标签或序号。四个只读规则覆盖尺寸与长图（含禁止多宫格拼接）、政治标识、价格和尺码；商品主体一致性与禁止编造并入逐图主图规则。比例仍同时传入 `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`。服务不删除本地文件或蝦皮线上图片，任一资产校验失败时整批回滚。

docs/api.md

@@ -432,6 +432,7 @@ export_generation_round(project_id, generation_round_key, parent_dir, path=None,
 - `remove_original_assets_if_unused()` 会先校验整批原图的项目归属、资产类型及 job/终选引用，再在单个事务中删除资产行并连续重排 `source_order`；任一图片不可删除时整批不变，本地源文件和蝦皮线上图片始终保留。
 - cmhub 托管生图每张都是独立 job：保存 `task_key/task_id/status/call_id/points_cost/points_balance`；已有 `task_id` 时只 poll/download，不重复 submit。商品套图把平台/国家/语言/比例等上下文写入每个 job prompt，并把比例实参传到 cmhub；界面不展示 Provider URL、OpenAI Key 或上游接口路径。
 - T-658a 后商品套图异步提交的图片字段统一为 `images` 数组（每项仅含本地编码的 `image_base64`），单图不再保留顶层 `image_base64` 兼容字段。提交层限制最多8张、单图原文件10MiB、编码后总输入32MiB；参考图快照字段由 T-658b 扩展。
+- T-658b 后 `image_studio.create_job(..., reference_asset_ids=...)` 接收同项目、去重且不包含主图的有序图片 ID 列表，并以 JSON 快照写入 `image_studio_jobs.reference_asset_ids`；`job_reference_asset_ids(job)` 负责解析和校验。历史 `NULL` 快照返回空列表，恢复/重试不根据当前商品原图补图。
 - `include_failed_downloads=True` 允许 failed 但已有 `task_id`、无输出 asset 的任务继续查询，用于下载失败或本地保存失败恢复。
 - 终选顺序由 `replace_selections()` 事务替换，主图/详情图同类别去重、跨类别可复用。
 - 导出只写 JPEG 图片文件，透明图铺白底；商品目录已存在时只能覆盖受管命名文件或新建带时间目录，不合并、不递归清空。

docs/tasks/T-658b.md

@@ -1,7 +1,7 @@
 ---
 id: T-658b
 title: 商品套图多图参考任务快照与历史兼容
-status: TODO
+status: DONE
 phase: 7
 deps: [T-658a]
 created: 2026-07-17
@@ -63,4 +63,8 @@ git diff --check
 
 ## 执行记录
 
-- 待实现。
+- 2026-07-17：新增 `image_studio_jobs.reference_asset_ids TEXT` additive 迁移，并扩展 `ImageStudioJob`、`create_job()` 与快照解析校验；历史 `NULL` 保持单图语义。
+- 2026-07-17：`build_job_specs()` 在未勾选逐图主图时冻结第1张后的最多7张参考图；GUI worker、计划签名和单图重试均传递原 job 快照。
+- 2026-07-17：运行时仅在尚未提交 cmhub 的 job 读取参考图快照；资产或本地文件缺失时提交前失败，不静默减少图片数量。已有 `task_id` 的任务继续只轮询下载，不要求历史参考文件仍存在。
+- 2026-07-17：补充 schema/历史 NULL、跨任务快照、参考图提交顺序和缺失参考图不提交的测试；同步架构/API 文档。
+- 验证通过：`py -3.10 -m unittest tests.test_product_suite tests.test_image_studio tests.test_image_studio_generation`（46项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。