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 衣服图片面板

控件：

• 打开衣服文件夹 按钮。
• 图片数量说明，例如：含子文件夹 · 共 12。
• 全选复选框。
• 已选数量。
• 排序选择，例如：文件夹+名称。
• 缩略图网格。

缩略图项显示：

• 图片预览。
• 勾选框。
• 来源子文件夹标签。
• 文件名。
• 当前预览选中态。

交互规则：

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

5.2 印花图片面板

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

差异：

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

6. 中间预览区

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

6.1 预览顶部栏

显示：

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

要求：

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

6.2 画布区域

画布显示：

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

印花选中态：

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

操作提示：

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

要求：

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

7. 右侧参数栏

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

7.1 模板区域

控件：

• 模板下拉框。
• 保存 按钮。
• 另存为 按钮。

示例模板：

标准居中印花 · T恤

要求：

• 选择模板后更新当前印花位置、尺寸和旋转。
• 保存用于覆盖当前自定义模板。
• 另存为用于创建新模板。

7.2 位置区域

控件：

• X 坐标 数字输入框。
• Y 坐标 数字输入框。

要求：

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

7.3 尺寸区域

控件：

• 宽度 数字输入框。
• 高度 数字输入框。
• 锁定宽高比例 复选框。

要求：

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

7.4 旋转区域

控件：

• 角度 数字输入框。
• 左旋 90° 按钮。
• 右旋 90° 按钮。

要求：

• 角度单位为度。
• 支持负角度。
• 顶部旋转控制点拖动后同步角度输入框。
• 按钮旋转后同步预览和角度输入框。

7.5 输出设置区域

控件：

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

要求：

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

7.6 提示信息区域

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

示例：

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

要求：

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

7.7 操作按钮

主要按钮：

• 导出当前单张
• 应用为模板
• 重置为模板

要求：

• 导出当前单张 使用主按钮样式。
• 其他按钮使用次级按钮样式。
• 当前缺少衣服图或印花图时，导出按钮应禁用。

8. 底部合成队列

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

8.1 队列头部

内容：

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

批量模式：

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

PRD 还要求支持：

• 多衣服和多印花一一匹配。

实现时需要在 UI 中补充 一一匹配 模式，或在后续 UI 版本中调整。

队列统计示例：

共 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。
• 不使用大圆角卡片。

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 穿搭 和 导出上架 页签不属于第一阶段范围，应确认是隐藏、置灰还是保留为未来入口。
• 队列中单项微调和模板重跑规则需要在后续需求或交互文档中进一步明确。
• 批量导出期间是否允许继续调整队列项，需要后续定义。