# Dashboard 生成自检 Checklist

## 0. 快查索引

- **交付前必做**：P0 全部通过
- **我需要 Inspect 契约**：看「§1.3 Inspect 契约」
- **我总是误判“看板可用”**：看「§1.4 常见误判与防线」
- **关联阅读**：
  - 失败反例库：`COMMON_FAILURES.md`
  - 滚动模型决策树：`LAYOUT_RULES.md` §1.2
  - recipe 选型矩阵：`LAYOUT_RECIPES.md`

## P0（必须满足）

- **模板选型**：先读 `PAGE_ARCHETYPES.md`，明确命中哪一类看板范式
- **布局 recipe**：先选唯一主 recipe（见 `LAYOUT_RECIPES.md`）
- **组件调用**：能用组件绝不手搓；Inspect 必须能看到 `.tfds-*` 或 `data-tfds-component`
- **配色**：按 `GLOBAL_DESIGN_RULES.md` §1/§2；禁止手写 hex/rgba 与黑色冒充系列色
- **封装 UI 链路（图表 P0）**：
  - 必须 `import "@tfdesign/dashboard/theme.css"`（或项目入口已统一引入，但必须可定位到代码位置）
  - 必须使用 `@tfdesign/dashboard` 的 `Smart*Chart` / `*Preview` / 已注册模块卡组件；禁止直接用 Recharts/ECharts/AntV 默认组件外观拼装
  - 必须使用 `useChartChrome`（或等价封装）与 `token-resolver/resolveColorToken`（或等价工具）；禁止自造 tooltip/legend 结构
  - **图表高度策略正确**：等高分组 / `flex-1` / 自适应（`fillContainer`）场景**不写** `spec.config.height`，高度交给容器决定；仅"独立、无等高约束、需固定防抖"才显式写高度（见 `LAYOUT_RULES.md` §3.1）。图表内部必须 viewBox/aspect-ratio 等比自适应、不被截断（见 §3.2）
- **滚动模型**：多面板对照工作流避免整页滚；滚动层只在正确容器内发生（见 `LAYOUT_RULES.md`）
- **对齐用容器、不用假高**：同语义分组卡片等高规则统一看 `LAYOUT_RULES.md` §2.0；禁止给个别兄弟卡手动塞高度制造假对齐

## P1（强烈建议）

- **文字可读**：避免灰底上的低对比文本；Tooltip/Legend 的字重与颜色符合 token
- **KPI 区**：主指标突出，次指标降级；不要堆 10+ 张 KPI 卡造成噪音
- **图表密度**：坐标/网格是底噪，不抢内容；禁止过粗线宽/过大点
- **对齐稳定**：同一行模块的标题区高度、legend 区预留高度尽量一致；同语义分组用容器等高对齐（`items-stretch`），不靠给个别卡片塞假高度修

## P2（加分项）

- **模块语义分段**：每一段都有“模块标题 + 解释/口径 + 主图/主表”，避免无标题堆叠
- **钻取路径清晰**：从 KPI → 拆解图 → TopN/聚类 → 明细表，能一眼看懂追因路线（见 `DESIGN_PRINCIPLES.md`）
- **抖动防线**：legend/tooltip 不抖动（见 `LAYOUT_RULES.md` §4）

---

## 1. 交付前“强制自检清单”（建议逐条打勾）

### 1.1 Pattern 与 recipe（P0）

- [ ] **Pattern**：只选 1 个，且名称来自 `src/data/systems/dashboard/patterns.js`
- [ ] **recipeId**：只选 1 个，且来自 `LAYOUT_RECIPES.md`
- [ ] **scrollOwner**：声明唯一滚动 owner，并满足 `LAYOUT_RULES.md` 的滚动决策树分支

### 1.2 组件选型与索引读取（P0）

- [ ] 先查 `components.summary.json`（kind/category/keywords）做粗选
- [ ] 使用 entry 的 `grepAnchor` 在 `components.index.json` 定位并局部读取 `props/rules/examples`
- [ ] 生成代码中优先复用 `@tfdesign/dashboard`（含其内置基础组件），不自造组件名
- [ ] **密度/对齐口令**：若用户提“对齐/底部对齐/收紧/留白”，先检查是否误触了禁用项（拉高卡、任意值、先动全局 gap），再按 `SKILL.md` §7.5 调整

### 1.3 Inspect 契约（P0，必须可被自动检查）

目的：让“生成结果是否使用了 TFDS 组件”可被人工/工具在浏览器快速确认。

- **必须满足其一**：
  - DOM 中出现 `.tfds-*` 类名（来自组件库或容器约定）
  - DOM 中出现 `data-tfds-component="xxx"`（或同等语义的 data 属性）
- **禁止**：
  - 只在代码里 import 了组件但 DOM 没有可观测痕迹
  - 只在最外层容器打一个无意义标记（无法区分模块/组件级别）

### 1.4 看板常见误判与防线（P0/P1）

- **误判 1：看起来“很满”就算看板**
  - **防线**：必须有“主线 + 追因路径”（KPI → 拆解 → TopN/聚类 → 明细），否则只是堆组件
- **误判 2：整页滚动也没问题**
  - **防线**：看板默认多面板对照，优先面板内滚；按 `LAYOUT_RULES.md` §1.2 裁决
- **误判 3：图表能画出来就算完成**
  - **防线**：必须走封装 UI 链路与图表高度规则，详见 `SKILL.md` §3.1、`LAYOUT_RULES.md` §3/§4、`COMMON_FAILURES.md` §1.1/§17
- **误判 4：缺组件就手搓一个“类似的”**
  - **防线**：先组合现有组件，再按 `GLOBAL_DESIGN_RULES.md` token 化降级（见 `SKILL.md` §4.2）
- **误判 5：底部对齐=给某张卡塞假高度**
  - **防线**：只按 `LAYOUT_RULES.md` §2.0 做容器统一等高；反例见 `COMMON_FAILURES.md` §7
