# Dashboard 设计原则（高密度数据可读性优先）

> 本文件回答“为什么这样设计、如何取舍”。具体组件与布局以 `components.index.json` / `LAYOUT_*` / `GLOBAL_DESIGN_RULES.md` 为准。

## 0. 快查索引

- **我想知道 Dashboard 的“主线”怎么构造**：看「§2 决策线：健康度→追因→钻取」
- **我想知道为什么强调面板内滚**：看「§3 对照工作流」
- **我想知道图表为什么要克制**：看「§4 图表底噪原则」
- **关联阅读**：
  - Pattern/范式选型：`PAGE_ARCHETYPES.md`
  - recipe 与滚动决策：`LAYOUT_RECIPES.md` / `LAYOUT_RULES.md`
  - 反例库：`COMMON_FAILURES.md`

## 0. 一句话定位

Dashboard 是高密度“读数 + 对比 + 发现异常 + 追因”的工作台。**可读性与对比效率**高于装饰性美观；图表网格、坐标轴、图例属于底噪，不抢主线。

## 1. 信息优先级

1. 先让用户看到：**核心指标是否健康**（KPI / 关键趋势）
2. 再让用户看到：**为什么变化**（维度拆解/对比/TopN）
3. 最后提供：**钻取与追因**（明细、过滤、对比面板）

## 2. 决策线：健康度 → 追因 → 钻取（生成时必须显式落地）

把“页面要做什么”写成可执行路径（否则容易变成堆组件）：

1. **健康度**：3–6 张核心 KPI（或 1 个核心 KPI + 2–4 次级）  
2. **追因拆解**：1–3 个维度拆解图（分布/TopN/趋势）  
3. **钻取与证据**：TopN/聚类 → 明细表（或评论/原声列表）  

> 这条路径必须与 `PAGE_ARCHETYPES.md` 的 Pattern 目标一致，并由 `LAYOUT_RECIPES.md` 的 recipe 保证“对照不丢失”。

## 2. 图表视觉原则

- 系列色使用 data 色槽 `--color-data-*`，不要用品牌色充当系列色
- 线宽、点大小、网格线强度保持克制
- Tooltip 必须可读，标题 semibold（600），内容 secondary

### 2.1 饼图 / 环图外部标签规则（P0，来自实战）

当 `SmartPieChart` / 环形图需要显示外部标签时，优先保证“完整读数 + 不重叠 + 紧凑靠近图形”，不要让标签按默认最短路径四散摆放。

- **标签是整体块**：百分比 + 类目名必须作为一个标签块统一布局，禁止分别计算位置导致数值和类目分离；小扇区也必须保留百分比，除非业务明确允许只用 tooltip。
- **同侧成列对齐**：左右两侧标签分别形成列，文字 `textAnchor` 同侧一致；同侧标签按 y 轴自动避让，并设置最小垂直间距。
- **引线统一两段式**：从扇区边缘先斜折到列端点，再水平连接到标签列；禁止“先水平再末端小折”、多段乱折或不同标签引线风格混用。
- **整体靠近图形**：标签列应落在环图外侧近距离区域，不要拉到卡片边缘；优先调整 `labelBendOffset` / `labelEndOffset` / `labelBandPadding`，而不是放大卡片或写死绝对坐标。
- **小扇区收纳进标签列**：小占比扇区（如 2%、6%、8%）不要散点摆放；优先进入同侧标签列，必要时通过 `labelSideOverrides` / `balanceLabelSides` 跨侧分配，平衡左右视觉重量。
- **不遗漏数值优先**：有明确分析价值的分布图，外部标签不得因空间不足直接隐藏低占比数值；应先收紧标签带、减小端点距离、跨侧均衡，再考虑 tooltip 降级。
- **适用配置范式**：异常/归因类环图可显式启用 `labelLayoutMode: 'smart'`，配合 `compactSmallSlices: false`、`hideOverflowLabels: false`、`balanceLabelSides: true`；其它页面默认不应被全局改动影响。

## 3. 滚动与对照

看板属于多面板对照场景，优先“面板内滚动”，避免整页滚造成输入/筛选/结果无法对照。

## 4. 图表底噪原则（把“装饰”降噪）

- **网格/坐标/图例**：属于“解释层”，不抢“数据层”
- **线宽/点大小**：保持克制，避免视觉噪音压过趋势
- **不要把 legend 当标题**：模块必须有明确标题与口径说明（否则 legend 变成不可控的标题替代）
