# 界面配色设计（语义色规范）

> 立场：以 UI 设计师视角，为当前灰白 GUI 定义一套**语义色**规范。核心原则是"颜色编码含义、加速判断、降低误操作"，不是装饰。
> 基线：`app/gui.py` 现状——除顶部 Tab 栏（`TAB_STYLE`，GitHub 风浅灰/悬停浅蓝）外，任务状态、校验数字、登录状态、动作按钮均为 Qt 默认灰白。
> 性质：设计规范，不改代码。落地时按文末"实现映射"接入，遵守 `docs/05-coding-rules.md` 验证清单。

## 为什么上色（用户视角）

本工具是**带风险分级的流水线**（①②只读/安全 → ③写 Shopee 线上，高风险）。纯灰白本身不是缺点：中性界面对长时间操作不易疲劳、显得专业。所以目标不是"变好看"，而是让**承载判断的关键信息**用颜色加速识别、并对高风险动作形成潜意识提醒。

**反面**：给大面积表格/面板刷底色、堆品牌色、加渐变，会让密集工具界面变吵、变"玩具感"，是负分。因此本规范只给"承载含义的元素"上色。

## 三条纪律（决定成败）

1. **背景保持中性**：只给状态文字、关键按钮、指示点上色；不给表格行/面板大面积刷底色（失败行可用极浅底色，见下）。
2. **不能只靠颜色**：色盲用户约 8%。状态必须"颜色 + 文字/图标"双编码——现有状态已有中文文字（达标）；③ 高风险按钮第一版不强制图标，避免 Windows/Qt 字体渲染不稳。
3. **一套色板全局复用 + 对比度达标**：绿/红/琥珀/蓝各定唯一值，禁止每处手写不同的红；文字色对白底满足 WCAG AA（对比度 ≥ 4.5）。

## 语义色板（浅色主题）

| 语义 | 名称 | 十六进制 | 用途 | 白底对比 |
| --- | --- | --- | --- | --- |
| 成功 | success | `#1a7f37` | 已更新成功、已登录 | AA ✓ |
| 失败 | danger | `#cf222e` | 失败状态、校验错误数、破坏性按钮文字 | AA ✓ |
| 进行中 | info | `#0969da` | 采集中/生成中/更新中、安全主操作按钮 | AA ✓ |
| 待处理 | pending | `#9a6700` | 待采集/待生成/待更新 | AA ✓ |
| 略过/禁用 | muted | `#6e7781` | 略过、禁用态、次级文字 | AA ✓ |
| 危险动作强调 | warning | `#bc4c00` | ③ 写线上的高风险按钮 | AA ✓ |
| 极浅失败底 | danger-bg | `#ffebe9` | 失败行可选浅底（谨慎用） | 底色 |

> 若将来做深色主题，另出一套等义映射；本规范先服务当前浅色。

## 组件配色映射（按价值排序）

### 1）任务状态列（①②③表格核心）— 最高 ROI

`TaskTableModel` / `GenerateTaskTableModel` / `ApplyTaskTableModel` 的状态/阶段列，按值上前景色：

| 显示 | 语义色 |
| --- | --- |
| 已采集 / 已生成 / 已更新成功 | success `#1a7f37` |
| 失败 | danger `#cf222e` |
| 略过 | muted `#6e7781` |
| 待采集 / 待生成 | pending `#9a6700` |
| 采集中 / 生成中 / 更新中（如有进行态） | info `#0969da` |

- 收益：扫上百行时一眼分辨成功/失败/待办，是全项目颜色投入产出比最高处。
- 可选：失败行整行加 `danger-bg #ffebe9` 极浅底，但仅失败一种、不叠加其他行底色，避免花。

### 2）③ 高风险动作按钮

- `开始更新`（写 Shopee 线上，`objectName=startUpdateButton`，现仅粗体）：改用 **warning `#bc4c00`** 系（暖色描边或填充；图标可后置评估），与②安全流程的 info 蓝主操作明确区分。目的是每次点它都有"这一步动线上"的潜意识提醒。
- `停止`：保持中性或 muted，不与主操作抢视觉。

### 3）校验数字（①导入汇总栏）

- 未匹配数 **> 0** 时用 danger `#cf222e`，并保持当前「未匹配(n)」按钮可点击筛出；= 0 时保持中性。
- 无效行数 **> 0** 时同样用 danger 标红提示，但第一版不承诺在任务表筛出，因为脏行不会入库；若要点击查看，需要后续新增「导入错误明细」。匹配数可用 success 或保持中性。

### 4）登录状态点（④账号管理）

- `● 已登录` = success `#1a7f37`；`● 未登录 / 检测失败` = danger `#cf222e`；`● 未检测 / 已启动 / 检测中` = muted `#6e7781` 或 info `#0969da`。落地时优先在④账号表登录状态单元格显示 `● 状态文本`，并通过 `QTableWidgetItem.setForeground(QColor(...))` 上色，保留文字，不只靠颜色。

### 5）③ Tab 危险区标识（克制）

