docs(tasks): refine custom gateway product suite plan

docs/tasks/T-679.md

@@ -1,80 +1,42 @@
 ---
 id: T-679
-title: 商品套图接入自定义网关（主图 + 参考图）
+title: 商品套图接入自定义网关（集成验收）
 phase: 7
-deps: [T-677, T-678]
+deps: [T-679a, T-679b, T-679c]
 status: TODO
 created: 2026-07-20
 ---
 
-# T-679 商品套图接入自定义网关（主图 + 参考图）
+# T-679 商品套图接入自定义网关（集成验收）
 
 ## 问题 / 背景
 
-T-677 在自定义网关（`ai.backend=direct`）下停用了⑥商品套图的新建、重试与「AI 帮写」，只保留已提交默认网关任务的取回入口。现在需要让⑥的生成能力也能走自定义网关，使 cmhub 上游不稳或用户自备算力时，套图不再是唯一断链的模块。
+商品套图从只支持默认网关扩展为支持自定义网关，涉及持久化 job 来源、同步请求、停止与失败语义、生成确认、历史与已提交默认网关任务恢复。原任务同时修改这些层次，风险和验收面过大，现拆为 T-679a、T-679b、T-679c；本任务只负责三项完成后的跨层集成验收。
 
-相关代码事实：
+## 集成要求
 
