cmbot/docs/07-ui-design.md

UI 设计文档

1. 文档定位

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

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

2. 设计目标

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

3. 整体布局

主窗口采用固定工具型布局（软件名称与版本号由系统窗口标题栏显示，内容区不再单设标题栏）：

流程页签（左：1/2/3 编号步骤 · 右端：⚙ 配置）
主工作区：左侧素材栏 | 中间预览区 | 右侧参数栏
底部合成队列
底部状态栏

参考设计尺寸：

1920 x 1080

推荐布局比例：

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

4. 顶部区域

4.1 标题栏

直接使用系统（Windows）窗口标题栏显示软件名称与版本号（通过窗口标题设置，例如 自动合成印花服饰效果图工具 v1.0.0），不在内容区另画一条标题栏。

要求：

• 软件名称与版本号通过窗口标题常驻显示，便于用户和管理员确认当前运行版本。
• 不在窗口内容区重复软件名称与版本号——内容区自绘标题栏会与系统标题栏重复，故不设置（除非后续改为无边框窗口、由自绘标题栏取代系统标题栏）。

4.2 流程页签

当前设计包含三个页签：

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

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

要求：

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

4.3 设置入口（更新配置）

在流程页签同一行的最右端放一个低调的 ⚙ 配置 按钮，用 addStretch() 与左侧编号页签隔开，使其读作「工具」而非工作流的第 4 步。

要求：

• 配置 按钮不是编号页签，不参与 1/2/3 顺序；样式低调（图标 + 文字，悬停出强调色）。
• 点击打开设置对话框（QDialog，见 4.4），不进入新的内容页（页签栏当前不切换内容面板）。
• 有新版本提示：启动时后台检查到新版,在 配置 按钮左侧显示一行低调的蓝色提示文字 发现新版本 vX.Y.Z(可点击,点它或点齿轮都进设置)。无更新时该文字隐藏。不用红色(红表示错误/危险,而「有新版」是信息);不弹阻塞横幅(详见 docs/10 §12)。

4.4 设置对话框

集中编辑在线更新配置并触发更新，对应 app_config.json 的 update_source / update_user / update_pass（见 docs/02-prd.md、docs/10-lan-update.md）。

字段与控件：

• 更新地址：update_source 的 HTTP(S) 地址。
• 账号 / 密码：HTTP Basic Auth 凭据；密码框默认掩码，提供「显示」切换。
• 测试连接：用 update_service.load_manifest 实拉一次清单，反馈「已是最新 / 发现新版本 vX.Y.Z / 连接失败」，便于保存前验证。
• 当前版本 + 更新状态：只读显示 APP_VERSION,并提示是否有新版。
• 检查并更新：点击在后台线程 check_for_update → installer.download_and_stage 下载并暂存到 staging\app.new,完成提示「已下载 vX,下次启动生效」。下载期间主界面照常可用,不阻塞;切换由启动器下次启动完成（运行中 app\ 无法替换,见 docs/10 §3/§8）。
• 一行小字安全提示：建议使用只读账号、生产环境走 HTTPS（凭据为明文存储）。

行为与架构：

• 对话框是纯 UI(配置部分)：打开时由 main_window 注入当前配置值；保存时把新值发回主窗口，由主窗口集中 save_config，UI 控件不直接读写配置文件（遵守 docs/05 4.12 与 docs/04 第 6 节）。下载/暂存经 services 层完成（与其它面板调用 service 一致）。
• 保存后主窗口重新触发一次更新检查（提示文字按新配置刷新）。配置写入 ~/.cmbot/config/app_config.json，启动器下次启动自然读到，两端一致。
• 取消不改动配置。

5. 左侧素材栏

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

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

5.1 衣服图片面板

控件：

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

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

缩略图卡片显示：

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

交互规则：

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

5.2 印花图片面板

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

差异：

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

6. 中间预览区

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

6.1 预览顶部栏

显示：

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

