cmshoppe/docs/tasks/T-605.md

id, title, phase, deps, status, created

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

问题 / 背景

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

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

参考设计稿：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：

• 主图和详情图分区展示。
• 主图显示 19 个槽位，详情图显示 112 个槽位。
• 已选图片显示缩略图，占位槽显示虚线空位。
• 支持现有能力：
  • 从照片池拖入。
  • 同区内拖动排序。
  • 移除终选。
  • 双击查看大图。
• 显示计数：
  • 主图 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工场主界面关键中文文案：当前商品、拉取蝦皮主图、照片池、生成设置、终选与排序、导出入口。
  • 覆盖未打开项目/未选择源图时的中文空状态或阻断提示。
  • 覆盖生成按钮文案会随类型和数量变化。
  • 覆盖已有项目、原图、照片池资产、任务状态、终选数据能渲染到新布局。
  • 覆盖不出现「导入本地图片」按钮。
  • 覆盖拖入终选和导出相关既有测试不回归。

验证命令：

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