docs: define ui status color guidance

2026-07-04 17:47:36 +08:00
parent c40de68379
commit 8522032b06
3 changed files with 64 additions and 0 deletions
@@ -457,6 +457,34 @@ Shift 锁比例
 画布背景：#9a9da3
 ```

+### 10.1 状态色使用规则
+
+状态色只用于表达状态、风险、错误和完成结果，不作为装饰色使用。普通 label、区域标题、普通按钮、普通输入框、普通下拉框保持黑灰色体系；不能为了“更醒目”而给静态说明文字加颜色。
+
+推荐映射：
+
+```text
+待处理 / 未开始 / 跳过：中性灰 #666666 / #8a8a8a
+等待中 / 生成中 / 导出中 / 停止中：信息蓝 #0078d4
+写入中 / 已完成 / 成功：完成绿 #107c10
+偏低 / 需注意 / 配置风险：警告橙 #b87a00
+失败 / 超时 / 不可用 / 不明显：错误红 #c42b1c
+```
+
+适用组件：
+
+- 异步任务状态文字或状态徽章：标题生成、图片生成、批量导出、停止中、写入中、完成、失败。
+- 表格中的状态列、可见度列、失败原因提示；优先给状态单元格或状态徽章上色，不给整行大面积染色。
+- 低对比 / 可见度结果：`正常` 可用完成绿或默认色，`偏低` 用警告橙，`不明显` 用错误红，且必须保留文字标签。
+- 配置和校验错误：API Key 缺失、模型不可用、输出目录不可写、Excel 路径无效等，用错误红文字提示，并配合明确文案。
+
+限制：
+
+- 颜色不能作为唯一信息来源，必须同时显示明确文字，例如 `失败`、`等待超时`、`不明显`。
+- 不使用闪烁、背景大色块或字号放大来表达普通等待状态；失败/警告也应控制在文字、图标或小徽章范围内。
+- 已经有进度条的区域，颜色只补充最终状态或异常状态，不再额外制造第二套“进度百分比”。
+- 状态色应集中封装为样式或 helper，避免同一个状态在不同面板使用不同色值。
+
 字体：

 ```text
@@ -293,6 +293,17 @@ Excel 行 → `OutfitTask` 列表的转换由 `excel_service` 完成；核心只
 - **右栏（设置 + 运行，~400px）**：生成设置标题与「重试上次失败的行」同排；图片并发数 / 新请求间隔 / 单任务冷却 / 失败重试 / 分辨率 / JPG 质量保持 **3 列 × 2 行**；`AI 模型` 标签与下拉框同排；本次进度 + 统计（完成 / 失败 / 待处理）；开始生成 / 停止生成同排；导出失败清单 / 打开输出目录同排；节省的纵向空间给实时日志（含 §8 心跳行）。
  - **图片 AI 模型下拉过滤**：右栏 `AI 模型` 只用于「开始生成」的人物穿搭图片生成，应在填充下拉时跳过 `name == app_config.title_model` 的模型（即 `self._title_model_name`）。标题模型继续由 §17.3 的配置定名机制使用，不出现在图片模型下拉中，避免用户误选文本模型导致图片生成失败。除这条按名过滤外，暂不引入 `usage` 字段或更复杂的配置结构。

+**状态色应用（遵守 `docs/07` §10.1）**：AI 穿搭页只给状态、风险和结果上色，不给普通 label / 按钮 / 输入框装饰性上色。标题生成等待计时已使用 `等待中=信息蓝`、`写入中/完成=完成绿`、`失败/超时=错误红`（§17.10）。后续若扩展颜色，优先覆盖这些组件：图片生成与批量导出状态（生成中 / 停止中 / 完成 / 失败）、处理明细表「状态」徽章、低对比 / 可见度结果、模型或路径校验错误。普通「标题生成提示词」「AI 模型」「输出」等静态标签保持黑灰色。
+
+状态建议：
+
+```text
+处理明细状态：待处理=灰，生成中=蓝，完成=绿，失败=红，跳过/停止=灰
+图片生成 / 批量导出：生成中/导出中/停止中=蓝，完成=绿，失败/超时=红
+低对比 / 可见度：正常=默认或绿，偏低=橙，不明显=红
+配置校验：API Key 缺失 / 模型不可用 / 路径无效=红色文字 + 明确原因
+```
+
 > **设计取舍：不做"实时单图大预览"。** 这是"开了走人、回头抽查"的批量工具；单图实时预览在并发时会产生"该显示哪一行"的歧义。改为「最近结果缩略图条」——只展示已落地成品，既保留"早发现话术/模型不对、及时停掉改话术"的价值，又因只显示成品而消除并发歧义。

 - 后台用 `QThread` + `Worker(QObject)` + 信号回主线程（与 cmbot 更新检查/导出一致；并发细节见 §8）。
@@ -558,3 +569,4 @@ Excel 行 → `OutfitTask` 列表的转换由 `excel_service` 完成；核心只
 - 这不是模型真实进度条，不能用百分比暗示“已生成多少”。它只表达“已等待多久 / 最长等多久”。
 - 现有右栏本次进度条继续按 Excel 行/写回进度推进；标题 label 右侧计时只覆盖“单次标题请求等待”这段长等待空窗。
 - 只给文字本身上色，不加背景色、不做闪烁、不放大字号，避免在左栏窄空间里形成过强干扰。
+- 其它 AI 穿搭状态色遵守 §10 的「状态色应用」和 `docs/07` §10.1：只给状态、风险、错误、完成结果上色，普通说明文字保持黑灰。