要求：

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

6.2 画布区域

画布显示：

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

印花选中态：

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

操作提示：

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

要求：

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

7. 右侧参数栏

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

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

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

参数栏底部另有一个全宽的 位置尺寸旋转重置为当前模板 按钮，一次性把位置、尺寸、旋转整体还原为当前选中模板，作为三个分项重置的「全部」入口。它紧挨它所操作的参数，不放在模板区域。

未选模板或未加载衣服/印花时，三个分项重置与 位置尺寸旋转重置为当前模板 一并置灰。视觉层级见第 10 节「重置类按钮」。

7.1 模板区域

控件：

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

模板区域只管模板本身（选择 / 保存 / 另存为 / 删除）。把印花参数整体还原为模板的 位置尺寸旋转重置为当前模板 属于「调整参数」而非「管理模板」，因此放在参数栏底部（见 7 节开头与 7.4）。

示例模板：

标准居中印花 · T恤

要求：

• 选择模板后更新当前印花位置、尺寸和旋转。
• 保存用于覆盖当前自定义模板。
• 另存为用于创建新模板。
• 保存 与 删除 仅对自定义模板有意义：选中内置模板时隐藏这两个按钮（而非禁用置灰），避免出现长期灰显且无法说明原因的控件。
• 删除 为破坏性操作，点击后必须二次确认（弹「确定删除模板「X」？此操作不可撤销。」），确认后才删除；删除后下拉框回选第一个内置模板。
• 删除 用红色文字提示危险，但保持安静（不使用红色实心块）；删除可逆性低，区别于「重置」类的可逆操作。

7.2 位置区域

控件：

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

要求：

• 单位为衣服底图原始像素。
• X、Y 是一对坐标，放在同一行（标签简化为 X / Y），节省纵向空间。
• 用户输入后实时或确认后更新预览。
• 预览区拖动后同步更新输入框。

7.3 尺寸区域

控件：

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

要求：

• 单位为像素。
• 宽、高是一对，放在同一行（标签简化为 宽 / 高），锁定宽高比例 复选框在其下方。
• 默认锁定宽高比例。
• 预览区缩放后同步更新宽度和高度。
• 输入框修改后同步更新预览。

7.4 旋转区域

控件：

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

要求：

• 角度单位为度。
• 支持负角度。
• 顶部旋转控制点拖动后同步角度输入框。
• 按钮旋转后同步预览和角度输入框。
• 旋转分区标题的 重置 已覆盖「拉直」需求，不再单独提供 归零 按钮。
• 旋转分区下方（参数栏底部）提供 位置尺寸旋转重置为当前模板，把位置 / 尺寸 / 旋转一并还原为所选模板；它和三个分项重置构成「全部 + 分项」两级还原。

7.5 输出设置区域

控件：

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

要求：

• 输出目录显示完整或省略路径。
• 格式至少支持 PNG 和 JPG。
• PNG 默认保留透明相关能力；JPG 需要处理背景。
• 质量设置用于 JPG 或需要压缩的输出格式。
• 格式 与 质量 是一对相关设置，放在同一行；质量 仅在选中 JPG 时可用（PNG 时置灰），并排能体现「先选格式 → 质量才可用」的关系。

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

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

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

分区标题内的 ↺ 重置（幽灵样式）：
静止：背景 透明 / #f7f7f7   图标+文字 #8a8a8a   无边框
悬停：背景 #eaf3fc          图标+文字 #0078d4
按下：背景 #d6e8f9
禁用：文字 #c0c0c0          不响应悬停

底部 位置尺寸旋转重置为当前模板（全宽，安静但有存在感）：
静止：背景 #f0f0f0   文字 #555555   边框 #d6d6d6
悬停：背景 #eaf3fc   文字 #0078d4   边框 #0078d4
禁用：文字 #c0c0c0   背景 #f7f7f7

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

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 版本中明确，例如放在队列头部或筛选菜单中。