# Dashboard 页面范式（选型决策树）

> 先选范式/模板，再写布局与组件。禁止"看板 = 堆卡片"。

## 0. 快查索引

- **我该用单一大白卡还是分组多白卡**：看「§0.1 两种大布局结构」
- **顶部 Tabs 该用 line / segment / pill 哪种**：看「§0.2 Tabs 选型决策」
- **我该选哪个 Pattern**：看「§1 决策树」与「§2 tiebreaker」
- **我需要 recipe 映射**：看「§3 Pattern → Recipe 建议」
- **我需要关键词**：看「§4 关键词库（反向命中）」
- **关联阅读**：
  - 布局 recipe：`LAYOUT_RECIPES.md`
  - 布局规则/滚动决策：`LAYOUT_RULES.md`
  - 组件选型入口：`components.summary.json` → `components.index.json`

## 0.1 两种大布局结构（Dashboard 顶层骨架，**优先 B 型**）

> Dashboard 在白卡组织上只有两种合法骨架，二选一，**默认优先 B 型分组卡（更清晰）**。

### A 型：单一大白卡承载整页（**有限场景使用**）
- **典型形态**：整页只有一张白底"画布"，顶部业务 Tab 内嵌在白卡顶部，其余指标 / 图表 / 列表都在这张白卡内继续分区。
- **何时用**：
  - 业务主题**单一**，没有"不同主题分块"的诉求（如「原声反馈大屏」整页就讲反馈这一件事）
  - 顶部 Tab 是**内容总开关**（切换不同数据源/视图），而**不是页面分块标题**
  - 内容**密度低**、模块少（≤2 大区）、不需要为不同主题分组提供视觉边界
- **代表模板**：`VoiceFeedbackScreenPattern`（原声反馈大屏）
- **顶部 Tabs 选型**：必须用 **`variant="line"`**（下划线页签）—— 因为它就是"白卡顶部子页签"，line 是 Semi 标准做法

### B 型：分组多白卡（**默认优先**，强语义聚合）
- **典型形态**：页面背景是 `bg-blueGrey-200`，每个业务主题/语义分组各占一张白卡（卡内可再走 §2.0.3 聚合卡范式融合多图）。
- **何时用**：
  - 页面承载**多个业务主题/分组**（核心指标 / 反馈分析 / 问题列表 / 明细钻取……）
  - 不同分组间需要**视觉边界**，让用户一眼看清"这是 N 个相对独立的模块"
  - 内容密度中高、模块 ≥3、且每组都有自己的标题/口径
- **代表模板**：`ServiceDataScreenPattern` / `CustomerServiceOpsCockpitTestPattern` / `AIFullLinkDashboardTestPattern` / `Monitor315Pattern` / `UserPersonaDashboardPattern`
- **顶部 Tabs 选型**：
  - **业务/数据源切换**（如"全网热点 / 站内反馈"）→ **`variant="pill"`**（胶囊）：浮在灰底之上，与下方分组白卡视觉互不抢夺
  - **时间分段器**（24h / 7d / 30d / 自定义）→ **`variant="segment"`**（灰轨白块），独立放右侧
  - ❌ **禁止**用 `variant="line"`：line 是"白卡内子页签"语义，放在灰底页面顶栏会"漂浮无依托"，且与下方白卡的标题层级冲突

### 选型流程图
```
是否多业务主题/分组？
├─ 否 → A 型（单一大白卡 + line Tabs）
└─ 是 → B 型（分组多白卡）
        ├─ 顶部业务切换 → variant="pill"
        └─ 时间筛选     → variant="segment"
```

### 反例

| ❌ 错误做法 | 正确做法 | 影响 |
|---|---|---|
| 多分组页面顶部用 `variant="line"` | 改 `variant="pill"` | line 的下划线在灰底页面顶栏没有"承载条"，视觉飘 |
| 单白卡页面顶部用 `variant="pill"` | 改 `variant="line"` | pill 的胶囊背景与白卡冲突，且打破"卡内子页签"惯例 |
| 在分组页面把所有内容塞进一张白卡 | 按主题拆分到 N 张白卡（B 型） | 失去语义分组，主题感全无 |
| 把单一主题强拆成 N 张白卡 | 合并成 A 型或 §2.0.3 聚合卡 | 视觉碎片，无意义边界 |

## 0.2 Tabs 选型决策（基于 §0.1 大布局类型）

| 场景 | variant | size | 说明 |
|---|---|---|---|
| A 型单白卡顶部业务切换 | `line` | `sm` | 白卡内子页签的标准用法 |
| B 型分组页顶部业务切换（数据源/视图切换） | **`pill`** | `sm` | 胶囊浮于灰底，**Dashboard 默认推荐** |
| 时间分段器（独立的、范围筛选语义） | `segment` | `sm` | 灰轨白块，与业务 Tab 视觉解耦 |
| 卡片内小模块切换（同卡内 N 视图） | `segment` | `sm` | b-end 标准 "分段器" 行为 |
| 强调块级、按钮组感 | `button` | `sm` | 较少用 |

> 一句话记住：**「在灰底上 → pill；在白卡内 → line；时间筛选 → segment」**。

## 1. 决策树（只选一个首选模板）

