cmbot/docs/07-ui-design.md

UI 设计文档

1. 文档定位

本文档基于 docs/ui-v1.html 和 docs/ui-v1.png 整理，用于指导 PySide6 桌面界面实现。

本文档定义界面布局、控件区域、视觉风格和交互状态，不定义底层图片合成算法。拖动、缩放、旋转和坐标换算的具体实现，应在图像编辑器设计文档中定义。

2. 设计目标

• 保持 Windows 桌面工具软件风格，清晰、稳定、效率优先。
• 让中间合成预览区成为主要工作区域。
• 让素材选择、参数调整、导出队列同时可见。
• 支持长时间批量操作，减少反复切换窗口。
• 支持衣服图片和印花图片从文件夹及子文件夹批量导入。
• 支持多种批量合成模式。

3. 整体布局

主窗口采用固定工具型布局：

标题栏
流程页签
主工作区：左侧素材栏 | 中间预览区 | 右侧参数栏
底部合成队列
底部状态栏

参考设计尺寸：

1920 x 1080

推荐布局比例：

左侧素材栏：约 374 px
右侧参数栏：约 318 px
中间预览区：占用剩余宽度
底部合成队列：约 188 px
状态栏：约 26 px

4. 顶部区域

4.1 标题栏

内容：

• 软件图标。
• 软件名称：自动合成印花服饰效果图工具。
• 当前版本号，放在软件名称右侧，例如：v1.0.0。
• 设置入口。
• Windows 窗口按钮。

要求：

• 标题栏高度紧凑。
• 版本号使用低于软件名称的视觉层级，例如浅灰小字。
• 版本号必须常驻显示，便于用户和管理员确认当前运行版本。
• 设置入口放在右侧。
• 不放复杂业务按钮。

4.2 流程页签

当前设计包含三个页签：

• 1 添加印花
• 2 AI 穿搭
• 3 导出上架

第一阶段只实现 添加印花 主流程。

要求：

• 未实现页签可以置灰或隐藏。
• 若保留未实现页签，点击时应提示“暂未开放”，不能进入空白页面。

5. 左侧素材栏

左侧素材栏分为上下两块：

• 衣服图片。
• 印花图片。

5.1 衣服图片面板

控件：

• 打开衣服文件夹 按钮，作为该区域的主操作，使用主色填充按钮（见第 10 节按钮层级）。
• 图片数量说明，例如：含子文件夹 · 共 12。
• 全选复选框。
• 已选数量。
• 排序选择，例如：文件夹+名称。
• 缩略图网格。

缩略图网格采用每行多张、随面板宽度自动换行的卡片布局（非每行一张的列表）。

缩略图卡片显示：

• 图片预览（卡片上方）。
• 勾选框（叠加在缩略图左上角）。
• 文件名（卡片下方，过长时中间省略）。
• 来源子文件夹（鼠标悬停 tooltip 显示，节省网格空间）。
• 当前预览选中态（卡片高亮）。

交互规则：

• 选择文件夹后递归导入该文件夹及所有子文件夹中的支持格式图片。
• 支持全选和取消全选。
• 支持单张勾选和取消勾选。
• 支持点击某张衣服图片作为当前预览底图。
• 勾选状态表示是否参与批量合成。
• 当前预览选中态和批量勾选态需要视觉上可区分。

5.2 印花图片面板

控件和交互与衣服图片面板一致。

差异：

• 按钮文案为 打开印花文件夹。
• 图片项代表印花素材。
• 点击某张印花图片后更新当前预览印花。

6. 中间预览区

中间预览区是主要编辑区域。

6.1 预览顶部栏

显示：

• 当前底图文件名。
• 当前印花文件名。
• 预览操作模式按钮：
  • 移动。
  • 缩放。
  • 旋转。
• 缩放比例控制：
  • 减小。
  • 当前比例，例如 82%。
  • 放大。

要求：

• 预览缩放只影响画布显示比例，不改变真实合成参数。
• 当前底图和当前印花需要清晰显示。

6.2 画布区域

画布显示：

• 灰色棋盘背景。
• 衣服底图。
• 印花图层。
• 印花选中框。
• 缩放控制点。
• 旋转控制点。
• 操作提示条。

印花选中态：

• 选中框使用蓝色线条。
• 四角和边中点显示缩放控制点。
• 顶部显示旋转控制点。
• 印花可以显示轻微旋转状态。

操作提示：

拖动移动
四角 缩放
顶部 旋转
Shift 锁比例

要求：

• 画布区域应尽量大。
• 鼠标交互反馈必须明确。
• 未加载图片时显示空状态提示。
• 加载衣服但未加载印花时，只显示衣服底图。
• 加载衣服和印花后，默认显示可编辑印花图层。

7. 右侧参数栏

右侧参数栏用于模板、位置、尺寸、旋转和输出设置。

位置、尺寸、旋转 三个分区各自在分区标题栏右侧放一个小型 重置 按钮（↺ 图标 + 文字），只把本分区参数还原为当前选中模板的对应值，三者互不影响：

