276 lines
58 KiB
Markdown
276 lines
58 KiB
Markdown
# 界面与流程结构
|
||
|
||
> 桌面工具，无前端路由。当前正式界面用 **6 Tab GUI（PySide6 `QMainWindow` + `QTabWidget`）+ 流水线** 约定界面职责与导航；商品套图已替换旧 AI工场入口。
|
||
|
||
## Tab 顺序与职责（工作流优先）
|
||
|
||
```
|
||
① 导入采集 │ ② AI生成 │ ③ 更新蝦皮 │ 账号管理 │ 设置 │ 商品套图
|
||
```
|
||
|
||
| Tab | 职责 | 风险 |
|
||
| --- | --- | --- |
|
||
| ① 导入采集 | 导入多个 Excel；任务列表；**采集**商品当前的旧标题/旧封面（只读），封面图下载本地；回写 Excel 旧字段 | 只读，低 |
|
||
| ② AI生成 | 左侧标题/封面**提示词**；右侧按批次/店铺/商品ID/状态筛选任务列表；开始前确认“仅状态正常”或“所有状态”生成范围后，AI 生成新标题，并按本轮开关可选生成新封面；表格拆分显示「标题状态 / 图片状态」；已生成任务可本地微调新标题；双击看新旧封面 | 不触线上，中 |
|
||
| ③ 更新蝦皮 | 对**已生成**任务点击「开始更新」后弹窗确认；确认后打开编辑页换标题+封面并逐条点「更新」提交；结果回写 Excel | **写线上，高** |
|
||
| 账号管理 | Shopee 账号（账号名/别名/数据目录/端口/密码本地明文仅参考/登录状态）；启动登录、检测登录、生成快捷方式；新增账号不自动启动 Chrome，首次启动复用初始卖家中心页，重复操作复用已打开的同账号 Chrome，避免重复开窗口；检测登录遇到 `accounts.shopee.tw/seller/login` 必须显示未登录 | 中 |
|
||
| 设置 | 默认网关/API Key 或自定义网关模型配置、生成参数、Chrome 路径、默认端口、蝦皮更新执行参数等 | — |
|
||
| 商品套图 | 按账号+商品ID管理本地图片项目；拉取/添加商品原图，AI帮写理解图片内容，按套图分类异步生图，查看历史与重试 | 本地生成，中 |
|
||
|
||
旧 `ImageStudioTab` 与 `image_studio_*` SQLite/图片资产服务继续保留作内部兼容；主窗口只创建 `ProductSuiteTab`，不会并列暴露两套第六 Tab，也不会删除或迁移用户既有项目数据。
|
||
|
||
任务的**阶段状态**贯穿各 Tab：`imported → collected → generated → applied`（或 `failed/skipped`）。② 不设逐条人工确认阶段；③ 无常驻提交开关，点击「开始更新」后必须弹窗确认当前筛选范围、任务数量和线上提交风险。各 Tab 聚焦各自阶段的列与按钮，但操作同一批任务（同一 batch）。
|
||
|
||
## 启动强制升级门禁
|
||
|
||
创建六个业务Tab之前先请求版本接口。服务端明确要求强制升级时，不创建 `MainWindow`，而是显示「必须升级」模态进度窗口：用户点击「立即升级」后可看到下载、校验、准备新版和重启阶段，以及百分比和字节数；运行中可「取消并退出」，失败后可重试。校验完成后软件启动安装目录外的独立更新器并退出，更新器替换程序后自动重启新版。版本接口完全不可达或非法时仍失败放行；一旦已明确强制，元数据缺失或后续失败都不允许进入旧版主界面。
|
||
|
||
## 会员订阅接入
|
||
|
||
- 当前处于联调测试期：`app.gui.main_window.SUBSCRIPTION_CHECK_ENABLED = False`，启动、保存设置和新提交均不请求订阅接口，也不限制六个工作流；顶部只显示“会员：订阅检测已暂停”。恢复发布前必须重新启用后再按下列流程验收。
|
||
- 强制升级检查完成、主窗口显示后，后台用 `data/config/cmhub.json` 的 API Key 请求 `GET /api/v1/cmshopee/subscription/status`；不会阻塞 Qt 主线程或把 Key 放入 URL、状态栏、日志和错误提示。
|
||
- 状态接口已启用时，未配置 Key、Key 无效、账号禁用、未订阅、到期、撤销或暂时无法确认会员状态，主窗口只保留「设置」Tab，并在顶部显示中文原因；用户可打开设置重填 Key、按服务端返回的 `manage_url` 用默认浏览器前往线上会员中心，或退出。已接受的异步任务、本地数据和导出不删除。
|
||
- 订阅有效时，应用顶部标题区域右侧显示“账号名 · 套餐名 · 有效至日期”；宽限期显示宽限截止日。不得把长会员文本拼进 Windows 原生窗口标题，也不得展示 API Key。
|
||
- 当前服务端未部署订阅接口时，`404` 视为旧服务兼容：顶部显示“会员服务尚未启用”，六个工作流继续按旧行为运行，不弹阻断窗口。网络或格式错误显示“暂时无法确认会员状态”，不能误报为 Key 无效或会员到期。
|
||
- ② AI生成、⑥商品套图和「AI帮写」的每次新提交均读取同一订阅预检状态；客户端预检只改善体验，cmhub 产品接口仍必须服务端最终裁决。已提交的异步任务继续查询、下载和查看。自定义网关直连同样做客户端软校验，不能作为不可绕过的授权保护。
|
||
|
||
## 全局 Tab 栏可用性
|
||
|
||
当前 6 个主 Tab 是高频导航入口，不能使用 Qt 默认的紧凑宽度。`MainWindow` 必须为 `QTabWidget/QTabBar` 设置基础样式：
|
||
|
||
- 每个 Tab 设置稳定最小宽度和足够左右 padding，避免文字贴边或窄到误点。
|
||
- Tab 之间保留明显间距，当前 Tab 有清晰背景/边框高亮。
|
||
- 样式只影响顶层主 Tab，不改变各业务表格、弹窗和后续 Tab 内部布局。
|
||
- 新增业务 Tab 内容时不得缩小主 Tab 栏点击区域。
|
||
|
||
## 全局状态栏反馈
|
||
|
||
左下角状态栏用于低打扰反馈，T-543 已统一由 `MainWindow.show_status(message, level)` 控制语义色：
|
||
|
||
- 普通/导航/就绪：muted 或系统默认，例如「就绪」「当前：② AI生成」。
|
||
- 信息/进行中：info，例如「正在生成标题」「检测登录中」。
|
||
- 成功：success，例如「设置已保存」「已回写 Excel」。
|
||
- 警告/需用户处理：warning，例如「当前筛选结果没有待生成任务」「请先到①完成旧数据采集」「请先配置 cmhub」。
|
||
- 错误/阻断：danger，例如「更新失败」「账号未登录」「数据目录不可写」「点数不足」。
|
||
|
||
状态栏只改变文字色，不做大面积背景；它不能替代弹窗、空状态、运行日志、按钮禁用和任务状态列。普通提示必须重置状态栏颜色，避免上一条错误或成功颜色残留。
|
||
|
||
## 首次使用引导保护
|
||
|
||
- ① 导入采集 与 ③ 更新蝦皮 都依赖**账号已配置且已登录**（在 账号管理）。
|
||
- ① 点击「采集旧标题/旧封面」后，会为本轮匹配到账号的店铺自动确保 Chrome 就绪：已打开则复用，未打开才启动；随后逐账号检测蝦皮登录态。明确进入登录页的账号任务整组略过并在结束汇总中提示去账号管理人工登录；`NO_SESSION_COOKIE` 或 CDP 短暂读取异常只视为登录状态暂不确定，重试后仍不确定也继续尝试采集，避免误判批量略过。
|
||
- ③ 点击「开始更新」后必须检查当前筛选结果涉及的账号；只要有账号 Chrome 未启动、CDP 端口不可访问或 Shopee 未登录，就弹窗列出账号并中止本轮更新，不创建真实更新 worker，不提交任何商品。
|
||
- 可以提供「打开账号管理」或「启动登录」入口辅助用户处理当前账号；③ 不要无提示批量启动所有账号 Chrome，避免在提交线上前开错账号或启动过多浏览器进程。用户主动点击账号管理中的「启动登录」时必须先检查该账号 CDP 端口：已打开则复用现有 Chrome 并打开/激活卖家中心 tab，不重复 `Popen`；未打开则直接携带卖家中心 URL 冷启动并复用初始 page target，不先开空白页再额外创建页面。启动过程中账号列表和相关按钮禁用，连续点击不排队启动第二轮。
|
||
- 老用户账号已就绪则无感。
|
||
|
||
## ① 导入采集
|
||
|
||
```
|
||
┌ 导入采集 ─────────────────────────────────────────────────────┐
|
||
│ [导入 Excel…] [移除] [清空] │
|
||
│ ▸ 3 文件 · 128 行 · 有效125/无效3 · 匹配123 · 未匹配5⚠ │ ← 导入汇总栏
|
||
│ 匹配明细：女装店60 · my主店40 · 饰品店23 │
|
||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||
│ │ 账号名 别名 商品ID 阶段 旧标题 旧封面 │ │
|
||
│ │ 主店A 女装店 51100639510 待采集 — — │ │
|
||
│ └───────────────────────────────────────────────────────────┘ │
|
||
│ [▶ 采集旧标题/旧封面] [■停止] [回写旧数据到 Excel] │
|
||
│ 日志：逐条 文件→匹配账号、采集步骤、失败原因 │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 导入：openpyxl 解析**输入列**（账号名/别名/商品id）入 SQLite。
|
||
- **导入汇总栏**（导入后即时刷新，跑采集前的校验关口）：显示 文件数、解析行数（原始数据量）、有效/无效行、匹配账号行数（按账号细分）、未匹配行数。未匹配/无效数字标红可点，点击在列表筛出便于定位纠错。
|
||
- 采集：点击后先从专用范围选择框选择范围，默认「采集架上商品」（即检测结果为正常），「采集全部商品」为警示橙色描边而非删除红色，包含未上架、审核中和状态未知商品；三个选项纵向全宽显示，常见 Windows 缩放下不截断。随后为本轮匹配账号确保 Chrome 就绪（已开复用、未开启动），再检测登录；明确未登录账号的任务整组略过并汇总提示。`NO_SESSION_COOKIE`、登录检测超时或 CDP 短暂异常会重试，连续不确定时不批量略过，继续打开商品页由真实页面结果决定成功/失败。登录账号用对应 Chrome 只读打开商品页，先检测并保存商品状态；默认范围下只有正常商品才读旧标题、下载旧封面到 `data/images/<batch_id>/<slug>/<task_id>_<item_id>_old.jpg`，未上架、审核中和状态未知商品按范围略过且不覆盖已有内容。选择全部范围时四类商品均继续采集。采集不主动把商品页切到前台；程序自动新建商品页 tab 时尽量后台创建，采集结束后自动关闭；若复用用户原本打开的 tab，则不关闭。采集结束不关闭账号 Chrome，用户可自行关闭。
|
||
- ①任务表显示账号、别名、商品 ID、阶段和商品状态。商品状态筛选位于「处理状态」筛选左侧，选项为全部商品状态、架上商品、未上架、审核中、状态未知、待检测；新打开①默认「全部商品状态」，确保新导入的待检测记录可见。它与批次、店铺、商品 ID 和处理状态叠加。空状态在①显示为「待检测」，显式 `unknown` 显示为「状态未知」；历史默认的架上商品可在 tooltip 查看“未实时检测”备注。商品状态只影响列表可见范围，不改变采集、生成或更新的安全规则。
|
||
- 商品状态功能于 `2026-07-18T16:34:37` 上线。更早创建的活动历史批次中，空状态在启动数据库时自动按「架上商品」写为 `normal`，备注「历史批次默认按架上商品处理（未实时检测）」且不写检测时间；同一范围内仅把由已知促销编辑提示误写的 `unknown` 修正为 `normal`，保留原检测时间并写明历史修正。其他真实保存的未上架、审核中、状态未知，以及上线时点及之后的空状态均不覆盖；不打开 Chrome、不访问详情页。①不提供「重新检测商品状态」入口。
|
||
- 若商品 ID 已失效、无权限或店铺不匹配，Shopee 可能只弹出短暂错误 toast；采集失败时界面日志应显示捕获到的 toast 文案，并把 toast HTML/URL 写入本地诊断日志，避免用户手动抢复制。只有明确捕获商品失效/商品不存在/无权限类 toast 时，①列表“阶段”列显示“商品失效”；其他商品页打开失败仍显示“失败”。如果失败发生在 `open_product()` 内部，本轮自动新建的商品 tab 必须关闭，复用用户已有 tab 不关闭。
|
||
|
||
- 回写：采集完成后自动把旧标题/旧封面路径批量回写原 Excel；保留「回写旧数据到 Excel」作为手动重试入口（原文件被锁→提示关闭后重试/另存）。
|
||
- 别名未匹配账号 → 该行 skipped 并记原因，不为未匹配别名启动 Chrome。账号预检或采集中途明确进入登录页 → 该账号剩余任务整组 skipped 并记原因，结束汇总列出需补登录的账号；`NO_SESSION_COOKIE` 等不确定检测结果只写日志和诊断信息，不触发整组 skipped。`T-207` 接入后，① 采集会像③更新一样写 `run_logs/run_log_events`，并把完整脱敏 traceback 写入本地 `data/logs/`，用于定位失败卡在哪个步骤。
|
||
|
||
- 「删除批次」位于①批次筛选旁，只能对当前选中的具体批次执行，不能在“全部批次”下执行；运行中禁用。删除是软删除：写本地批次删除标记，不物理删除 DB 记录，不删除原 Excel，不回滚蝦皮。删除后该批次不再出现在①/②/③任何批次下拉、任务列表、筛选、采集、生成、更新、回写入口中。确认框必须显示任务数、已上线任务数，并提示软删除只隐藏本地批次、不会回滚线上修改。
|
||
- ①任务表右键先选中命中行并打开菜单，第一版仅提供「删除本条记录」；右键本身不弹确认框。点击后才确认商品 ID、店铺和批次；已提交线上时明确提示仅删除本地记录、不回滚蝦皮。单条删除写 `tasks.deleted_at/deleted_reason`，运行中禁用且数据库拒绝 `running` 任务；删除后该记录不再进入①/②/③列表、筛选、采集、生成、更新、回写和默认统计，不删除 Excel、本地图片或账号 Chrome 数据。
|
||
## ② AI生成
|
||
|
||
左右布局：左侧约 1/4 放提示词，右侧放筛选 + 任务列表。
|
||
|
||
```
|
||
┌ AI生成 ───────────────────────────────────────────────────────┐
|
||
│ 左侧提示词区： │
|
||
│ 标题提示词 │
|
||
│ 模板[▼] [新建] [保存模板] [模板操作▼] │
|
||
│ [标题提示词输入框，较旧版增高] │
|
||
│ [插入旧标题] [保存标题提示词] │
|
||
│ 封面提示词 │
|
||
│ 模板[▼] [新建] [保存模板] [模板操作▼] │
|
||
│ [封面提示词输入框] [插入标题] [预览] │
|
||
│ 右侧任务区：批次/店铺/商品ID/状态筛选 + 任务表 + AI生成运行日志 │
|
||
│ 生成内容[只生成标题▼] 标题30/30 ━━━━━ 生标题用时 18 秒 [▶ 开始生成][■停止][重置生成结果] │
|
||
│ 图片0/0 ━━━━━ 生图用时 0 秒 │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 左侧（提示词管理，上下两块）：
|
||
- **标题提示词**：模板下拉（读 `data/prompts/title/*.txt`）+「新建 / 保存模板 / 模板操作（另存为、重命名、删除）」+ 多行输入 + 下方工具条「插入旧标题」（插 `{旧标题}`）/「保存标题提示词」（写 `data/title_prompt.txt`）。启动时自动加载 `title_prompt.txt` 回显，不自动用模板覆盖工作文本；用户选择模板时才把模板内容载入输入框。若标题提示词包含 `{旧标题}`，生成前替换为当前任务旧标题且不重复追加旧标题块；不包含时保持旧行为自动追加旧标题。
|
||
- **封面提示词**：模板控件压缩到一行（读 `data/prompts/cover/*.txt`，新建/保存模板/另存为/重命名/删除）+ 多行输入 + 下方工具条「插入标题」（插 `{新标题}`）/「预览」（变量替换后查看）。
|
||
- 变量：标题提示词本阶段只支持 `{旧标题}`；封面提示词支持 `{旧标题}`/`{新标题}`/`{商品id}`/`{店铺}`，生成前按任务替换。
|
||
- 右上：按导入批次 / 店铺 / 商品ID / 商品状态 / 生成状态筛选任务；商品状态位于生成状态左侧，选项与①一致，按原始快照区分架上商品、未上架、审核中、状态未知和待检测；新打开②默认「架上商品」。生成状态继续表示待生成、已生成、失败、略过、已更新。商品状态筛选只缩小当前列表，商品ID输入框按包含匹配 `item_id`，清空表示全部；用户主动改选商品状态后，刷新或切换其他筛选条件保留该选择。
|
||
- 筛选行提供「打开图片文件夹」按钮，用于只读打开本地图片目录：选中某行时打开该商品所在账号图片文件夹（优先打开已有新/旧封面文件的真实父目录，缺失时回退到规范账号目录）；未选行且选择具体批次时打开该批次图片文件夹；未选行且为全部批次时打开图片根目录。目录不存在只中文提示，不自动创建目录，不修改任务状态。
|
||
- 右下：任务列表（店铺名、商品id、旧标题、新标题、标题状态、图片状态）+ AI生成运行日志；标题/图片状态由 `new_title`、`new_cover_path`、`stage/status` 和失败步骤推导，帮助用户区分“标题未生成 / 图片未生成 / 标题成功但图片失败”。商品ID列按原等分宽度约 50% 显示；标题状态和图片状态列在 T-554 基础上再缩到约 33%，缩出的宽度平均给旧标题和新标题。已生成、未提交线上、非运行中的任务可双击「新标题」列本地微调，写回 `tasks.new_title`，清空 `last_error` 并回到可更新；双击其他列弹窗展示旧封面、新封面和历史候选图。
|
||
- 底部**单个「开始生成」+「停止」**，并增加「生成内容」下拉：默认只生成标题，可选只生成封面或生成标题和封面；只生成封面不调用生文，有新标题时优先使用，没有时用已采集旧标题作为封面prompt参考，新旧标题都为空才不纳入。开始前先从真实候选重新分组商品状态，弹出与①共用的纵向范围确认框：默认「生成架上商品」（即仅检测结果为正常的商品），「生成全部商品」为警示橙色描边，还会处理未上架、审核中、状态未知商品，可能额外消耗点数；未上架、审核中、状态未知默认不入队、不请求 AI、不消耗点数，用户明确选择全部范围才可入队。商品状态功能上线前的历史空状态会启动时迁移为默认正常；上线后仍为空的记录按未知处理。范围确认不跨轮记忆，取消或候选在确认期间变化均不启动生成；无异常候选时该警示选项禁用。标题/图片两条进度条右侧分别显示同宽用时标签（`生标题用时 N 秒` / `生图用时 N 秒`），运行中每秒递增，完成/停止后冻结；原图片进度条右侧的失败数和 cmhub 余额不再占用该位置。cmhub 模式会把用户设置的图片并发内部限制到最大 5，并用同样最大 5 的独立下载线程池拉取 `image_url`，不新增用户可见下载并发配置；运行日志显示用户设置并发和实际并发。下拉状态持久化到 `config.json` 的 `ai.generate_mode`，并继续写回旧兼容 `ai.generate_cover`。
|
||
- 点击「开始生成」还会先读取主窗口已验证的会员状态。未订阅、到期、Key 无效或状态暂时无法确认时不创建 `GenerateWorker`，引导到⑤设置或线上会员中心；旧服务订阅接口尚未启用时保持原有生成行为。
|
||
- 生成参数（标题/图片并发数、失败重试、分辨率、jpg 质量、cmhub 网关/Key/别名）在 **设置**；②只暴露本轮生成标题/封面/图文的内容模式。设置不新增“下载并发”控件；cmhub 图片下载并发由程序按实际生图并发自动计算，最大 5。
|
||
- 只生成标题时标题成功即写库并进入 `generated`，保留已有封面；只生成封面时通过组件级写库只保存 `new_cover_path`，不覆盖已有标题，也不把旧标题写入空的 `new_title`；生成标题和封面时按缺失组件增量补齐。“有新封面、无新标题”时标题状态为待生成、图片状态为已生成，后续补标题不重复生图。三种模式都写 `run_type=generate` 的 `run_logs/run_log_events` 和用户可读滚动日志；日志开头明确显示本轮生成内容。点击「开始生成」时先清空②界面可见日志并写入本轮开始摘要，运行中只追加本轮日志；不删除历史 `run_logs/run_log_events` 或本地 `data/logs/`。进入页面默认可显示“本轮日志会在开始运行后显示”，历史日志不自动混入当前运行界面。「停止」取消未开始项，可再次「开始生成」对剩余继续。即使用户通过商品状态筛选查看异常商品，也必须在范围确认框主动选择「生成全部商品」才会入队；默认「生成架上商品」不会因筛选而放宽。
|
||
- 「重置生成结果」支持选中任务或当前筛选结果，运行中禁用；确认框提供「重置标题 / 重置封面 / 重置全部」，只改本地 DB，默认不删除本地新封面文件。若范围内包含已提交线上记录，必须提示本地重置不回滚蝦皮，重生成后再更新会再次提交线上。
|
||
- ②任务表右键仅作用于鼠标命中的单条记录，提供「删除本条记录」。确认后调用任务级软删除：记录立即从①②③的列表、筛选和后续采集/生成/更新/回写范围排除；不删除原 Excel、本地图片、账号 Chrome 或蝦皮线上商品。生成中或任务运行中禁用该入口；已提交线上记录的确认框明确提示不回滚线上。
|
||
- **无逐条人工审核环节**；新标题默认使用 AI 输出，但允许对已生成且未提交线上的单行做本地微调。封面画廊内「重置图片」只清当前任务 `new_cover_path` 并归档旧图，不启动单条生图；用户翻看完后用状态筛选「待生成」并点击「开始生成」批量补封面。生成完即可进入 ③，③ 开始更新前会做批量确认。
|
||
|
||
## ③ 更新蝦皮
|
||
|
||
```
|
||
┌ 更新蝦皮 ───────────────────────────────────────────────────┐
|
||
│ 批次[本次▼] 店铺[全部▼] 商品ID[____] 状态[已生成▼] [筛选] │
|
||
│ ⚠ 点击「开始更新」后先校验更新内容，再确认【当前筛选结果】并提交 │
|
||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||
│ │ 店铺 商品ID 新标题 新封面 阶段 结果 │ │
|
||
│ └───────────────────────────────────────────────────────────┘ │
|
||
│ 运行日志：检查/真实更新逐条留痕 │
|
||
│ 更新内容[只更新标题▼] [检查本轮更新] [▶ 开始更新] [■停止] [回写结果到 Excel] │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 顶部**按批次 / 店铺 / 商品ID / 商品状态 / 更新状态筛选**（与①②一致）；商品状态位于更新状态左侧，选项与①一致，按原始快照区分架上商品、未上架、审核中、状态未知和待检测；新打开③默认「架上商品」，用户主动改选后刷新或切换其他筛选条件保留该选择。更新状态继续表示已生成、失败、已更新、略过和全部状态。商品ID输入框按包含匹配 `item_id`，清空表示全部；「开始更新」作用于**当前筛选结果**，是一道范围控制。
|
||
- 店铺筛选：建议**逐店铺更新**（每店铺需先启动其 Chrome 并登录）。
|
||
- 状态筛选：`已生成` 只跑未更新的；`失败` 用于**失败重试**；`已更新成功/略过` 仅查看。
|
||
- 「更新内容」下拉支持只更新标题、只更新封面、更新标题和封面；点击「检查本轮更新」或「开始更新」前统一用状态优先的预检计划：仅 `product_status=normal` 可进入标题/封面完整性检查，`unlisted`、`reviewing`、`unknown` 及上线后历史 NULL 一律排除，不传给 `ApplyWorker`。商品状态功能上线前的活动历史批次空状态已在数据库初始化时默认迁移为 `normal`，可进入既有内容完整性检查；该默认值会标注为未实时检测，但不要求用户额外打开商品页。状态异常和缺失内容记录都在确认框、状态栏和本轮日志列出分类、数量与示例商品ID；全部被排除时按真实原因中文弹窗阻断，不打开 Chrome、不改任务状态。用户确认后重新计算计划指纹，任务状态、更新时间、新标题或新封面变化则中止并要求重新开始。
|
||
- 「检查本轮更新」只读取当前筛选结果并写运行日志，不打开 Shopee、不提交、不改任务状态；弹窗/日志展示总任务数、店铺分布、当前商品状态/更新状态筛选、当前更新内容、会更新标题/封面、略过原因、每批最大条数和预计批次数。
|
||
- 完成缺失内容预检并剔除不合格记录后，点击「开始更新」读取设置中的 `shopee_update` 执行设置：普通正式更新不再以测试商品 ID 或旧真实提交开关限制当前筛选结果，允许当前筛选结果包含多个真实商品 ID；`max_items_per_run` 作为**每批最大更新条数**，当前可执行任务超过该值时不阻断，而是自动分批执行。
|
||
- 弹窗展示本次筛选条件、更新内容、任务总数、每批最大条数、预计批次数、执行设置和“将提交线上”的风险提示；用户点「是/确认」才开始，点「否/取消」不执行。
|
||
- 真实更新第一条商品前做账号就绪预检：按当前筛选结果汇总需要的账号；无账号、Chrome 未启动、CDP 端口不可访问、未登录或端口冲突时，弹窗列出具体账号/原因并中止本轮，不自动调用「启动登录」或静默打开 Chrome。
|
||
- 对确认后的**已生成（generated）任务**按当前更新内容执行：打开编辑页换标题和/或换封面 → 点页面「更新」 → 如 Shopee 弹出“確定您要更新商品嗎?”确认框（`.eds-modal__content` / `.eds-modal__box`），则只点弹窗主按钮「更新」提交，不点「立即優化」。
|
||
- ③每条更新任务都会把对应 Chrome 的当前商品 tab 切到前台；新建 tab 不使用后台创建，复用 tab 时也显式激活。上传封面、等待图片管理器刷新、拖到第一位和提交线上均以稳定性优先，因此批量更新期间 Chrome 会随任务切换到前台。后台态封面安全恢复逻辑仅为兼容直接调用保留，正常③批量路径不依赖它。
|
||
- 打开编辑页失败时，如果 Shopee 弹出错误 toast（如商品 ID 不正确、商品不存在、无权限），③运行日志和任务失败原因必须显示该 toast 文案；同时把 toast HTML/URL/时间写入本地诊断日志。用户不需要手动复制瞬时 toast 的 HTML。
|
||
|
||
- 更新封面时统一按替换第一张执行：删除第一张前必须已有该任务的本地旧封面备份（①采集得到的 `old_cover_path` 且文件存在）；备份缺失时阻断该条更新并提示先采集/修复备份，不盲删线上图片。
|
||
- 默认串行、单条失败继续；设置中的「同时更新蝦皮账号」设为 1 时逐个账号执行，设为 2..5 时不同账号同时执行，同一账号内仍串行；真实更新前若本轮账号调试端口冲突则阻断。
|
||
- 「检查本轮更新」只写运行日志与检查汇总，不打开 Shopee、不调用 `editor.apply_task()`、不写任务状态、不回写 Excel。
|
||
- 真实更新每条立即写回 SQLite（committed/状态/error），失败不阻塞后续任务；检查和真实更新都会写 `run_logs/run_log_events`。点击「检查本轮更新」或「开始更新」时先清空③界面可见日志并写入本轮检查/更新开始摘要，运行中只追加本轮日志；不删除历史 `run_logs/run_log_events` 或本地 `data/logs/`，历史日志不自动混入当前运行界面。
|
||
- 分批更新时「停止」为协作式停止：已开始的当前商品跑到安全边界并写库后停止，不再开始新商品、不进入下一批；未开始任务保持原状态，下次可继续。
|
||
- 更新前做账号就绪预检：无账号、对应账号 Chrome 未启动、CDP 端口不可访问或未登录时整体阻断并引导去账号管理，不进入逐条提交，也不自动打开账号 Chrome。
|
||
- 若设置中开启“成功后关闭本次新开编辑页”，则仅关闭本轮程序自动新开且成功提交的商品页；确认后跳回我的商品列表页时，关闭前等待 2 秒；已进入编辑页后的失败任务和用户原本打开的 tab 不关闭。但如果失败发生在 `open_product()` 内部，程序自动新开的无效商品页 tab 要关闭，避免 Chrome 残留空错误页。
|
||
- 「开始更新」是③的主操作按钮，视觉上必须强于其他批处理按钮。
|
||
- 「重置更新状态」从底部批处理按钮移到任务表右键菜单/高级入口，仅作用当前选中单条，运行中禁用；保留 `new_title/new_cover_path`，只把本地状态退回可更新，用于重复测试上传/提交。若 `committed=1`，确认框必须提示线上已提交过、本地重置不回滚蝦皮、重复更新会再次提交；不得静默清除 committed 历史事实。
|
||
- ③任务表右键保留「重置更新状态」，并以分隔线增加「删除本条记录」。删除只对鼠标命中的一条本地记录生效，复用任务级软删除；更新或结果回写运行中禁用。确认内容须说明商品、店铺、批次及不删除 Excel、图片、账号 Chrome 和蝦皮线上商品；已提交线上记录额外提示本地删除不回滚线上。
|
||
- ③任务表**左键双击**某行可人工查看该商品：在对应账号 Chrome 中，已存在同商品详情页时只切到前台，不刷新、不重新导航；没有才新建一个前台详情页并等待就绪。右键双击不触发此行为。账号不存在、Chrome/CDP 未启动、未登录或页面失败只在状态栏显示中文引导前往④账号管理，不自动启动 Chrome 或登录；查看不会读写任务、Excel、图片、AI 或线上商品。新建页失败只关闭本轮新建 tab，成功页和用户既有页都保留。
|
||
- 更新完成后自动回写原 Excel：写入新标题、新封面图片路径、更新状态；原文件被锁时提示关闭后点击「回写结果到 Excel」手动重试。
|
||
- 自动回写完成后弹窗汇总成功/失败/略过数量与 Excel 回写文件/行数。
|
||
|
||
## 账号管理
|
||
|
||
```
|
||
┌ 账号管理 ─────────────────────────────────────────────────────┐
|
||
│ 账号名 别名 地区 端口 登录状态 备注 │
|
||
│ 主店A 女装店 seller.shopee.tw 9222 ●已登录 │
|
||
│ [＋新增][✎编辑][🗑删除] [▶启动并登录][🔄检测登录][⧉快捷方式] │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
账号弹窗字段：账号名、别名（唯一，Excel 用它匹配）、地区域名、调试端口、密码（本地明文仅参考，保存/变更时提示，UI 打码，不自动登录）、备注；配置目录按别名生成 slug 只读显示。
|
||
|
||
## 设置
|
||
|
||
- 设置页整体布局：内容区居中，左右留白已从 T-506 初始实现缩短到约 40%；实现上用最大内容宽度 + 自适应 margin，而不是写死窗口像素。所有设置组默认响应式 3 列表单：短字段占 1 格，URL/API Key/路径等长字段跨 2 格或 3 格；窄窗口自动降为 2 列/1 列。点击「保存设置」成功后，状态栏显示“设置已保存”，并弹出轻量提示框。T-531 已完成：保存成功会清除未保存标记；保存失败时保留未保存标记并阻止离开。设置页所有数字微调框禁用滚轮改值，滚动输入交给外层设置页，仍可通过箭头、键盘和直接输入修改。
|
||
- 生成网关（T-677/T-680/T-684）：在原「AI 模型配置」标题下使用同行标准单选框「默认网关 / 自定义网关（仅支持 OpenAI 格式）」替代历史「AI 后端」下拉和不明显的分段按钮；选中自定义网关时，在其下显示“只有服务商明确说明‘支持 OpenAI 格式接口’时才选择此项。”，并提供同义 tooltip。启动/放弃未保存更改时按已保存的 `ai.backend=cmhub/direct` 自动勾选对应项，圆点与焦点状态表达当前选择。切换只改变待保存状态并立即切换原有面板，点击「保存设置」才写入配置；默认网关的 `data/config/cmhub.json` 与自定义模型的 `data/config/ai_models.json` 始终并存，模型新增、保存、删除仍立即写盘，不受来源待保存语义影响。除这两个选择控件外，不改变设置页其它组件、表单布局或业务逻辑。
|
||
- 默认网关面板展示 Base URL、API Key、生文/生图/图片理解别名、连接超时、批量生成前检查余额、刷新别名和测试连接/查余额；Base URL 输入框旁提示“只填网关根，如 https://host”，保存/刷新前规整掉 `/api`、`/api/v1` 或其它路径。测试连接成功优先显示 `账号「<账号名>」连接默认网关成功`，邮箱脱敏；没有账号信息时显示「默认网关连接成功」。Key 只本地明文保存、UI 打码显示，不进入日志或导出。
|
||
- 自定义网关复用既有模型列表、其下紧凑显示的模型配置字段、默认文本模型与默认图像模型；不再显示重复的“模型详情”标题，模型选择区到配置表单保留 8px 间距。文本模型保留 `chat` / `auto`；图片模型固定使用「OpenAI 图片编辑接口」（`images_edits`），②和⑥通过 `/v1/images/edits` 以有序重复 `image[]` 上传，第一张是商品主体图、每次只请求 `n=1` 输出。历史 `chat` / `auto` 图片模型不会被改写或隐藏，但会标示「图片接口不支持」，生成前会被拦截。图片响应只接受 `data[].b64_json` / `data[].url`，不适配聊天响应或服务商私有结构。说明行明确「图片理解仅支持默认网关」。
|
||
- 图片模型按钮显示「检查图片配置」，只在本地检查接口类型、URL、模型 ID、密钥和超时，绝不对 `/images/edits` 发送无图片的测试请求；实际可用性必须以②或后续⑥的正常生成确认判断。允许保存不完整配置。②点击生成后、自定义 worker 创建前按本轮标题/封面选择校验所需模型的启用状态、类别、地址、模型 ID、API Key 和接口类型，失败提示去⑤补齐且不发请求、不改任务状态；自定义网关不显示默认网关余额，运行日志和状态栏说明“不计点数，费用由服务商收取”。
|
||
- T-679b 后，⑥商品套图在自定义网关下先本地校验已启用的图片模型、接口类型、网址、模型 ID、密钥与连接超时；不合格时阻止创建 job 并引导到⑤补齐。合格后可创建同步直连 job，确认框显示数量、主图/参考图、逐图模式、比例映射与“自定义网关不计点数，实际费用以服务商为准”，并说明首图为主要商品参考、主体一致性可能弱于默认网关；不请求 cmhub 模型目录、余额或价格。AI帮写仍禁用并说明仅默认网关可用。已有 `generation_source=cmhub`、`provider=cmhub` 且 `task_id` 非空的可恢复任务仍显示「继续查询已提交图片」，仅轮询、下载和保存，不新建 job 或重复扣点。所有②/⑥ worker 开始时冻结来源、实际模型和密钥的仅内存快照，保存设置不会改变正在执行的一轮。
|
||
- T-679c 后，「继续查询已提交图片」只显示并处理 `generation_source=cmhub`、`provider=cmhub` 且 `task_id` 非空的任务，切换到自定义网关后仍可继续查询旧默认网关任务；direct job 永不进入该入口。结果卡、项目历史和全局历史固定显示 job 已保存的“默认网关 / 自定义网关”，不因⑤设置切换改写；同轮混合来源显示“默认网关、自定义网关”。direct 失败只能手动“重新生成”，并再次显示完整生成确认及“服务商可能已对上次未确认请求计费，本次可能再次收费”的默认取消警告。确认后新建 job，不自动重试或复用旧 job；默认网关历史、导出、删除撤销和继续查询保持原有行为。
|
||
- T-531 已完成：设置页任意可编辑控件变更都进入未保存状态，保存按钮旁显示“● 未保存更改”；切换到其它 Tab 或关闭窗口时弹出保存/放弃/取消。放弃会重新从本地配置文件回填控件，避免未保存的 URL/API Key 留在界面上；程序化回填、保存后重载和刷新别名填充下拉不会误触发未保存状态。
|
||
- 自定义模型清单继续保存于 `data/config/ai_models.json`；在自定义网关面板中可通过「新增 / 重命名 / 删除」维护并立即保存，切换回默认网关不会清除这些配置。重命名会保留模型的连接参数和本地 API Key，并同步迁移 `config.json` 中标题/图片默认模型对旧名称的引用；取消、空名称或重名不会写入。
|
||
- AI 生成参数：标题并发、图片并发、失败重试、分辨率、返回超时等短字段按三列排列；标题/图片并发可选 1..5，失败重试可选 0..10，旧配置超限值会自动夹紧；图片保存质量保留内部默认 90，不在普通 UI 展示。自定义模型角色选择只在自定义网关面板显示。
|
||
- 分辨率为 `512 / 1k / 2k / 4k`，在 cmhub 默认模式下只控制生成图片尺寸；设置中的「返回超时」只读展示当前实际等待口径：标题 600 秒、图片 900 秒，不再随分辨率切换显示 180/240/360/600，避免用户误解生图等待时间。
|
||
- 保存写入 `config.json` 的 `ai` 段，供 ② AI生成复用；标题/图片模型角色下拉随 direct UI 一起隐藏。
|
||
- 路径与端口（T-501b/T-506/T-539/T-580 已接入）：组件组改为 3 个组件一组；普通设置页只显示 Chrome 路径、默认端口、端口起止、Chrome 就绪超时。T-538 后账号数据根目录、图片目录、DB 路径固定解析到 `data/` 下，普通 UI 不再提供输入框，避免用户误改后数据分裂；`config.json` 中 `user_data_root` / `image_dir` / `db_path` 字段继续作为内部兼容字段保留，手工配置值仍会被读取和保存。
|
||
- 蝦皮更新执行（T-580 已接入）：组件组改为 3 个组件一组；普通设置页只保留「每批最大更新条数」和「同时更新蝦皮账号(1..5)」两个执行参数。`1` 表示逐个账号串行，`2..5` 表示按账号分组并行；“dry-run”不作为用户可见开关，改到③成为「检查本轮更新」按钮；测试商品 ID 和旧封面开关仅作为历史/调试兼容字段读取，普通设置页无入口，保存后不再写回。
|
||
- ③「更新内容」默认只更新标题，每批最大更新条数默认 1，同时更新蝦皮账号默认 1。
|
||
- ③ 点击「开始更新」和「检查本轮更新」会先排除非正常商品状态，再按「更新内容」剔除缺失内容记录并在确认框说明；仅无可执行记录时中止。①的“采集所有状态”和②的“生成所有状态”不构成③线上更新授权。
|
||
|
||
## 商品套图
|
||
|
||
```
|
||
┌ 套图任务1 │ 套图任务2 │ + ───────────────────────────────────┐
|
||
│ [历史生成][添加图片] 账号[▼] 商品ID[____][拉取主图] │
|
||
├ 左侧配置（滚动）────────────┬ 右侧生成结果 ─────────────────────┤
|
||
│ 商品原图 N/16 已选N张[全选][反选]│ 共N张·成功M张 │
|
||
│ 主图/参考图按宽度换行自然展开 │ │
|
||
│ 平台 站点 语言 比例（同行） │ [结果卡][结果卡][失败卡·重试] │
|
||
│ 每张上传图分别作为主图生成 │ │
|
||
│ 商品卖点与要求 [AI帮写/取消] │ │
|
||
│ 白底图/场景图/模特图/细节图/卖点图 │ 进度条 套图X/Y（秒）·失败N │
|
||
│ [生成套图(N) ⇄ 停止生成] │ │
|
||
└─────────────────────────────┴──────────────────────────────────┘
|
||
```
|
||
|
||
- 每个顶部任务标签持有独立账号、商品ID、设置、原图、当前 job 集合和 worker；任务可并行生成。切换任务不停止后台操作；关闭运行中任务先确认并协作式取消，线程引用保留到真正结束，避免 `QThread: Destroyed while thread is still running`。
|
||
- 二级套图任务标签使用独立紧凑样式，不继承主模块 Tab 的大尺寸点击区。上下文栏左侧集中「历史生成 / 添加图片」，右侧集中账号、商品 ID 和拉取入口；常见 11～13 位商品 ID 不得裁切，长账号可通过 tooltip 查看完整名称。内部生成目录不提供顶部直达入口，正式取图统一通过历史窗口的「导出本轮」选择外部目录。
|
||
- 项目仍以 `账号别名 + 商品ID` 唯一，复用 `image_studio_projects/assets/jobs`。商品ID输入框只接受数字；提交时清除不可见格式字符，失焦、拉取、添加原图和生成共用提交校验。非数字输入只提示并保留在输入框，不覆盖当前已绑定项目；合法切换商品继续弹窗确认。`suite_settings_json` 保存平台、国家地区、语言、比例、逐图主图模式和分类数量；卖点文本继续使用 `draft_prompt`，用户停止输入约 500ms 后自动保存，切换任务、关闭任务或程序前同步补保存。未创建项目时只保留在当前任务内存，不因输入文字自动创建临时草稿。
|
||
- 「商品卖点与要求」关闭内部横向和纵向滚动条，输入框按完整换行内容自然增高；文本删除后可缩回最低高度，页面过长时统一由左侧 `suiteConfigScroll` 滚动。
|
||
- 商品原图最多16张。前6个槽位固定显示主图与参考1～5；列表关闭内部滚动条，按可用宽度换行并自然向下展开，由左侧配置区统一滚动。支持文件选择、外部拖入、剪贴板粘贴和列表内排序；每张真实图片都是内部拖放的合法放置目标，列表固定以移动方式排序。第1张以「主图」文字、粗体和语义色标识，拖动任意图片到第一位即可设为主图，排序成功提示“已更新商品原图顺序，第一张图片为主图”。未被接受的内部 drop 不回写顺序；外部文件拖入只添加图片。历史失效远程图不占有效名额；第1张是主参考图。
|
||
- 每张真实原图左上角提供独立勾选框，标题行显示「已选 N 张 / 全选 / 反选」；添加占位图不参与选择。勾选只在当前任务界面内临时保留，普通刷新和排序按资产 ID 保留，切换任务或删除成功后清空。右键或 Delete 可批量移除，确认框说明准确数量、主图变化及非破坏性边界；生成中或勾选项仍在下载时整批阻断。删除会继续保护终选直接引用、运行中和可继续查询/重试 job 的主图及参考图；已成功且不可重试的历史 job 不阻断删除，删除后可按剩余原图开始新一轮生成。移除只删除当前项目的本地资产记录，不删除本地源文件或蝦皮线上图片。
|
||
- 「拉取蝦皮主图」复用只读 CDP，读取 URL 后由最多2个下载 worker 后台落盘；不改标题/封面、不拖拽、不点击更新。拉取、下载期间其余界面和其他任务仍可操作，但商品原图列表仅锁定内部拖拽排序，并用 tooltip 说明“正在拉取蝦皮主图，完成后可调整图片顺序”；文件拖入、预览等非冲突操作不因此整页禁用。
|
||
- 套图按分类配置生成图片，固定分类顺序为白底图、场景图、模特场景图、细节说明图、卖点图，之后是自定义分类；默认数量为白底图1、场景图2、模特场景图0、细节说明图0、卖点图2。新增分类默认数量为0，用户未主动配置时不增加生成任务或点数消耗。自定义分类名称非空、无空格、最多10字且不可重名。逐图主图开启后，白底图只生成一次，其余分类按每张有效原图展开。
|
||
- 套图提示词设置弹窗默认模板首行使用“生成目标：{套图名称},{生成目标}”。五个内置分类使用统一固定目标描述；自定义分类使用“生成自定义分类图片：分类名称。”，实际分类名称必须进入最终提示词。旧模板若仍使用 `{套图名称}` 与 `{补充描述}` 会继续读取和渲染，不静默覆盖用户文件；新模板与旧模板都由同一个 renderer 提供预览和 job prompt。模板变量只在替换前校验，商品卖点与要求、分类名等业务文本允许原样包含 `{}`，不会再次按变量解析；发生其他渲染异常时显示「无法生成商品套图」，不创建 job、worker、价格查询或网关请求。
|
||
- `{参考图规则}` 由实际提交图片数决定：逐图主图开启、或当前只有1张可用图时，使用“参考图规则:当前上传图片是本任务唯一主参考图；保持商品主体、款式、颜色和关键细节准确；不编造用户与参考图均未提供的信息。”；未开启且有2至8张可用图时，第1张为主商品图，第2至N张仅作风格、构图、场景或排版参考，N 为本次实际提交总数。提示词弹窗按当前可用原图数预览，`build_job_specs()` 按冻结的参考图快照渲染；默认模板中的 `{参考图规则}` 独占一行，不额外重复标签或序号。
|
||
- 「每张上传图分别作为主图生成」右侧固定显示可换行 helper：“多款式或多SKU图请勾选；同一商品多角度图不勾选，其余图会作为参考图一同提交。”确认生成框必须说明当前主图/参考图模式和实际参考图数；未开启且上传超过8张时，明确仅提交第1张主图加前7张参考图，以及未参与本轮的剩余数量。
|
||
- 平台、国家地区、语言和比例以四个带独立标签的同行下拉展示，选项只显示真实值；四项都写进每个 job 的完整提示词，比例还透传到 cmhub 生图请求，不是装饰字段。已有项目保存自己的完整设置；未绑定商品的新任务在重启后采用 `config.json` 的最近四项选择。生成仍走 `image_studio_generation.run_jobs()` 的 submit → poll → download 管线。
|
||
- 平台、站点、语言和比例四个生成设置下拉仅在闭合时拦截自身滚轮改值，并把滚动交给 `suiteConfigScroll`；展开时滚轮只浏览候选列表，不静默提交当前值。鼠标点击、方向键、回车和 `Alt+↓` 保持原有显式选择语义；账号、历史筛选和设置页等其它下拉不受影响。
|
||
- 生成按钮按当前总数显示并在运行时切换为「停止生成」；确认停止后显示「正在停止...」，重复点击不再弹确认框。默认网关停止会取消未开始任务、保留已提交任务供继续查询；自定义网关停止同样只取消未开始 job，已发出的同步请求不可强杀，界面明确显示“正在停止，等待当前图片返回后结束”，已收到图片仍会保存成功。生成期间可切换其他任务、查看日志、历史和已完成图片；当前任务的账号、商品ID、原图、提示词、比例、分类和生成设置锁定，避免把运行时修改误认为会影响已冻结 job。每轮生成用独立运行标识隔离旧信号，本轮全部 job 终态或线程结束时都会统一恢复按钮；最终 worker 信号缺失时由数据库终态看门狗兜底，不要求用户重启。T-643 后项目持久化当前生成轮次：常规新轮至少成功一张才替换主结果区，全部失败/取消保留上一当前轮；主结果按稳定槽位显示同轮最新 job，单张重试留在原槽位。旧版无轮次 job 临时显示为“旧版历史记录”，不按时间或图片数量猜测归属。成功图可预览、复制路径、打开目录、重新生成、移入项目废纸篓并撤销，失败卡显示脱敏中文摘要与重试入口。
|
||
- T-648 后，常规「生成套图」在原图、卖点和数量校验通过后、费用确认前，若 SQLite 记录显示当前商品已有成功套图，会出现「已有套图生成记录」确认框：用户可查看仅当前商品的全局历史、继续生成新一轮或取消，默认取消；查看历史和取消都不提交任务，继续仍须通过原费用确认后才创建新轮次。失败图片重试、恢复未完成任务和仅失败/已取消历史不出现该确认。
|
||
- T-646 后「历史生成」打开全局非模态「套图历史生成记录」窗口，默认显示所有未删除商品项目最近创建的生成轮次，主结果区不切换。T-649 将店铺筛选固定为首项「全部店铺」的下拉：当前账号显示「账号名（账号别名）」，已删除但仍有历史项目的账号显示「历史店铺：别名（账号已删除）」，选择值使用 `account_alias` 精确查询；商品 ID 关键字和“仅当前商品”可与其叠加，默认不限制当前任务。每一行就是一次正常生成轮次，单张失败重试仍归入原行。行内固定显示时间、店铺/账号、商品 ID、成功/失败/停止/重试统计、最多5张缩略图及余量 `+N`，当前轮标记“当前”，NULL 轮次标记“旧版历史记录”，临时项目显示“临时草稿”。双击缩略图或整行从对应图片打开该轮所有可用图的自适应原尺寸浏览；“导出本轮”后台复制该轮成功且本地存在的图片到用户选择目录下的新安全子目录，不覆盖或修改内部图片。旧版记录、全失败轮和本地文件缺失项保留中文说明；不提供批量导出、删除、重试、切换当前轮或再次生成。重复点击复用同一窗口；关闭任务页不关闭全局窗口，应用退出时正常释放。
|
||
- AI帮写和生图按任务独立运行。AI帮写只使用默认网关设置的「图片理解别名」调用图片理解能力，不走②标题生成；按商品原图 `source_order` 取1至8张已下载的本地图片，在一次请求中作为同商品的多角度/细节/包装/场景证据集联合理解，超过8张时状态提示只使用前8张，原图勾选不改变输入图片。返回一份可直接编辑的商品级卖点与套图画面要求，按商品概述、可确认卖点、人群与场景、套图画面要求、待确认或避免编造的信息组织，不按图1、图2逐图说明；图片有可见差异时明确为待确认项。单图超过10MiB、总计超过32MiB、没有可用本地图、别名未配置或服务异常时不改现有卖点；图片理解读超时或网络中断提示“结果未确认，请先查看点数余额或稍后重试”，不自动重发。成功状态显示理解图片张数、扣点和余额；AI帮写期间若用户改过卖点，返回后必须确认才覆盖；全部用户可见错误隐藏图片路径、URL、接口路径、base64、完整提示词和敏感信息。切换到自定义网关后，AI帮写禁用；新建套图可走同步直连图片编辑，已提交默认网关任务仍可继续查询、下载和保存。
|
||
- AI帮写提交图片理解前先显示「开始AI帮写」确认框：按 `source_order` 说明会理解当前商品前1至8张可用原图并生成商品卖点与要求。模型目录只走后台读取或进程内短期缓存；仅当前图片理解别名有唯一无条件价格时显示「预计扣点：X 点」，否则明确实际以网关返回为准。确认框默认、Esc 和关闭均取消，不提交图片；开始后可取消本地等待，但已提交网关的请求仍可能产生扣点。预估不写入业务数据，完成后仍只显示接口返回的实际扣点和余额。
|
||
- 常规「生成套图」保留“已有成功历史”优先确认，选择继续后才后台读取或复用同一模型目录缓存，并显示正式生成确认。确认严格按最终 planned `specs` 展示各分类实际张数、总张数和比例；逐图主图开启时明确白底图只用第一张原图，其他分类按每张原图生成；关闭时所有分类使用第1张主图及同一批冻结参考图。仅唯一无条件的生图价格显示预计单张和总扣点，总价只按 `len(specs)` 计算；价格未知时不显示数字。默认、Esc、关闭、切换任务、取消读取或计划变化均不创建生图 job；单图失败重试和恢复未完成任务不增加这一层批量确认。
|
||
- 商品套图只管理本地图片资产，不自动上传或修改蝦皮；③线上更新边界不受影响。旧 `ImageStudioTab` 留作代码兼容但不再作为主窗口入口。
|
||
- 「AI帮写」和「生成套图」在新提交前共用主窗口会员预检；默认网关或自定义网关直连都一样。继续查询已提交默认网关任务、下载、预览、历史查看和导出不属于新提交，不因会员状态变化中断。
|
||
|
||
## 流程导航
|
||
|
||
```text
|
||
账号管理：配账号 + 启动登录（首次必做；重复点击应复用已打开 Chrome）
|
||
│
|
||
① 导入采集：导入 Excel → 采集旧标题/旧封面 → 自动回写旧字段（失败可手动重试）
|
||
│
|
||
② AI生成：提示词 → 选择生成标题/封面/图文（无逐条审核）
|
||
│
|
||
设置：配置每批最大更新条数和蝦皮更新执行模式
|
||
│
|
||
③ 更新蝦皮：选择更新标题/封面/图文 → 对已生成任务点击开始更新 → 缺失内容校验 → 弹窗确认 → 账号就绪预检（未启动/未登录则中止） → 按模式换标题/封面 → 点「更新」提交 → 回写结果 → 弹窗汇总
|
||
```
|
||
|
||
- 未配账号 / 未登录：① 会自动确保匹配账号 Chrome 就绪但不自动登录，未登录账号略过并提示去账号管理；③ 更新前仍只检测账号 Chrome/CDP/登录态，未启动或未登录则中止，不静默启动缺失账号 Chrome。
|
||
- 已生成的任务即可进 ③；③ 经用户确认批量弹窗后提交线上，无常驻提交开关。
|
||
- 任意步骤失败：记入该任务、日志标明，不影响其他任务。
|
||
|
||
## 组件建议（PySide6）
|
||
|
||
| 组件 | 归属 | 说明 |
|
||
| --- | --- | --- |
|
||
| `MainWindow(QMainWindow)` | 根窗口 | 持有 `QTabWidget`、状态栏、顶部会员状态、订阅受限恢复入口和全局消息 |
|
||
| `CollectTab(QWidget)` | ① | 导入、任务表、采集、回写 |
|
||
| `GenerateTab(QWidget)` | ② | 左提示词管理 + 右筛选/任务列表；双击看新旧封面；先确认商品状态生成范围，再按本轮「生成内容」下拉接入 `GenerateWorker` |
|
||
| `ApplyTab(QWidget)` | ③ | 已生成任务筛选 +「更新内容」下拉 + 商品状态优先/内容完整性预检剔除 +「检查本轮更新」+ 分批开始更新确认 + 检查/真实更新运行日志 + 结果回写与结束汇总 |
|
||
| `AccountsTab(QWidget)` | 账号管理 | 账号增删改、启动登录、检测登录、生成快捷方式；首次启动复用初始卖家中心页，启动中防重复触发，登录检测把 Shopee accounts 登录页判为未登录 |
|
||
| `SettingsTab(QWidget)` | 设置 | cmhub 网关配置 + 响应式三列设置表单 + 生成参数 + Chrome/端口配置 + 蝦皮更新执行；数据路径字段隐藏但保留配置兼容 |
|
||
| `ProductSuiteTab(QWidget)` | 商品套图 | 商品套图多任务、账号+商品ID上下文、原图导入/排序、套图分类、默认网关异步或自定义网关同步生成、AI帮写、结果历史与删除撤销 |
|
||
| `TaskTableModel(QAbstractTableModel)` | ①②③ | 任务表格数据模型，供 `QTableView` 使用 |
|
||
| `BaseWorker(QObject)` | 后台 | 定义 `progress/log/row_updated/failed/finished/cancelled` signals |
|
||
| `ApplyWorker(BaseWorker)` | ③ | 账号就绪预检、检查本轮更新、按每批最大条数分批、按账号并行或串行调用 `editor.apply_task(...)`、逐条 `set_applied()`，失败继续，写运行日志；执行层再次拒绝非正常商品状态 |
|
||
| `AIModelTestWorker(BaseWorker)` | 设置 | 后台调用 `appconfig.test_ai_model()` 测试模型连接 |
|
||
| `SubscriptionCheckWorker(BaseWorker)` | 根窗口 | 后台查询 cmhub 账号订阅状态；结果只通过 signal 回主线程更新会员标签和工作流可用性 |
|
||
| `WriteBackWorker(BaseWorker)` | ①③ | ①回写旧字段；③回写新标题/新封面/更新状态 |
|
||
| `ImageStudioPullImagesWorker / ImageStudioDownloadOriginalWorker / ProductSuiteImportImagesWorker / ProductSuiteGenerateWorker / ProductSuiteAiWriteWorker / CMHubModelCatalogWorker` | 商品套图 | 后台执行只读拉主图、远程原图下载、本地图片校验复制、默认网关异步或自定义网关同步套图生成、AI帮写和只读模型目录；拉图和本轮下载支持安全边界协作停止，worker 不直接操作 QWidget |
|
||
|
||
> 采集、生成、更新都是耗时操作，使用 `QObject` worker + `QThread`。Worker 不直接操作 QWidget，只通过 signal 通知主线程刷新 UI。
|