cmshoppe/docs/tasks/T-605.md

---
id: T-605
title: AI工场参考 v3 效果图优化信息架构与界面展示
phase: 7
deps: [T-591, T-592, T-593, T-594, T-604]
status: DONE
created: 2026-07-11
---

## 问题 / 背景

⑥AI工场当前功能已经具备项目、拉取蝦皮原主图、照片池、生成图片、继续查询、终选排序和导出能力，但界面仍偏“工程表格/控件堆叠”：

- 用户需要先理解「打开项目」是什么，再知道后续「拉取主图」「开始生成」「导出终选」之间的关系。
- 项目列表、蝦皮原主图、照片池、生成设置、终选区域之间层级不够清晰，运营用户不容易一眼判断当前正在处理哪个商品、源图是哪张、已选多少张。
- 原主图和照片池目前主要以表格呈现，图片工作台的“看图、选图、拖图、排序”氛围不够明显。
- 生成设置和计费/余额提示没有形成强视觉区块，用户不容易在点击「开始生成」前理解成本和任务数量。
- 底部终选区需要更像“主图 1~9 / 详情图 1~12 的排序盘”，而不是普通列表。

参考设计稿：`docs/ui/tab6-ai-studio-v3.svg`。该 SVG 明确了 AI工场的目标体验：

- 左侧商品轨：快速切换商品项目，突出当前商品。
- 顶部操作条：展示当前账号/商品ID/自动保存状态，提供拉取蝦皮主图、打开项目文件夹。
- 原主图抽屉：展示蝦皮原主图缩略图，说明“单击加入照片池、双击查看大图”。
- 照片池：以图片卡片为中心，显示原图/主图/详情图类型、源图状态、生成中/排队中任务状态。
- 右侧生成设置：源图预览、模板操作、完整提示词、类型/数量/比例、生成来源、预计扣点/余额和操作按钮。
- 底部终选盘：主图/详情图分区、计数、拖拽排序、导出说明与导出按钮。

本任务目标：**从产品经理和 UI 设计师视角，把⑥AI工场调整成更接近 v3 效果图的信息架构和视觉表达，让运营用户不用理解内部表结构，也能按“选商品 → 拉主图 → 入照片池 → 选源图 → 生成 → 拖入终选 → 导出”的顺序工作。**

## 方案

### 1. 整体布局调整为 v3 工作台结构

修改 `app/gui/tabs/image_studio.py`：

- 保持一个页面完成主要工作，不新增独立窗口作为主流程。
- 推荐结构：
  - 左侧：项目/商品轨或更紧凑的项目列表区。
  - 中上：当前商品操作条。
  - 中部：蝦皮原主图 + 照片池。
  - 右侧：生成设置。
  - 底部：终选与排序。
- 允许不完全复刻 SVG 像素，但信息层级、区域名称和用户动线要贴近 `tab6-ai-studio-v3.svg`。
- 页面不做营销化 hero，不加装饰性渐变/orb；保持桌面工具的密度和可扫读性。

### 2. 项目入口文案和状态更清楚

当前「打开项目」对用户语义偏抽象。第一版优化：

- 按实际行为改成更清楚的中文文案，例如「打开/切换商品」或「打开商品项目」。
- 输入区保留账号 + 商品ID，但要在顶部操作条/当前项目标题处明确显示：
  - 当前账号/店铺别名
  - 当前商品ID
  - 项目自动保存状态
- 如果用户未打开项目，主工作区给中文空状态，引导：
  - 选择账号
  - 输入商品ID
  - 点击打开商品项目
- 「拉取主图」文案建议改成「拉取蝦皮主图」，避免用户误以为只是本地刷新。

### 3. 原主图和照片池改为图片优先展示

原主图区域：

- 从纯表格感调整为缩略图横向区或紧凑网格。
- 每张图显示顺序、状态：
  - 远程待下载
  - 已加入照片池
  - 下载失败/缺失
- 明确交互提示：
  - 单击：下载并加入照片池/选择
  - 双击：查看大图

照片池区域：

- 以缩略图卡片为主，弱化表格列。
- 图片卡片展示：
  - 类型徽标：原图 / 主图 / 详情图
  - 当前源图标记
  - 生成任务状态：排队中 / 生成中 / 成功 / 失败 / 已停止
  - 比例提示，如 `1:1`、`3:4`，不推荐比例用 warning 边框提示。
