docs: split T-658 into four subtasks

docs/tasks/T-658.md

@@ -1,136 +0,0 @@
----
-id: T-658
-title: 商品套图多图参考提交与主图生成规则
-status: TODO
-phase: 7
-deps: [T-622, T-637]
-created: 2026-07-17
----
-
-# T-658 商品套图多图参考提交与主图生成规则
-
-## 问题 / 背景
-
-⑥「商品套图」当前每个生成请求只向 cmhub 提交**单张**源图（`app/image_studio_generation.py::_submit_or_resume_job()` 的顶层 `image_base64` 字段）。不勾选「每张上传图分别作为主图生成」时，除第一张外其余上传图**完全不参与生成**——用户上传多角度图没有任何价值。调研笔记《虾皮圈电商图生成器提示词组装分析》第 6.1 节指出源项目「提示词声称有参考图、实际未提交」的缺陷，cmshopee 目前靠 `{参考图规则}` 的「唯一主参考图」表述回避了这个不一致，但多图能力本身缺失。
-
-cmhub 图生图接口已更新（cmhub T-620，契约见 obsidian《cmhub-接口对接文档-桌面端生文生图》2026-07-17 版）：
-
-- 新增 `images` 有序数组，1–8 张，每项 `image_base64` 或 `image_url` 二选一；与顶层旧单图字段**互斥**；
-- **第 1 张固定为主商品图**，cmhub 服务端固定要求上游优先保留其主体、外观和关键细节；
-- **第 2 张及之后为参考图**，仅用于风格、构图、场景或排版，不得替换主商品——该规则由服务端固定追加，客户端 prompt 不能关闭或覆盖；
-- 混用/空数组/空图片项/超过 8 张返回 `400 bad_request`；
-- 单次请求**无论传几张图只扣一次点**，不按图片数量重复扣费；
-- 同步 `/generate/image` 与异步 `/generate/image/tasks` 请求字段一致，桌面端继续走异步 + `Idempotency-Key`（T-564）。
-
-用户已定稿生成规则（2026-07-17 讨论）：不勾选时所有分类「第 1 张主图 + 其余全部作为参考图」一起提交；勾选时维持现行为（逐图主图、单图提交）；白底图按配置数量生成、默认 1 张（现状即如此，不改）。
-
-## 目标
-
-1. **不勾选**「每张上传图分别作为主图生成」时：所有分类的每个请求提交「第 1 张上传图为主图 + 其余上传图按序作为参考图」，受 cmhub 上限约束最多 1+7 张，超出部分忽略并如实告知。
-2. **勾选**时：维持现行为——白底图只用第 1 张、按配置数量生成；其他分类每张上传图分别作为主图、各生成配置数量；每个请求仍**单图提交**（多 SKU 场景防止参考图混款）。
-3. `{参考图规则}` 渲染文本与实际提交严格一致：单图与多图两种文本，参考图数量取实际提交数。
-4. 提交层统一迁移到 `images` 数组结构（单图也用单元素数组），不再使用顶层旧字段，消除两套代码路径。
-5. 参考图列表在 `build_job_specs()` 时冻结进 job 快照，重试/恢复使用快照，不受生成后增删图片影响。
-6. 勾选项旁增加 helper 文案，说明勾选依据（多 SKU 勾选 / 同商品多角度不勾选）。
-
-## 实现方案
-
-### 1. 生成规则矩阵（定稿）
-
-| 场景 | 白底图 | 场景图 / 卖点图 / 自定义分类 | 每请求提交内容 |
-| --- | --- | --- | --- |
-| 不勾选 | 第 1 张为主图，按配置数量生成 | 同左 | 主图 + 其余上传图为参考图（最多 7 张参考） |
-| 勾选 | 第 1 张为主图，按配置数量生成 | 每张上传图分别为主图，各生成配置数量 | 仅当前主图单图提交，无参考图 |
-
-- 张数计算与点数估算不变：`suite_total_count()` 逻辑不动；白底图默认数量保持 1（`DEFAULT_CATEGORY_COUNTS` 现状）。
-- 多图参考不增加点数消耗（cmhub 单次请求扣一次点），确认弹窗的总点数估算无需调整。
-
-### 2. 提交层 payload（`app/image_studio_generation.py`）
-
-- `_submit_or_resume_job()` 的 payload 从顶层 `image_base64` 迁移为 `images` 数组：
-  - 勾选模式 / 无参考图：`images=[{"image_base64": 主图}]`；
-  - 不勾选且有参考图：`images=[{"image_base64": 主图}, {"image_base64": 参考1}, ...]`，参考图按上传顺序排列；
-- 本地文件一律读成 base64（复用 `ai._image_data_url`），不使用 `image_url`（SSRF 校验只放行公网地址，本地路径不可用）。
-- 客户端在提交前裁剪到 cmhub 上限：主图 1 张 + 参考图最多 7 张；不得同时携带顶层旧字段与 `images`（互斥，违者 `bad_request`）。
-- 同步/异步接口字段一致；异步提交、`Idempotency-Key`、轮询、退点、重试语义全部不变。
-
-### 3. job spec 与冻结快照
-
-- `build_job_specs()` 为每个 spec 增加 `reference_asset_ids`（有序整数列表，不含 `source_asset_id` 自身）；勾选模式为固定空列表。
-- `image_studio_jobs` 表新增可空列 `reference_asset_ids TEXT`（JSON 数组），走既有 additive 迁移方式；历史行为 `NULL`，语义等同「无参考图」，历史任务查看/恢复/重试不受影响。
-- 「生成套图」点击时冻结：参考图列表与 prompt 同时进入 job 快照；生成过程中增删上传图只影响下一轮。
-- 重试/恢复读取快照 `reference_asset_ids`：若某参考资产文件已缺失（被删除），跳过该参考图、仅以剩余图片提交，并写一条中文日志说明；主图缺失仍按现状让该 job 失败。
-
-### 4. `{参考图规则}` 渲染（衔接 T-637 契约）
-
-- renderer context 增加实际参考图数量；`{参考图规则}` 按提交事实渲染两种文本：
-  - 单图（勾选模式，或不勾选但只上传 1 张）：沿用现文本「当前图片为本任务唯一主参考图；保持商品主体、款式、颜色和关键细节准确；不编造用户与参考图均未提供的信息。」
-  - 多图（不勾选且参考图 ≥1）：「第 1 张为主商品图，请保持其主体、款式、颜色和关键细节准确；第 2–N 张仅作为风格、构图、场景参考，不得替换主商品；不编造用户与参考图均未提供的信息。」N 为实际提交总张数。
-- 该表述与 cmhub 服务端固定追加的多图规则同向，不冲突、不试图覆盖。
-- 提示词设置弹窗预览：预览 context 按当前套图任务的勾选状态与上传图数量计算参考图数；上传 0/1 张或勾选时显示单图文本。占位符契约（14 个变量、必需 9 个）不变。
-
-### 5. GUI 调整（`app/gui/tabs/product_suite.py`）
-
-- 勾选项「每张上传图分别作为主图生成」旁增加 helper 文案（次要灰色小字，参考现有 helper 样式）：
-  `多款式/多SKU图请勾选；同一商品多角度图不勾选，其余图将作为参考图一同提交。`
-- 生成确认弹窗的「逐图主图」说明行更新为新规则表述；不勾选且上传图超过 8 张时，追加一行「参考图仅取前 7 张，其余不参与本轮生成」。
-- `1180x760` 及最小窗口尺寸下 helper 与弹窗文案不截断、不重叠。
-
-### 6. 边界与超限
-
-- 上传图 > 8：参考图取上传顺序前 7 张；确认弹窗与日志如实说明；`{参考图规则}` 的 N 用实际提交数，不用上传总数。
-- 单张参考图读取/编码失败：跳过该参考图并写中文日志，不使整个 job 失败；主图读取失败维持现状（job 失败）。
-- 上传仅 1 张时勾选与否行为一致（单图提交），不出现空参考数组。
-
-## 验收标准
-
-- [ ] 不勾选时，任一分类的生成请求 payload 为 `images` 数组：首元素为第 1 张上传图，后续为其余上传图按序（≤7 张）；不含顶层旧单图字段。
-- [ ] 勾选时，每个请求 `images` 为单元素数组（当前主图）；白底图仍只用第 1 张、按配置数量生成；其他分类每张上传图各生成配置数量。
-- [ ] 白底图默认数量为 1，允许用户调整，生成张数与配置一致；`suite_total_count()` 合计与实际 job 数一致。
-- [ ] 多图与单图请求均只扣一次点；确认弹窗总点数估算与实际扣点一致。
-- [ ] `{参考图规则}` 单图/多图两种渲染与实际提交张数严格一致；弹窗预览与新建 job 的最终 prompt 在同一 context 下完全相同。
-- [ ] `reference_asset_ids` 随 job 冻结落库；生成开始后增删上传图不影响本轮已创建 job；重试使用快照参考图列表。
-- [ ] 历史 job（`reference_asset_ids` 为 NULL）查看、恢复、重试行为不变，按单图提交。
-- [ ] 重试时参考资产文件缺失：跳过缺失项、剩余图片正常提交、写中文日志；主图缺失该 job 失败。
-- [ ] 上传图 > 8 时仅前 7 张作为参考提交，确认弹窗有明确中文说明。
-- [ ] 勾选项旁 helper 文案按定稿文案显示，`1180x760` 与最小窗口尺寸不截断。
-- [ ] 异步提交 `Idempotency-Key`、轮询、自动重试、失败退点语义与 T-564 一致，未被多图改动破坏。
-- [ ] cmhub 返回 `bad_request`（含多图字段混用）按不可重试错误处理并展示中文信息。
-- [ ] ②AI生成封面、AI 帮写、③「更新蝦皮」、CDP、计费展示不受影响。
-
-## 测试要求
-
-- 纯逻辑测试：`build_job_specs()` 勾选/不勾选 × 白底图/其他分类 × 上传 1/3/9 张的 `reference_asset_ids` 与 spec 数量矩阵；参考图排序、去除主图自身、>8 张裁剪。
-- `{参考图规则}` 渲染：单图文本、多图文本（N 取实际提交数）、上传 1 张勾选与不勾选文本一致；预览与 `build_job_specs()` prompt 相等。
-- 提交层：payload 使用 `images` 数组且不含顶层旧字段；单元素与多元素结构；参考图读取失败跳过并日志；主图失败 job 失败。
-- 迁移：新列 additive 迁移幂等；历史 NULL 行为单图提交；快照重试路径。
-- GUI：helper 文案存在与不截断断言；确认弹窗新规则说明与 >8 张提示（进 `tests/test_product_suite_gui.py`）。
-
-## 文档同步
-
-- 实现时更新 `docs/04-architecture.md`：商品套图多图提交规则、`reference_asset_ids` 快照语义、`{参考图规则}` 双态渲染。
-- 不修改冻结的 `docs/06-tasks.md`。
-
-## 验证
-
-```bash
-py -3.10 -m unittest tests.test_product_suite
-py -3.10 -m unittest tests.test_product_suite_gui
-py -3.10 -m unittest tests.test_image_studio_generation
-py -3.10 -m unittest discover -s tests
-py -3.10 -m ruff check app tests main.py
-py -3.10 -m compileall app main.py
-git diff --check
-```
-
-## 非目标
-
-- 不做多 SKU 自动识别或图片语义分组；多图关系由用户通过勾选项声明。
-- 不实现「多图联合生成一张多 SKU 拼图/色卡图」（源项目 `multi_sku` 详情图模式不迁移）。
-- 不修改点数计费规则、并发计划、轮询间隔或 cmhub 协议本身。
-- 不修改 T-637 占位符契约（变量清单与必需集不变，仅 `{参考图规则}` 渲染内容按事实扩展）。
-- 不修改 ③「更新蝦皮」、CDP、蝦皮主图拉取。
-
-## 执行记录
-
-- 待实现。