• 位置重置 → 还原为模板的居中位置（X / Y）。
• 尺寸重置 → 还原为模板目标框内适配的大小（宽 / 高）。
• 旋转重置 → 还原为模板角度（通常为 0）。

未选模板或未加载衣服/印花时三个重置按钮置灰。视觉层级见第 10 节「重置类按钮」。

7.1 模板区域

控件：

• 模板下拉框。
• 保存 按钮。
• 另存为 按钮。
• 重置为模板 按钮（把印花参数一次性整体还原为所选模板）。

示例模板：

标准居中印花 · T恤

要求：

• 选择模板后更新当前印花位置、尺寸和旋转。
• 保存用于覆盖当前自定义模板。
• 另存为用于创建新模板。
• 保存 仅对自定义模板有意义：选中内置模板时隐藏该按钮（而非禁用置灰），避免出现长期灰显且无法说明原因的控件。

7.2 位置区域

控件：

• X 坐标 数字输入框。
• Y 坐标 数字输入框。
• 分区标题右侧的 重置 按钮（还原 X / Y 为模板值）。

要求：

• 单位为衣服底图原始像素。
• 用户输入后实时或确认后更新预览。
• 预览区拖动后同步更新输入框。

7.3 尺寸区域

控件：

• 宽度 数字输入框。
• 高度 数字输入框。
• 锁定宽高比例 复选框。
• 分区标题右侧的 重置 按钮（仅还原宽 / 高为模板值，位置 X / Y 不变）。

要求：

• 单位为像素。
• 默认锁定宽高比例。
• 预览区缩放后同步更新宽度和高度。
• 输入框修改后同步更新预览。

7.4 旋转区域

控件：

• 角度 数字输入框。
• 分区标题右侧的 重置 按钮（还原角度为模板值，即拉直印花）。
• 左旋 90° 按钮。
• 右旋 90° 按钮。

要求：

• 角度单位为度。
• 支持负角度。
• 顶部旋转控制点拖动后同步角度输入框。
• 按钮旋转后同步预览和角度输入框。
• 旋转分区标题的 重置 已覆盖「拉直」需求，不再单独提供 归零 按钮；也不再提供合并的 重置位置 / 尺寸 / 角度 按钮，统一由三个分区各自的独立重置取代。

7.5 输出设置区域

控件：

• 输出目录输入框。
• 浏览目录按钮。
• 输出格式下拉框。
• 输出质量下拉框。

要求：

• 输出目录显示完整或省略路径。
• 格式至少支持 PNG 和 JPG。
• PNG 默认保留透明相关能力；JPG 需要处理背景。
• 质量设置用于 JPG 或需要压缩的输出格式。

7.6 提示信息区域

用于显示当前操作影响范围。

示例：

当前调整将仅作用于队列中选中的「黑T_短袖 × 花卉_001」，并标记为「已微调」，重跑模板时不被覆盖。

要求：

• 提示语需要明确说明当前参数影响的是当前单张、选中队列项还是批量模板。
• 警告和错误信息不能只用颜色表达。

7.7 操作按钮

主要按钮：

• 导出当前单张

要求：

• 导出当前单张 使用主按钮样式。
• 当前缺少衣服图或印花图时，导出按钮应禁用。
• 导出面板只负责输出与导出；模板相关操作（保存 / 另存为 / 重置为模板）统一放在模板区域（7.1），不在导出面板重复设置，避免同一动作出现两次。

8. 底部合成队列

合成队列用于批量任务预览和导出进度。

8.1 队列头部

内容：

• 标题：合成队列。
• 批量模式切换。
• 队列统计。
• 队列操作按钮。

批量模式：

• 多衣服 × 单印花
• 单衣服 × 多印花
• 一一匹配
• 全组合（矩阵）

队列统计示例：

共 60 项 · 完成 12 · 进行 1 · 失败 1 · 待导出 46

操作按钮：

• 重置全部
• 导出选中
• 开始批量导出
• 折叠/展开队列。

8.2 队列表格

列：

• 序号。
• 衣服。
• 印花。
• 来源文件夹。
• 参数。
• 可见度。
• 状态。
• 进度 / 输出文件。

参数状态：

• 模板
• 已微调

任务状态：

• 已完成
• 待导出
• 导出中
• 失败

可见度状态：

• 正常
• 偏低
• 不明显

要求：

• 当前选中的队列行需要高亮。
• 队列应支持按可见度筛选，便于只查看 偏低 或 不明显 组合。
• 不明显 组合应有明确文字标记，不能只依赖颜色。
• 用户可以选择跳过低对比组合，不参与批量导出。
• 导出中显示进度条。
• 失败行显示具体原因。
• 输出文件列显示最终文件名或错误说明。

9. 底部状态栏

显示：

• 当前衣服。
• 当前印花。
• 当前模板。
• 批量导出状态。
• 失败数量。
• 最近日志摘要。