- 保留右键移除、双击预览、拖入终选槽等现有能力。
- 照片池和终选区不要把同一个 UI 卡片嵌套在另一个卡片里；区域可以是面板，图片项才是卡片。

### 4. 生成设置区强化成本和动作确认

右侧生成设置参考 v3：

- 顶部显示当前源图缩略预览，没有源图时显示空状态。
- 模板选择、保存、新建、重命名、删除保持现有能力，但布局更紧凑。
- 提示词输入框下方保留一句中文说明：
  - 程序原样提交完整提示词，不自动拆分。
- 类型/数量/比例使用更容易扫读的控件组合：
  - 类型：主图 / 详情图
  - 数量：数字输入
  - 比例：下拉
- 生成来源保留当前 cmhub 托管模型展示；后续 BYOK/自定义模型未完成前，不暴露未完成入口。
- 开始生成前的展示信息更明确：
  - 当前模型档位/别名
  - 预计扣点或“以返回结果为准”
  - 当前余额
  - 不会失败后静默切换生成来源
- 主按钮文案带数量和类型，例如：
  - `生成 3 张主图`
  - `生成 6 张详情图`

### 5. 底部终选区改成排序盘

终选区域参考 v3：

- 主图和详情图分区展示。
- 主图显示 1~9 个槽位，详情图显示 1~12 个槽位。
- 已选图片显示缩略图，占位槽显示虚线空位。
- 支持现有能力：
  - 从照片池拖入。
  - 同区内拖动排序。
  - 移除终选。
  - 双击查看大图。
- 显示计数：
  - 主图 `5/9`
  - 详情 `3/12`
- 导出区说明：
  - 可以部分导出。
  - 文件名按终选顺序连续。
  - 目标目录存在时沿用现有覆盖/新建时间目录/取消逻辑。

### 6. 视觉和响应式约束

- 控件文案全部中文；平台名统一「蝦皮」。
- 不新增「导入本地图片」按钮，继续遵守已定产品边界。
- 文本不能溢出按钮/卡片/状态标签；窄窗口下优先缩略文案或换行，不互相遮挡。
- 缩略图尺寸要稳定，加载中/失败/空状态不能改变布局尺寸。
- 颜色沿用现有语义色：
  - 主操作：蓝色 primary
  - 成功：绿色
  - 警告/比例不推荐：琥珀色
  - 失败：红色
  - 次要说明：灰色
- 不引入新 UI 框架；继续 PySide6。

## 验收要点

- ⑥AI工场打开后，用户能一眼看到当前商品、当前源图、照片池、生成设置、终选和导出入口。
- 「打开项目」语义变清楚，用户知道它是在打开/切换某个商品的 AI工场项目。
- 点击「拉取蝦皮主图」后，原主图区域以缩略图方式展示结果，不再只是表格字段感。
- 照片池中图片类型、源图状态、任务状态可扫读；生成中/排队中/失败状态有明确视觉区分。
- 未选择源图时，生成区给中文空状态；选择源图后展示源图预览。
- 开始生成按钮能反映当前数量和类型，例如「生成 3 张主图」。
- 底部终选区能明显区分主图和详情图，并显示 `x/9`、`x/12`。
- 终选拖拽、排序、移除、双击预览、导出功能不回归。
- 目标目录存在时，导出弹窗仍提供覆盖软件图片/新建时间目录/取消。
- 不出现英文 UI 文案，不出现 `Shopee/shopee` 平台名裸露给用户。
- 不改 CDP 拉图、生图、续查、导出业务逻辑。

## 测试要求

优先补/更新 GUI 单元测试：

- `tests/test_gui.py`
  - 覆盖 AI工场主界面关键中文文案：当前商品、拉取蝦皮主图、照片池、生成设置、终选与排序、导出入口。
  - 覆盖未打开项目/未选择源图时的中文空状态或阻断提示。
  - 覆盖生成按钮文案会随类型和数量变化。
  - 覆盖已有项目、原图、照片池资产、任务状态、终选数据能渲染到新布局。
  - 覆盖不出现「导入本地图片」按钮。
  - 覆盖拖入终选和导出相关既有测试不回归。

验证命令：