| 触发信号 | 首选模板（Pattern） | 典型触发关键词（5–10） | 备注 |
| --- | --- | --- | --- |
| 一屏展示多个模块，强调"健康度 + 趋势 + 拆解" | `ServiceDataScreenPattern` | 总览、驾驶舱、健康度、趋势、TopN、拆解、模块、运营、概览 | 多模块布局，强调栅格与分组 |
| 监控类大屏，强调"告警/异常/排行/趋势" | `Monitor315Pattern` / `VoiceFeedbackScreenPattern` | 监控、告警、异常、舆情、热词、排行、趋势、来源、扩散 | 监控类视觉更强，但仍克制 |
| AI 全链路效果看板（测试/评测用） | `AIFullLinkDashboardTestPattern` | 全链路、评测、命中率、效果、漏斗、对比、AB、回归 | 强调对比与维度拆解 |
| 客服运营驾驶舱（测试/模板） | `CustomerServiceOpsCockpitTestPattern` | 客服、运营、工单、会话量、响应、满意度、人效、分组 | 多指标 + 明细钻取 |
| **用户/对象画像 + 多维特征聚合**（同主题不同维度图表共享一卡） | **`UserPersonaDashboardPattern`** | 用户画像、人群画像、特征、标签体系、反馈分析、问题归因、问题标签、人群对比 | **聚合卡范式**：示范同主题 N 图共享 1 卡，反"每图一白卡"碎片化 |

> 如果上述都不命中：先选“总览看板”范式，再按模块拆解。

## 2. Tiebreaker（同样命中多个 Pattern 时怎么选）

当多个 Pattern 都“看起来能用”时，只按下面顺序做裁决（从上到下，命中即停）：

1. **是否是评测/回归/AB 对比主线**：是 → `AIFullLinkDashboardTestPattern`
2. **是否是监控/告警/热点/舆情类大屏主线**：是 → 优先 `Monitor315Pattern`；如果有"原声/聚类/评论流"为主 → `VoiceFeedbackScreenPattern`
3. **是否是客服/工单/人效/满意度运营主线**：是 → `CustomerServiceOpsCockpitTestPattern`
4. **是否是用户/人群/对象画像 + 多维特征聚合分析**（多个图共讲同一主题）：是 → `UserPersonaDashboardPattern`
5. **否则**（多模块总览/健康度） → `ServiceDataScreenPattern`

> 禁止“混合模板”：只允许 1 个首选 Pattern 作为页面骨架，其余差异用 recipe/组件组合解决。

## 3. Pattern → Recipe 映射建议（pattern + recipe = 稳定骨架）

| Pattern | 建议主 recipe id | 适用备注 |
| --- | --- | --- |
| `ServiceDataScreenPattern` | `dashboard-overview` / `filter-sticky-modules-scroll` | 典型“左侧固定导航 + 右侧模块区滚动”；需要固定筛选时选后者 |
| `Monitor315Pattern` | `monitor-wall-split-columns` / `monitor-no-scroll` | 大屏双列：尽量不滚；必须滚时只让“列表/评论流”内滚 |
| `VoiceFeedbackScreenPattern` | `monitor-audio-feedback` / `filter-sticky-modules-scroll` | 原声列表天然需要内滚；顶部指标与趋势区保持稳定高度 |
| `AIFullLinkDashboardTestPattern` | `drilldown-compare` / `filter-sticky-modules-scroll` | 强对照/下钻：筛选固定 + 模块区滚；避免整页滚导致对照丢失 |
| `CustomerServiceOpsCockpitTestPattern` | `dashboard-overview` / `drilldown-compare` | 驾驶舱主线 + 明细钻取；表格区通常是内滚容器 |
| `UserPersonaDashboardPattern` | `aggregated-feature-card` / `filter-sticky-modules-scroll` | 聚合卡：同主题 N 图共享 1 卡 + 顶栏跨整宽 + 列表内滚 |

### 3.1 模板级实战约束（P0）

- **有页面标题的模板**：标题字号与 header 高度以 `ServiceDataScreenPattern` 为基准，统一 `DASHBOARD_PAGE_TITLE` + 固定 `h-14`；不要用 `text-[20px]` 或 `pb-3` 撑 header。
- **监控类大屏顶部**：如果顶部视觉显挤，只允许收敛页面顶 padding（如 24px → 16px），不要删除 header 与内容之间的 `gap-3`。
- **用户画像 / 特征聚合**：外层已有“核心反馈特征”大白卡时，`FeatureCardGroup` 必须用 `bare` 嵌入；不要把组件详情页的默认白卡预览搬进页面。
- **FeatureCardGroup 数量 / 折行**：一行最多 3 张子卡；4 张必须折成 2×2；5 张按上 3 下 2；6 张按 3+3。生成时如果配置 `columns=4/5/6` 但业务只给了 3 张卡，要复制已有卡片补足展示数量，不要留下空位，也不要渲染 4 列。
- **组件详情预览**：复杂多列组件要随画布自适应变宽，窄屏再横向滚动；页面模板显示正确时，不要为了修组件预览反向修改页面模板。
- **异常/归因环图**：需要完整读数时显式配置 `labelLayoutMode: 'smart'`、`compactSmallSlices: false`、`hideOverflowLabels: false`；仅影响目标页面，不做全局默认替换。

## 4. 关键词库（反向命中）

用于把自然语言需求快速归类到 Pattern（只作为提示，最终以 §2 tiebreaker 裁决）：

- **总览/驾驶舱**：总览、概览、驾驶舱、健康度、核心指标、趋势、拆解、TopN、分布、运营
- **监控大屏**：监控、告警、异常、热点、舆情、预警、实时、扩散、排行、热词、来源
- **原声/反馈**：原声、评论流、用户反馈、聚类、摘要、话题、议题、情绪、声量
- **评测/全链路**：评测、回归、命中率、效果、漏斗、AB、对比、分群一致性、聚类、Case 明细
- **客服运营**：客服、运营、工单、会话、响应、满意度、人效、策略、质检、评分
- **用户画像/特征聚合**：用户画像、人群画像、特征、标签体系、反馈分析、问题归因、问题标签、人群对比、消费分布、设备分布