docs/tasks/T-658a.md

@@ -0,0 +1,52 @@
+---
+id: T-658a
+title: 商品套图多图参考 cmhub 接口与提交 payload
+status: TODO
+phase: 7
+deps: [T-564]
+created: 2026-07-17
+---
+
+# T-658a 商品套图多图参考 cmhub 接口与提交 payload
+
+## 问题 / 背景
+
+商品套图当前每个生图请求只提交一张源图，使用顶层 `image_base64`。不勾选「每张上传图分别作为主图生成」时，除第一张外的图片没有参与生成。cmhub 已提供 `images` 有序数组：第 1 张为主商品图，第 2 至第 8 张为参考图，每项使用 `image_base64` 或 `image_url` 二选一。
+
+## 方案
+
+- 在 `app/image_studio_generation.py` 中集中实现多图 payload 构造。
+- 本地图片统一使用 `images` 数组中的 `image_base64`，不再提交顶层旧字段。
+- 单图也使用单元素 `images` 数组；多图按主图、参考图顺序提交。
+- 每个请求最多提交 8 张图片，超出部分由上游规则明确裁剪，并返回实际提交数量。
+- 保留异步提交、`Idempotency-Key`、轮询、自动重试、失败退点和现有并发语义。
+- 在提交前校验单图和总 payload 大小，避免 Base64 请求体过大；同一轮生成可按资产 ID缓存已编码内容，但必须有界。
+- 为 cmhub 请求增加真实接口契约测试：数组结构、最大数量、字段互斥、空项、错误响应和点数返回。
+- 若接口契约不满足，按中文错误提示失败，不静默回退到旧字段；是否支持旧服务端必须在发布前明确验证。
+
+## 验收要点
+
+- 单图请求只有 `images=[{"image_base64": ...}]`，没有顶层 `image_base64`。
+- 多图请求首元素是主图，后续是按顺序排列的参考图，最多 8 张。
+- 不能同时提交旧字段和新字段；空数组、空图片项、超过上限按可识别错误处理。
+- 每个生图请求的点数以 cmhub 返回值为准，确认现有点数展示没有按图片数量重复计算。
+- 异步任务的幂等、轮询和重试回归测试通过。
+
+## 边界（不改什么）
+
+- 不修改 cmhub 服务端协议、计费、并发和轮询策略。
+- 不修改提示词模板、数据库 schema、GUI 布局、蝦皮 CDP 流程。
+- 不实现图片语义分组或多 SKU 自动识别。
+
+## 验证
+
+```bash
+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
+```
+
+## 执行记录
+
+- 待实现。