```bash
python -m ruff check app tests main.py
py -3.10 -m compileall app main.py
py -3.10 -m unittest discover -s tests
git diff --check
```

人工验收建议：

- 用一个已有 AI工场项目打开页面，确认视觉结构接近 `docs/ui/tab6-ai-studio-v3.svg`。
- 拉取一个有效商品主图，确认缩略图展示、加入照片池、选源图、生成、终选拖拽、导出都能完成。
- 在 1280×820 附近窗口尺寸下检查文字和控件不重叠。

## 边界（不改什么）

- 不改 `app/image_studio.py` 的 DB schema 和核心业务语义。
- 不改 `app/editor.py`、CDP 读取蝦皮主图、商品详情页打开/关闭规则。
- 不改 cmhub 提交、轮询、下载、续查逻辑。
- 不实现 BYOK/自定义模型新能力；只保留当前生成来源展示。
- 不新增「导入本地图片」入口。
- 不改 ①②③④⑤ 模块。
- 不新增图片编辑算法或自动上传蝦皮能力；AI工场导出后仍由用户手动处理。

## 执行记录

- 2026-07-11：已完成。
- 代码：
  - `app/gui/tabs/image_studio.py`：⑥AI工场改为顶部操作条 + 左侧商品项目 + 中央蝦皮原主图/照片池 + 右侧生成设置 + 底部终选与排序的工作台结构。
  - 顶部入口文案改为「打开商品项目」「拉取蝦皮主图」，并新增当前商品、自动保存状态和未打开项目空状态。
  - 原主图和照片池增加稳定缩略图/占位图、图片类型与任务状态图标、源图高亮，保留单击下载/选源图、双击预览、右键移除和拖入终选能力。
  - 生成设置区新增源图预览、提示词提交说明、生成来源/扣点提示和「不会在失败后静默切换生成来源」说明；开始按钮文案会随类型和数量变化，如「生成 3 张详情图」。
  - 底部终选区改为固定槽位显示：主图 9 个、详情图 12 个；空位只做视觉占位，真实保存顺序仍只来自 SQLite 终选记录。
  - 不改 `app/image_studio.py`、`app/editor.py`、cmhub 生图/续查/导出业务逻辑。
- 测试：
  - `tests/test_gui.py`：更新 AI工场构建测试，覆盖 v3 关键中文文案、顶部状态、拉取蝦皮主图、导出到文件夹、生成按钮动态文案、缩略图图标和不出现「导入本地图片」。
  - `tests/test_gui.py`：更新终选排序测试，覆盖主图 9 槽、详情图 12 槽和空位占位不影响真实终选顺序。
  - `tests/test_gui.py`：更新生成日志测试，覆盖选择源图后源图预览显示。
- 验证：
  - 主工作区定向验证通过：
    - `py -3.10 -m unittest tests.test_gui.GuiTests.test_image_studio_tab_builds_project_pool_and_template_controls tests.test_gui.GuiTests.test_image_studio_final_selection_order_and_guards tests.test_gui.GuiTests.test_image_studio_tab_shows_resume_and_job_billing_status tests.test_gui.GuiTests.test_image_studio_generation_log_uses_cmhub_tier_summary tests.test_gui.GuiTests.test_image_studio_worker_thread_is_kept_until_thread_finished tests.test_gui.GuiTests.test_image_studio_worker_failure_is_handled_once tests.test_gui.GuiTests.test_image_studio_pull_main_images_uses_current_item_input`
    - `python -m ruff check app tests main.py`
    - `py -3.10 -m compileall app main.py`
    - `git diff --check -- app\gui\tabs\image_studio.py tests\test_gui.py docs\tasks\T-605.md`
  - 主工作区全量 `py -3.10 -m unittest discover -s tests` 仍因既有未提交默认提示词改动失败 3 个用例，失败内容为 `papa1` 与乱码 `默认` 文件名不一致，不属于 T-605。
  - 为满足提交前全绿验证，已在临时干净 worktree `D:\chengma\cmshopee-t605-verify` 只应用 T-605 diff 后通过：
    - `python -m ruff check app tests main.py`
    - `py -3.10 -m compileall app main.py`
    - `py -3.10 -m unittest discover -s tests`（378 tests）
    - `git diff --check -- app\gui\tabs\image_studio.py tests\test_gui.py docs\tasks\T-605.md`