- 给 ③ 更新shopee 加一个**克制**的暖色标识时，不依赖 QSS 硬选第 3 个 Tab。普通 `QTabBar` stylesheet 没有稳定的 nth-tab 选择器；本轮 T-513 采用 `QTabWidget.setTabIcon(2, ...)` 设置 10-12px warning 小圆点图标，Tab 文案仍保持 `③ 更新shopee`，不改文字色、不整条刷红。目的：让用户始终知道自己在"碰线上"的那个 Tab。

### 6）破坏性按钮（低优先）

- `删除批次`（①）、`删除账号`（④）等不可逆动作：按钮文字和描边用 danger `#cf222e`，与普通灰按钮区分；保持原有启用/禁用和二次确认逻辑不变。二次确认弹窗仍是主防线，颜色只是二级提示。

### 7）状态栏全局提示色（T-543 已落地）

左下角状态栏是低打扰反馈，不应做成醒目的大色块。建议只改变状态栏文字颜色，并在每次显示普通提示时重置样式，避免上一条红色/绿色残留到下一条普通消息。

| 提示类型 | 语义色 | 示例 |
| --- | --- | --- |
| 普通/就绪 | muted `#6e7781` 或系统默认 | `就绪`、`当前：② AI生成` |
| 信息/进行中 | info `#0969da` | `正在生成标题 3/10`、`检测登录中` |
| 成功 | success `#1a7f37` | `设置已保存`、`AI 生成完成`、`已回写 Excel` |
| 警告/需用户处理 | warning `#bc4c00` 或 pending `#9a6700` | `当前筛选结果没有待生成任务`、`请先到①完成旧数据采集`、`请先配置 cmhub` |
| 错误/阻断 | danger `#cf222e` | `更新失败`、`账号未登录`、`点数不足` |

- 状态栏只做辅助反馈，不能替代弹窗、空状态、运行日志和按钮禁用等主反馈。
- 高频进度信息用 info；不会继续执行、但用户可通过配置/选择修复的问题用 warning；已经失败或阻断当前动作的问题用 danger。
- 不建议给所有状态栏消息都上强颜色；普通导航、就绪、筛选数量等信息保持 muted 或默认色，避免长期使用时视觉疲劳。
- T-543 已统一使用 `MainWindow.show_status(message, level)`；新增状态栏提示必须显式传入 `level`，现有旧回调保留轻量兜底分类以兼容测试和旧入口。
- T-543 第一版已覆盖主窗口和 ①②③④⑤ Tab 现有状态栏调用；状态栏只作为辅助反馈，不改变弹窗、空状态、运行日志、任务状态列或按钮禁用的主反馈职责。

## 实现映射（PySide6，落地时参考）

- **状态色**：在各 TableModel 的 `data()` 里响应 `Qt.ForegroundRole`（必要时 `Qt.BackgroundRole`）按内部 `stage/status` 返回 `QColor`；不要按中文显示文案硬匹配，不要在 QSS 里做，表格单元格上色走 model role 最稳。
- **按钮/汇总数字**：用 `objectName` + 集中 QSS。建议把语义色板定义为 `app/gui.py` 顶部的一组常量（如 `COLOR_SUCCESS = "#1a7f37"`），QSS 与 `QColor` 都引用同一常量，杜绝散落硬编码。③ Tab 单独标识如需落地，用 `setTabIcon(2, ...)`，不要试图用 QSS nth 选择器。
- **登录点**：文字前缀 `●` 用 `QColor`，或状态列走 ForegroundRole。
- **状态栏**：T-543 已在 `MainWindow` 增加统一入口 `show_status(message, level="muted")`，内部映射 level 到色板、设置状态栏文字色并调用 `statusBar().showMessage(message)`；普通/就绪提示会重置为 muted，避免上一条 danger/success 残留。现有 `self.statusBar().showMessage(...)` 已收口到该入口；传给 Tab 的 `status_callback` 也改为 `show_status`。第一版为兼容旧测试和旧入口保留轻量关键词兜底分类（失败/错误/异常/点数不足/未登录→danger，完成/成功/已保存/已回写→success，没有/请先/未配置→warning，正在/开始/进度/检测中→info），但新增代码必须显式传 `level`，不要长期依赖中文字符串匹配。
- **复用**：所有红/绿/蓝/琥珀只从色板常量取值，新增组件一律引用，不新造颜色。

## 非目标（明确不做）

- 不做整体换肤 / 品牌主题 / 渐变 / 大面积彩色背景。
- 不给普通只读表格行刷底色（失败行浅底是唯一例外且可选）。
- 不改变顶部 Tab 栏既有的防误点尺寸与灰白基调；③ 风险标识必须克制，且可在第一版跳过。
- 不引入第三方 QSS 主题库；用现有 `TAB_STYLE` + objectName + model role 即可。

## 落地建议顺序

1. 状态列上色（映射 1）——收益最高、风险最低，建议先做。
2. ③ 高风险按钮 + 校验数字标红（映射 2、3）——直接服务防误操作与导入纠错；无效行第一版只标红，不做筛表。
3. 登录点、③ Tab 标识、破坏性按钮（映射 4、5、6）——体验打磨。
4. 状态栏提示色（映射 7）——低风险体验增强，适合在现有语义色稳定后作为小任务落地。

> 每步落任务时补现状/方案/验收，并跑 `python -m unittest discover -s tests`（GUI 逻辑测试）确认无回归。