docs/tasks/T-658b.md

@@ -0,0 +1,53 @@
+---
+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` 时视为没有参考图，查看、恢复和重试继续单图提交，不根据当前项目图片列表补图。
+- 参考图片文件缺失时，优先保证“提示词数量”和“实际提交数量”一致：该 job 按中文错误失败并记录缺失资产，不静默跳过导致语义不一致。若最终采用“跳过缺失图”，必须同步重新生成并持久化本次尝试的 prompt 与实际资产快照。
+- 主图文件缺失继续按现有失败语义处理。
+
+## 验收要点
+
+- 生成开始后增删、排序上传图片，不影响已创建 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
+```
+
+## 执行记录
+
+- 待实现。

docs/tasks/T-658c.md

@@ -0,0 +1,52 @@
+---
+id: T-658c
+title: 商品套图多图参考生成计划与提示词一致性
+status: TODO
+phase: 7
+deps: [T-655, T-656, T-657, T-658b]
+created: 2026-07-17
+---
+
+# T-658c 商品套图多图参考生成计划与提示词一致性
+
+## 问题 / 背景
+
+当前 `{参考图规则}` 已由 T-657 统一带有 `参考图规则:` 前缀，但内容只覆盖单图。多图提交后，最终提示词必须准确说明主图和参考图数量，且预览内容要与新建 job 使用同一套 context。
+
+## 方案
+
+- 由统一 helper 根据“逐图主图勾选状态、实际可用图片数量、cmhub 裁剪上限”生成参考图规则。
+- 单图保持 T-657 的现有中文表述和前缀：`参考图规则:当前上传图片是本任务唯一主参考图；...`。
+- 多图使用明确的序号规则：第 1 张为主商品图，第 2 至 N 张仅作风格、构图、场景或排版参考，不得替换主商品。
+- `build_job_specs()` 与提示词设置弹窗共用同一 context 构造函数，不能在 GUI 和生成层分别拼接规则。
+- 预览没有图片资产时按 0/1 张显示单图规则；正式生成时以实际提交数量为准。
+- 白底图、场景图、模特场景图、细节说明图、卖点图和自定义分类继续使用现有目标描述与数量配置。
+- 确认弹窗的数量和点数仍按 job 请求数计算；超过 8 张时说明仅使用前 7 张参考图。
+
+## 验收要点
+
+- 单图、3 张、8 张上传图的 prompt 规则分别准确。
+- 勾选逐图主图时每个 job 都使用单图规则；不勾选时使用多图规则。
+- 预览 prompt 与实际 `build_job_specs()` 生成的 prompt 完全一致。
+- 上传 1 张时两种模式行为一致，不出现空参考图描述。
+- 当前 T-657 的变量清单、必需变量、`生成目标：{套图名称},{生成目标}` 格式不回退。
+
+## 边界（不改什么）
+
+- 不新增或删除提示词占位符。
+- 不改变 cmhub 接口 payload、数据库迁移和蝦皮/CDP 操作。
+- 不实现多 SKU 自动识别和图片语义分组。
+
+## 验证
+
+```bash
+py -3.10 -m unittest tests.test_product_suite
+py -3.10 -m unittest 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
+```
+
+## 执行记录
+
+- 待实现。