-- `app/image_studio_generation.py` 的来源耦合只有两处：`_runtime()`（:35）写死 `ai._cmhub_runtime(config, "image", ...)`，以及 `_submit_or_resume_job()`（:401）的 cmhub 提交与 `_poll_job()`（:325 调用）轮询。建 job、并发槽、停止、输出路径、存资产、重试删除历史、进度事件**已经与来源无关**。
-- **direct 是同步路径**：`_call_with_retry()` 返回后 `_extract_image_bytes()` 取字节、`_save_jpeg()` 落盘（`app/ai.py:387-390`）。因此自定义网关不需要异步状态机，而是**跳过** submit/poll 两步，不是补齐它们。
-- 已提交任务的回收守卫（`app/image_studio_generation.py:200`）判断条件是 `getattr(job, "task_id", None) and not _is_default_gateway_job(job)`，**只拦有 `task_id` 的 job**。direct job 天然没有 `task_id`，自动不被拦截，该守卫无需修改即可继续保护已扣点的 cmhub 任务。
-- `create_generation_jobs()`（:115）目前把 `generation_source` 与 `provider` 硬编码为 `"cmhub"`，接入多来源后必须写入真实来源，否则回收守卫的判断依据失效。
-
-**能力边界必须如实表达**：cmhub 的多图契约中，首图为主体且由服务端强制追加"保留主体"规则，客户端无法覆盖（T-658 已确认）。OpenAI 图片编辑接口的多图输入没有等价契约，主体保留只能写入提示词由模型自行遵守。对白底图这类"必须仍是同一件商品"的场景，两者不等价，不得因为支持多图就宣称效果相同。
-
-## 方案
-
-### 1. 来源分派（两处接缝）
-
-- `_runtime()`（:35）改为按来源返回带稳定来源标记的运行时对象：默认网关沿用 `ai._cmhub_runtime()`；自定义网关解析本轮实际使用的图像模型，复用 T-677 的 `ai.freeze_runtime_config()` 快照与 `ai._role_model("image", ...)`。运行时对象仅存在于内存，密钥不得写入 SQLite、运行日志、异常正文或 UI。
-- `_submit_or_resume_job()`（:401）按来源分支：默认网关保持现有异步提交；自定义网关走 T-678 提供的多图同步请求，直接返回图片字节。
-- `_run_one_job()`（:284）在自定义网关下跳过 `_poll_job()`（:325），直接进入保存分支。`request_result` 的契约需要能同时表达"远程 URL 待下载"（cmhub）与"字节已在手"（direct），两种形态都要能走到 :329 的保存与 :344 的 `add_asset()`。
-- `create_generation_jobs()`（:115）写入真实 `generation_source` / `provider`，不再硬编码 `"cmhub"`。
-- `_ensure_new_submission_allowed()`（:47）放开自定义网关；三层守卫（`create_generation_jobs()`、`ProductSuiteGenerateWorker`、`_submit_or_resume_job()`）继续使用同一守卫函数，改为按来源判断可用性而不是逐层各写一遍。
-
-### 2. 主图与参考图
-
-- 未勾选「每张上传图分别作为主图生成」时，自定义网关按 T-678 的多图请求提交：第一张为主体图，其余为参考图，数量上限按所选模型与服务商实际限制处理并在超限时给出中文提示。
-- 勾选逐图主图时维持现有每图单独提交的语义，不引入跨 SKU 混图。
-- 主体保留只能通过提示词表达：把"第一张为商品主体、必须保持商品本体不变，其余仅供风格与场景参考"拼进发送给自定义网关的提示词。**不得**声称与默认网关等价。
-- ⑥在自定义网关下显示中文说明：参考图效果取决于所选模型，主体一致性弱于默认网关。
-
-### 3. 停止、超时与并发
-
-- **停止会变迟钝**：direct 是一次同步 HTTP 请求，请求发出后没有中断点，`should_stop` 只能在两张图之间生效。UI 必须如实说明"正在停止，需等待当前图片返回"，不得让用户误判为卡死；不得用 `processEvents()` 或强杀线程伪装成即时取消。
-- 自定义网关不使用 `CMHUB_IMAGE_SUBMIT/POLL/READ_TIMEOUT`（:446、:513、:485）这套为异步设计的常量，改用模型自身配置的超时秒数。
-- 并发沿用现有 `MAX_CMHUB_IMAGE_STUDIO_WORKERS = 5` 与全局信号量（:15-16），本任务不调整取值，避免把针对 cmhub 的保护与用户自备服务的限流混为一谈。
-- 套图传入的是 `aspect_ratio`（如 `1:1`），OpenAI 图片编辑接口吃的是尺寸文本，需要一层明确换算；换算规则与不支持的比例回退口径要有测试。
-
-### 4. 费用口径与不变部分
-
-- ⑥在自定义网关下不显示"预计消耗 X 点"，改用 T-677 在②已定的口径「自定义网关（不计点数，费用由服务商收取）」，不得显示 `0 点`或沿用旧余额。默认网关下点数预估与余额展示不变。
-- 「AI 帮写」在自定义网关下继续不可用：`appconfig.CATEGORIES` 无 vision 类别，自定义模型没有图片理解配置位。入口保持置灰并说明仅默认网关支持。
-- 已提交默认网关任务的「继续查询已提交图片」入口与回收守卫（:200）保持不变；切到自定义网关不得影响已扣点任务的轮询、下载与保存。
+- 默认网关任务继续使用 `generation_source="cmhub"`、`provider="cmhub"`、异步 task ID、轮询、幂等键和点数账本。
+- 自定义网关任务使用 `generation_source="direct"`、`provider="openai_images_edits"`、`task_id=NULL`、同步单图请求；不得进入 cmhub 轮询或恢复流程。
+- 同一项目可以同时显示历史 cmhub 与 direct 任务；界面仅显示“默认网关 / 自定义网关”，不显示密钥、完整 URL 或模型名。
+- T-678 的图片编辑契约、T-679a 的任务语义、T-679b 的交互预检和 T-679c 的恢复/历史语义必须一致。
 
 ## 验收要点
 
-- [ ] 自定义网关下⑥可新建并完成套图生成；job 的 `generation_source` / `provider` 记录真实来源，`task_id` 为空。
-- [ ] 未勾选逐图主图时按主图 + 参考图提交，首图为主体；勾选时维持每图单独提交。
-- [ ] 切换来源后，此前已提交的默认网关任务仍可继续查询、下载并保存，不被拒绝、不新建任务、不二次扣点；回收守卫逻辑未被削弱。
-- [ ] 运行中保存⑤来源或修改模型，不影响已启动任务的来源快照；密钥只存在于 worker 内存，未出现在 DB、日志、异常正文或 UI。
-- [ ] 自定义网关下停止在当前图片返回后生效，UI 有"正在停止"的中文说明，不出现伪即时取消或卡死观感。
-- [ ] 自定义网关使用模型自身超时；`aspect_ratio` 到尺寸的换算与不支持比例的回退有明确行为。
-- [ ] ⑥在自定义网关下显示不计点数口径与主体一致性弱化说明；默认网关下点数预估不回归。
-- [ ] 「AI 帮写」在自定义网关下仍不可用并给出中文原因。
-- [ ] 默认网关的套图生成、重试、删除撤销、历史、导出与③更新蝦皮全部不回归。
+- [ ] 两种来源均可完成各自允许的新建任务；切换⑤设置不会改变已启动 worker 的来源快照。
+- [ ] 已提交的默认网关任务在切换到自定义网关后仍可继续查询、下载并保存，绝不二次提交或扣点。
+- [ ] 自定义网关不会访问 cmhub 模型、余额、价格、提交或轮询接口；默认网关行为不回归。
+- [ ] 直连失败、停止、程序中断、手动重试和历史展示符合 T-679a/T-679c 的语义，用户不会误以为未完成任务可自动恢复。
+- [ ] ⑥生成确认、进度、结果卡片和历史页面的来源、比例、费用与主体一致性提示均为中文且一致。
+- [ ] ③更新蝦皮、②生成封面、⑥AI 帮写以及默认网关套图全量回归通过。
 
 ## 测试与文档
 