示例：

衣服：白T_圆领.png
印花：花卉_001.png
模板：标准居中印花 · T恤
批量导出中 12/60
1 项失败
已导出 白T_圆领_花卉_001.png

要求：

• 状态栏保持单行。
• 重要失败状态需要明显，但不要遮挡工作区。

10. 视觉规范

整体风格：

• Windows 桌面工具软件。
• 浅色背景。
• 蓝色作为主操作色。
• 边框、分隔线和面板层级清晰。
• 不使用营销式大图、渐变背景或装饰性卡片。

推荐颜色：

窗口背景：#f0f0f0
面板背景：#ffffff
次级面板：#f7f7f7
边框：#d6d6d6
主色：#0067c0 / #0078d4
成功：#107c10
警告：#b87a00
错误：#c42b1c
画布背景：#9a9da3

字体：

Segoe UI
Microsoft YaHei
微软雅黑

字号：

• 普通文本：12 px。
• 重要标签：13 px。
• 辅助说明：11 px。

圆角：

• 控件圆角保持小半径，约 3 px。
• 不使用大圆角卡片。

按钮层级（一套主色，按角色克制使用）：

• 主按钮：主色填充、白字。用于每个区域「推动流程前进」的唯一动作：左侧 打开文件夹、右侧 导出当前单张、底部 开始批量导出。三者分处不同区域，各自是本区域主操作，不互相竞争。
• 次按钮：白底、主色描边与文字。用于有意义但非主线的动作，如 应用为模板、导出区的 重置为模板。
• 辅助按钮：浅灰底、细边框。用于就地微调类动作，如 浏览…、排序、左旋 / 右旋。
• 重置类按钮：最安静的一档（幽灵样式），用于 位置 / 尺寸 / 旋转 三个分区的独立重置。它们会重复出现且属于「纠正/撤销」类动作，不应占用常驻强调色；强调色只在悬停时短暂出现以表达意图。重置可逆，因此不使用红色/警告色。

重置类按钮（分区标题内的 ↺ 重置）：
静止：背景 透明 / #f7f7f7   图标+文字 #8a8a8a   无边框
悬停：背景 #eaf3fc          图标+文字 #0078d4
按下：背景 #d6e8f9
禁用：文字 #c0c0c0          不响应悬停（未选模板或未加载图片时）

避免所有按钮使用同一种灰色样式而丧失层级；同一动作在不同位置应使用一致的文案与层级。

11. PySide6 控件映射

建议映射：

主窗口：QMainWindow 或 QWidget
整体布局：QVBoxLayout + QSplitter / QGridLayout
左侧素材栏：QWidget + QVBoxLayout
缩略图列表：QListWidget / QTableView + 自定义 delegate
中间预览区：QGraphicsView + QGraphicsScene
右侧参数栏：QScrollArea + QFormLayout / QVBoxLayout
数字输入：QSpinBox / QDoubleSpinBox
下拉框：QComboBox
复选框：QCheckBox
队列表格：QTableView
进度条：QProgressBar
状态栏：QStatusBar 或底部 QWidget

要求：

• 预览区必须优先使用 QGraphicsView / QGraphicsScene。
• 批量队列建议使用模型视图结构，避免后续数据多时卡顿。
• 缩略图列表可先用 QListWidget 实现，后续再优化为模型视图。

12. 状态说明

12.1 未加载图片

• 左侧列表为空。
• 中间画布显示空状态提示。
• 参数区禁用。
• 导出按钮禁用。

12.2 已加载衣服但未加载印花

• 画布显示衣服底图。
• 印花相关参数禁用。
• 导出按钮禁用。

12.3 已加载衣服和印花

• 画布显示衣服和印花。
• 印花默认选中。
• 位置、尺寸、旋转参数可编辑。
• 单张导出按钮可用。

12.4 选中队列项

• 队列行高亮。
• 预览区显示该队列项的衣服、印花和参数。
• 若该队列项被手动调整，参数状态显示为 已微调。

12.5 正在批量导出

• 显示总进度和当前任务进度。
• 开始批量导出 按钮应切换为停止或暂停类操作，具体行为后续定义。
• 允许查看队列状态。
• 不应阻塞整个界面。

12.6 导出失败

• 队列对应行显示 失败。
• 输出列显示失败原因。
• 状态栏显示失败数量。
• 日志记录详细异常信息。

13. 与当前设计稿的差异和待确认

当前 ui-v1 设计稿已经覆盖主要工作流，但有以下待确认点：

• 顶部 AI 穿搭 和 导出上架 页签不属于第一阶段范围，应确认是隐藏、置灰还是保留为未来入口。
• 队列中单项微调和模板重跑规则需要在后续需求或交互文档中进一步明确。
• 批量导出期间是否允许继续调整队列项，需要后续定义。
• 低对比组合筛选的入口位置需要在后续 UI 版本中明确，例如放在队列头部或筛选菜单中。