docs/tasks/T-658d.md

@@ -0,0 +1,54 @@
+---
+id: T-658d
+title: 商品套图多图参考 GUI 与全流程回归
+status: TODO
+phase: 7
+deps: [T-658a, T-658b, T-658c]
+created: 2026-07-17
+---
+
+# T-658d 商品套图多图参考 GUI 与全流程回归
+
+## 问题 / 背景
+
+多图参考会改变用户对「每张上传图分别作为主图生成」选项的理解。需要在商品套图界面和生成确认流程中明确说明两种模式，同时验证多图提交不会破坏历史任务、点数展示、异步轮询和其他模块。
+
+## 方案
+
+- 在逐图主图勾选项旁增加中文 helper：
+  `多款式/多SKU图请勾选；同一商品多角度图不勾选，其余图将作为参考图一同提交。`
+- 生成确认弹窗说明当前模式、主图与参考图数量、配置生成张数和预计请求点数。
+- 上传超过 8 张时明确提示仅使用前 7 张参考图，其余不参与本轮生成。
+- 以 `1180x760` 和最小窗口尺寸检查 helper、确认文案不截断、不重叠。
+- 增加端到端回归：不勾选多角度图、勾选多 SKU 图、单图、3 图、9 图、历史 NULL job、重试恢复和参考图缺失。
+- 验证取消、失败、自动重试、轮询、点数展示和生成历史不受影响。
+- 验证 ② AI 生成封面、AI 帮写、③ 更新蝦皮、CDP 流程不受影响。
+
+## 验收要点
+
+- 用户能在生成前理解两种参考图模式及实际图片数量。
+- 多图请求失败时显示中文可操作提示，不暴露内部接口路径或原始堆栈。
+- 9 张图片只提交主图加 7 张参考图，并在确认框和日志中说明。
+- 全流程测试通过，历史单图任务仍可查看、恢复和重试。
+- GUI 最小窗口下布局稳定，所有用户可见文字符合中文规则。
+
+## 边界（不改什么）
+
+- 不修改 cmhub 服务端协议、计费、并发和轮询策略。
+- 不修改 ③ 更新蝦皮、CDP、主图拉取和 AI 帮写的业务逻辑。
+- 不实现多 SKU 自动识别或多图联合生成拼图。
+
+## 验证
+
+```bash
+py -3.10 -m unittest tests.test_product_suite_gui
+py -3.10 -m unittest tests.test_product_suite tests.test_image_studio tests.test_image_studio_generation
+py -3.10 -m unittest discover -s tests
+py -3.10 -m ruff check app tests main.py
+py -3.10 -m compileall app main.py
+git diff --check
+```
+
+## 执行记录
+
+- 待实现。