-- `tests/test_image_studio_generation.py`：来源分派、direct 同步路径跳过轮询、多图请求顺序与主体图位置、`generation_source`/`provider` 写入、已提交 cmhub 任务在来源切换后仍可恢复、无 `task_id` 与来源不匹配的 job 被拒绝、比例换算、停止在图片边界生效。
-- `tests/test_gui.py`：⑥在两种来源下的入口可用性、点数与主体一致性文案、停止提示、AI 帮写仍不可用、运行中保存设置不改变本轮来源。
-- `tests/test_ai.py`：套图复用的多图请求构造与超时取值。
-- 更新 `docs/routes.md`、`docs/04-architecture.md`、`docs/api.md`；如⑥文案或流程变化，同步 `docs/ui/` 对应效果图并在 `docs/ui/README.md` 登记。
+- 跑 T-679a/T-679b/T-679c 的全部验证，再补两来源混合项目、运行中保存⑤设置、切换来源后继续查询旧 cmhub 任务的集成测试。
+- 更新 `docs/04-architecture.md`、`docs/routes.md`、`docs/api.md` 与⑥效果图说明。
 
 ## 验证
 
 ```bash
-py -3.10 -m unittest tests.test_image_studio_generation tests.test_gui tests.test_ai
 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
@@ -83,20 +45,16 @@ git diff --check
 
 ## 边界（不改什么）
 
-- 不新增 vision 类别或图片理解的自定义网关路径；「AI 帮写」仍为默认网关独占。
-- 不改 cmhub 的请求协议、异步 submit/poll 状态机、幂等键、预扣退点账本与已提交任务回收守卫。
-- 不调整套图并发上限与全局信号量取值。
-- 不新增 provider 适配、接口自动探测或任意上游 URL 放行（接口规范由 T-678 锁定）。
-- 不改 SQLite schema、Chrome/CDP、Excel 回写、蝦皮更新流程。
-- 不解除 T-596 的 BYOK 门禁；本任务仍属客户端直连的过渡形态。
+- 本任务不新增功能；只整合并验证 T-679a/T-679b/T-679c 已定义的能力。
+- 不新增图片理解的自定义网关路径，不改 cmhub 协议、Chrome/CDP、Excel 或蝦皮更新流程。
 
 ## 关联
 
-- T-678：自定义网关锁定 OpenAI 规范并支持多图输入（本任务的前置能力）。
-- T-677：⑤生成网关来源切换（本任务**有意放宽**其"不给商品套图新增自定义网关路径"的边界；放宽理由为套图是当前唯一在来源切换后完全断链的模块）。
-- T-658：商品套图多图参考提交规则（cmhub 首图主体、服务端强制保留的契约来源）。
-- T-596：BYOK 总设计与启动门禁（`status: BLOCKED`，正式形态要求经 cmhub 代理并收口 direct）。
+- T-678：自定义网关图片编辑协议。
+- T-679a：多来源 job 状态机。
+- T-679b：商品套图 GUI 与生成确认。
+- T-679c：中断恢复、历史与重试。
 
 ## 执行记录
 
-（做完在这里写：改了什么文件、跑了什么验证命令及结果、遇到的阻塞、关键决策。）
+（做完在这里写：集成测试覆盖、验证命令和结果、发现的跨层问题及处理决定。）