@teamix-evo/skills 0.10.2 → 0.11.1

package/src/teamix-evo-design-opentrek/pages/dashboard-page/patterns/dashboard-opentrek.md

@@ -0,0 +1,268 @@
+# OpenTrek 仪表板页业务规则
+
+> 路由自 [../SKILL.md](../SKILL.md)
+> 本文件基于 OpenTrek DEV 平台实际页面截图沉淀，定义仪表板页面级组合规则。
+> 所有 UI 组件引用均指向 `packages/ui/src/components/`，开发时必须从该路径导入。
+> 通用仪表板规则（TimeToolbar/StatCard/ChartPanel/Grid 布局）见 [../SKILL.md](../SKILL.md) §5。
+
+---
+
+## 1. 页面模式速查表
+
+| 模式 ID | 名称 | 典型页面 | 核心结构 |
+|---------|------|----------|----------|
+| **OT-DASH-1** | 指标监控总览 | 指标监控（应用层/资产层/模型服务层） | PageHeader + Desc + TimeToolbar + NavCards + StatCardRow + ChartGrid |
+| **OT-DASH-2** | 实体观测面板 | 知识库 > 产品文档库 - 观测 | Breadcrumb + FilterBar + TimeToolbar + ChartGrid(3×N) |
+
+---
+
+## 2. OT-DASH-1：指标监控总览
+
+> 典型页面：指标监控首页（L1 级，无面包屑）
+
+### 布局骨架
+
+```
+┌─ PageShell (components/page-shell) ──────────────────────────────────────┐
+│ sidebar: Sidebar (components/sidebar)                                     │
+│ children:                                                                 │
+│ ┌─ ContentCard (components/card → Card + CardContent) ──────────────┐   │
+│ │ PageHeader (components/page-header):                               │   │
+│ │   Heading: "指标监控" (18px/500)                                    │   │
+│ │   Description: "应用层·资产层·模型服务层 — 全方位监控系统运行态势"          │   │
+│ │                                                                    │   │
+│ │ TimeToolbar (与 PageHeader 独立一行, 右侧对齐):                      │   │
+│ │   ToggleGroup[分钟|小时|天]                                         │   │
+│ │   ToggleGroup[近7日|近30日|近1年|自定义] (选中: bg-primary)           │   │
+│ │   Button(outline) "↻ 刷新"                                         │   │
+│ │                                                                    │   │
+│ │ NavigationCards (flex row, gap=16px):                               │   │
+│ │   ┌─NavCard(selected)─┐ ┌─NavCard──────┐ ┌─NavCard──────┐        │   │
+│ │   │ 🔷 应用层       → │ │ 🔷 资产层   → │ │ 🔷 模型服务层 → │      │   │
+│ │   │ 智能体应用的调用… │ │ 知识库、记忆…│ │ 模型服务的调用…│        │   │
+│ │   └──────────────────┘ └─────────────┘ └──────────────┘          │   │
+│ │                                                                    │   │
+│ │ Section "总览指标" (icon: 📈 + title + right: "近7天统计数据"):      │   │
+│ │   StatCardRow (grid-cols-6, gap=16px):                             │   │
+│ │   ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐              │   │
+│ │   │●128  ││●356  ││●89   ││●12.6K││●42.9K││●1.1M │              │   │
+│ │   │智能体 ││版本数 ││上线版本││会话数  ││调用量  ││tokens│              │   │
+│ │   │┄spark┄││┄spark┄││┄spark┄││┄spark┄││┄spark┄││┄spark┄│              │   │
+│ │   └──────┘└──────┘└──────┘└──────┘└──────┘└──────┘              │   │
+│ │                                                                    │   │
+│ │ ChartSection (grid-cols-3, gap=16px):                              │   │
+│ │   ┌─ 调用趋势 (col-span-2) ────────────┐┌─ 类型分布 (col-span-1) ┐│   │
+│ │   │ dual Y-axis: Line+Area             ││ Donut + Legend          ││   │
+│ │   │ 左Y: 调用量, 右Y: 成功率%           ││ [调用量|Tokens] toggle  ││   │
+│ │   │ X轴: 日期 6/9~6/15                 ││ ●知识问答 47.5K 41%     ││   │
+│ │   └────────────────────────────────────┘│ ●工作流 27.6K 24%      ││   │
+│ │                                          │ ●角色对话 28.4K 25%    ││   │
+│ │                                          │ ●TrekAgent 11.0K 10%  ││   │
+│ │                                          └────────────────────────┘│   │
+│ └────────────────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 页面级组件清单
+
+| 区域 | UI 组件库引用 | 用途 | 必需 |
+|------|--------------|------|------|
+| 页面框架 | `components/page-shell` → `PageShell` | L1 级页面壳 | ✅ |
+| 侧边导航 | `components/sidebar` → `Sidebar` + `SidebarContent` + `SidebarMenu` | 左侧导航 | ✅ |
+| 白卡容器 | `components/card` → `Card` + `CardContent` | 内容区白色容器 | ✅ |
+| 页面标题 | `components/page-header` → `PageHeader` + `PageHeaderHeading` + `PageHeaderDescription` | 标题+描述 | ✅ |
+| 时间粒度 | `components/toggle-group` → `ToggleGroup`(type='single') + `ToggleGroupItem` | 分钟/小时/天 | ✅ |
+| 时间范围 | `components/toggle-group` → `ToggleGroup`(type='single') + `ToggleGroupItem` | 近7日/近30日/近1年/自定义 | ✅ |
+| 刷新 | `components/button` → `Button`(variant='outline', size='sm') + icon:RefreshCw | 手动刷新 | ✅ |
+| 导航卡片 | `components/card` → `Card` + hover:shadow-md + 内部 flex row | 分类入口 | ✅(OT-DASH-1) |
+| 统计数值 | `components/statistic` → `Statistic`(value, title, prefix) | 核心指标 | ✅ |
+| 状态圆点 | `components/badge` → `Badge` 或自定义 `8px circle` | 指标色彩标识 | ✅ |
+| 信息提示 | `components/tooltip` → `Tooltip` + `TooltipTrigger` + `TooltipContent` | ⓘ 指标说明 | 可选 |
+| 视角切换 | `components/toggle-group` → `ToggleGroup`(type='single') + `ToggleGroupItem` | 调用量/Tokens | 可选 |
+
+### NavigationCard 详细规范
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| 容器 | `Card`, `min-width: 200px`, flex: 1, `cursor-pointer` | 等分一行 |
+| 内部布局 | flex row, align-center, gap=12px, padding: 16px 20px | 横向排列 |
+| 图标区 | 40px×40px 圆角容器，`bg-primary/10`，居中显示 24px icon | 分类标识 |
+| 文本区 | flex column: 标题(`text-sm font-medium`) + 描述(`text-xs text-muted-foreground`) | 左侧文本 |
+| 箭头 | `ChevronRight` icon, 16px, `text-muted-foreground`, margin-left: auto | 右侧箭头 |
+| 选中态 | `ring-2 ring-primary ring-offset-2`（蓝色外框） | 当前激活卡片 |
+| Hover | `shadow-md` + `border-color: hsl(var(--primary)/0.3)` | 悬浮反馈 |
+| 点击 | 切换当前仪表板数据源（刷新所有 Section） | 导航行为 |
+
+### StatCard 详细规范（OT-DASH-1 特化）
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| 容器 | `Card`(无border, shadow-none, `bg-transparent`) 或无容器 | 行内轻量展示 |
+| 色彩圆点 | 8px circle, `bg-[hsl(var(--chart-N))]` | 左上角标识 |
+| 标签 | `Badge`(variant='secondary', size='xs') "累计指标" | 指标类型 |
+| 数值 | `Statistic` value, `text-3xl font-bold tabular-nums` | 核心数字(128/356/12.6K) |
+| 描述 | `text-sm text-muted-foreground` + 可选 Tooltip(ⓘ) | 指标名称 |
+| Sparkline | 迷你面积图, 高度 32px, 无坐标轴, 填充色 `chart-N/0.2` | 趋势缩略 |
+| 网格 | 同一行等宽排列，`grid-cols-6`(6个) 或 `grid-cols-4`(4个) | 响应式 |
+
+### 图表 Section 规范
+
+#### 调用趋势（Area/Line + 双Y轴）
+
+| 属性 | 值 |
+|------|-----|
+| 占位 | `col-span-2`（3 列 Grid 中占 2 列） |
+| 图表类型 | 组合图：面积(调用量-左Y) + 虚线(成功率%-右Y) |
+| 左Y轴 | 数值，自动刻度(0/200K/400K/600K/800K) |
+| 右Y轴 | 百分比(0%/3%/6%/10%) |
+| X轴 | 日期, `M/D` 格式 |
+| 面积填充 | `hsl(var(--chart-1) / 0.15)` |
+| 线色 | 主线: `hsl(var(--chart-1))`(蓝), 副线: `hsl(var(--chart-4))`(橙,虚线) |
+| Section 标题 | icon(📈) + "调用趋势" + right-text "近7天" |
+
+#### 类型分布（Donut/Pie Chart）
+
+| 属性 | 值 |
+|------|-----|
+| 占位 | `col-span-1`（3 列 Grid 中占 1 列） |
+| 图表类型 | 环形图(Donut)，内圆半径 60% |
+| 色彩 | 按 `chart-1` → `chart-4` 顺序 |
+| Legend | 图表下方，每行: ●色彩圆点 + 名称 + 数值(bold) + 百分比 |
+| 切换 | 右上 `ToggleGroup`(type='single'): [调用量 | Tokens] |
+| Section 标题 | icon(🔵) + "智能体类型分布" |
+
+---
+
+## 3. OT-DASH-2：实体观测面板
+
+> 典型页面：知识库 > 产品文档库 - 观测（L2 级，带面包屑）
+
+### 布局骨架
+
+```
+┌─ PageShell ──────────────────────────────────────────────────────────────┐
+│ sidebar: Sidebar                                                          │
+│ ┌─ ContentCard ──────────────────────────────────────────────────────┐   │
+│ │ Breadcrumb: 知识库 > 产品文档库 - 观测                                  │   │
+│ │                                                                    │   │
+│ │ ToolbarRow (flex, justify-between):                                │   │
+│ │   .left-filters:                                                   │   │
+│ │     Label "调用方式" + Select[全部▼]                                  │   │
+│ │     Label "调用空间" + Select[全部▼]                                  │   │
+│ │   .right-time:                                                     │   │
+│ │     ToggleGroup[分钟|小时|天]                                        │   │
+│ │     ToggleGroup[今日|近7日|近30日|近1年|自定义]                         │   │
+│ │     Button "↻ 刷新"                                                 │   │
+│ │                                                                    │   │
+│ │ Section "明细指标" (icon: 📊 + title + right: "近7日统计数据"):        │   │
+│ │   ChartGrid (grid-cols-3, gap=16px):                               │   │
+│ │     Row 1:                                                         │   │
+│ │       [知识库调用量] [知识库调用成功率] [知识库调用平均耗时]               │   │
+│ │     Row 2:                                                         │   │
+│ │       [解析tokens消耗ⓘ] [索引构建tokens消耗ⓘ] [检索tokens消耗ⓘ]      │   │
+│ └────────────────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 页面级组件清单
+
+| 区域 | UI 组件库引用 | 用途 | 必需 |
+|------|--------------|------|------|
+| 面包屑 | `components/breadcrumb` → `Breadcrumb` + `BreadcrumbItem` + `BreadcrumbLink` + `BreadcrumbSeparator` | L2 导航 | ✅ |
+| 筛选标签 | `<span>` + `text-sm text-muted-foreground` | "调用方式"等 label | ✅ |
+| 下拉筛选 | `components/select` → `Select` + `SelectTrigger` + `SelectContent` + `SelectItem` | 维度筛选 | ✅ |
+| 时间粒度 | `components/toggle-group` → `ToggleGroup`(type='single') + `ToggleGroupItem` | 分钟/小时/天 | ✅ |
+| 时间范围 | `components/toggle-group` → `ToggleGroup`(type='single') + `ToggleGroupItem` | 今日/近7日/... | ✅ |
+| 刷新 | `components/button` → `Button`(variant='outline', size='sm') | 手动刷新 | ✅ |
+| 图表卡片 | `components/card` → `Card` + `CardContent` | 单个图表容器 | ✅ |
+| 信息提示 | `components/tooltip` → `Tooltip` | 指标说明 ⓘ | 可选 |
+
+### ToolbarRow 规范
+
+| 规则 | 说明 |
+|------|------|
+| 布局 | `flex justify-between items-center`，左侧筛选 + 右侧时间 |
+| 左侧 | Label + Select 组合，多组筛选间 gap=16px |
+| Label 样式 | `text-sm text-foreground font-normal`，与 Select 间距 8px |
+| 右侧 | TimeToolbar（粒度+范围+刷新），遵循 SKILL.md §5.1 |
+| 分隔 | 左右两组之间自然由 `justify-between` 推开 |
+
+### ChartCard 详细规范（OT-DASH-2 特化）
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| 容器 | `Card`(shadow-sm, rounded-lg), padding: 16px 20px | 独立白卡 |
+| 标题行 | `text-sm font-medium` + 可选 `Tooltip`(ⓘ icon, size=14px) | 指标名 |
+| 图表类型 | 面积图(Area Chart)，填充渐变 | 时序数据 |
+| 图表高度 | 160px | 紧凑展示 |
+| X轴 | `text-xs text-muted-foreground`，日期格式 `M/D` | 每天一个刻度 |
+| Y轴 | `text-xs text-muted-foreground`，自适应刻度 | 量度轴 |
+| 线宽 | 2px | 清晰可见 |
+| 面积填充 | 从 `hsl(var(--chart-N) / 0.3)` → 透明 的线性渐变 | 柔和过渡 |
+| 不同指标色彩 | 每张卡片使用不同 `chart-N` 色值 | 按顺序消费 |
+
+### 图表色彩分配（知识库观测示例）
+
+| 图表 | 色彩变量 | 视觉色 |
+|------|----------|--------|
+| 知识库调用量 | `--chart-1` | 蓝/靛 |
+| 知识库调用成功率 | `--chart-2` | 绿 |
+| 知识库调用平均耗时 | `--chart-4` | 橙/红 |
+| 解析tokens消耗 | `--chart-3` | 青 |
+| 索引构建tokens消耗 | `--chart-5` | 紫 |
+| 检索tokens消耗 | `--chart-1` | 蓝(复用) |
+
+> 色彩按 chart-1 → chart-5 顺序消费，超过后从头循环。
+
+---
+
+## 4. 公共交互规范
+
+### 时间联动
+
+| 规则 | 说明 |
+|------|------|
+| 全局联动 | 切换时间粒度/范围后，页面内**所有图表**同步刷新 |
+| Loading 态 | 刷新时图表区显示 Skeleton 骨架屏 |
+| 无数据态 | 图表区显示 Empty 组件（"暂无数据"），保留坐标轴 |
+| URL 同步 | `?granularity=day&range=7d` 或 `?start=2026-06-09&end=2026-06-15` |
+| 默认值 | 粒度=天，范围=近7日 |
+
+### 刷新行为
+
+| 规则 | 说明 |
+|------|------|
+| 手动刷新 | 点击"↻ 刷新"按钮，刷新所有 Section |
+| 自动刷新 | OT-DASH-1 可选（默认关闭），OT-DASH-2 不需要 |
+| 刷新动画 | RefreshCw icon 旋转动画持续到数据返回 |
+| 节流 | 连续点击 debounce 1s |
+
+### Section 标题规范
+
+| 元素 | 样式 | 说明 |
+|------|------|------|
+| 图标 | 20px，`text-muted-foreground` | 语义图标(📈/📊/🔵) |
+| 标题 | `text-base font-medium`，gap=8px(与图标) | Section 名称 |
+| 右侧文本 | `text-xs text-muted-foreground`，`margin-left: auto` | "近7天统计数据" |
+| 容器 | `flex items-center` 单行，margin-bottom: 12px | 标题行 |
+
+---
+
+## 5. 验证清单
+
+| 验证项 | 检查点 | 目标 |
+|--------|--------|------|
+| 模式匹配 | 页面结构与模式 ID（OT-DASH-1/2）一致 | 100% |
+| PageHeader | L1 含 Description，L2 含 Breadcrumb | 正确 |
+| TimeToolbar | 粒度 ToggleGroup + 范围 ToggleGroup + 刷新 Button 三部分完整 | 正确 |
+| 时间范围选中态 | 选中项 `bg-primary text-primary-foreground` 高亮 | 正确 |
+| NavigationCard | OT-DASH-1 必需，选中 ring-2，hover shadow-md | 正确 |
+| StatCardRow | 使用 `Statistic` 组件，`tabular-nums`，sparkline 高 32px | 正确 |
+| ChartGrid | grid-cols-3(desktop) / grid-cols-2(tablet) / grid-cols-1(mobile) | 正确 |
+| 图表色彩 | 全部使用 `hsl(var(--chart-N))`，按顺序消费 | 100% |
+| 面积填充 | 使用半透明渐变（0.2~0.3 → transparent） | 正确 |
+| Section 标题 | icon + title + right-text 三要素 | 正确 |
+| FilterBar | OT-DASH-2 必需，Label + Select 组合 | 正确 |
+| URL 持久化 | 时间参数同步到 URL searchParams | 正确 |
+| 组件引用 | 所有组件从 `packages/ui/src/components/` 导入 | 100% |
+| 只读约束 | 无 Form / 无内联编辑 / 无 DataTable 主体 | 0 个违反 |