# 仪表板模式 - 实时数据可视化整理项目现有的仪表板架构：Status Command Center 组件库、后端分析 API 以及管理每个数据表面的 Scientific Luxury 设计规则。强制执行时间线布局、光谱颜色、基于物理的动画和澳大利亚区域设置格式。 ## 说明为 NodeJS-Starter-V1 编写实时仪表板模式，包括 Status Command Center 组件库、时间线/轨道布局、Supabase Realtime 集成、光谱颜色映射以及所有数据可视化表面的 Scientific Luxury 设计实施。 ** ** ## 何时申请 ### 积极的触发因素 * 构建新的仪表板页面或指标显示 * 添加实时数据可视化组件 * 集成 Supabase Realtime 进行实时更新 * 为仪表板创建加载骨架或空状态 * 组合 MetricTile、DataStrip 或 ProgressOrb 组件 * 审查仪表板布局以确保科学奢侈品合规性 * 用户提及：“仪表板”、“指标展示”、“实时”、“监控UI”、“指挥中心” ### 负面触发因素 * 收集或存储指标数据（使用“metrics-collector”代替） * 设计电子邮件模板（使用 `email-template` 代替） * 添加日志语句（使用“结构化日志记录”代替） * 实现非仪表板 UI 组件（使用 `scientific-luxury` 代替） ## 核心指令 ### 仪表板三定律 1. **时间轴，从不网格**：没有 `grid-cols-2`/`grid-cols-4` 布局。使用垂直时间线、水平数据条和轨道排列。 2. **光谱，永不静态**：每个状态都映射到带有呼吸动画的光谱颜色。没有灰色占位符状态。 3. **实时，永不过时**：通过 Supabase Realtime 或 30 秒轮询获取实时数据。始终显示连接状态。 ** ** ## 现有项目基础设施 ### 组件库 **位置**：`apps/web/components/status-command-centre/` 类别 |组件 ---|--- **主要** | `StatusCommandCentre`（完整/紧凑/最小变体） **数据显示** | `DataStrip`（水平指标）、`MetricTile`（带有趋势的统计图块） **可视化** | `ProgressOrb`、`ProgressRing`、`StatusPulse`、`StatusBadge` **活动** | `AgentNode`、`AgentActivityCard`、`ActivityTimeline`、`AgentThinkingIndicator` **实用程序** | `NotificationStream`、`ElapsedTimer` **挂钩** | `useElapsedTime`、`useCountdown`、`useStatusTransitions`、`useStatusColourTransition` **实用程序** | `formatElapsedAU`、`formatTimestampAU`、`formatDateAU`、`getAustralianTimezone` ### 仪表板页面页 |地点 |数据来源 ---|---|--- 代理仪表板 | `apps/web/app/(dashboard)/agents/page.tsx` | `/api/agents/stats`、`/api/agents/list` 分析仪表板 | `apps/web/app/dashboard-analytics/page.tsx` | `/api/analytics/metrics/overview` 状态指挥中心|嵌入式组件 | Supabase Realtime（`agent_runs` 表） ### 后端 API 路线 |地点 |退货 ---|---|--- `/分析/指标/概述` | `apps/backend/src/api/routes/analytics.py` |运行次数、成功率、成本、代币 `/analytics/metrics/agents` |相同文件 |每个代理的绩效细分 `/分析/指标/成本` |相同文件 |按模型划分的成本、代币细分 `/api/agents/stats` | `apps/backend/src/api/routes/agent_dashboard.py` |汇总代理统计数据 `/api/agents/{id}/health` |相同文件 | `AgentHealthReport` 模型 `/api/agents/performance/trends` |相同文件 |时间序列趋势数据 ** ** ## 布局模式 ### 禁止：卡片网格 // 已拒绝 — 违反科学奢华和时间线法

<卡>... <卡>...

### 必需：时间线布局 `StatusCommandCentre` 实现了带有代理节点的垂直时间线脊柱：

{/* 垂直时间轴脊柱 */} <运动.div 初始={{scaleY:0}} 动画={{scaleY:1}} 过渡={{ 延迟: 0.3, 持续时间: 0.8, 缓和: [0.19, 1, 0.22, 1] }} className="绝对 top-0 Bottom-0 left-8 w-px origin-top bg-渐变-b 从-白色/10 通过-白色/5 到-透明" /> {/* 沿着主干的代理节点 */}

{runs.map((运行，索引) => ( ))}

### 必需：水平数据条将度量网格替换为“DataStrip”——带有光谱颜色值的内联水平布局： <数据条指标={[ { 标签：'总计'，值：runs.length }， { 标签: 'Active', 值: activeRuns.length, 变量: 'info' }, { 标签：'已完成'，值：completedRuns.length，变量：'成功' }， { 标签: '失败', 值: failedRuns.length, 变量: '错误' }, ]} /> DataStrip 使用 JetBrains Mono 作为值，使用“text-[10px] Tracking-widest uppercase”作为标签，使用指标之间的管道分隔符，以及非零突出显示值上的光谱发光。 ** ** ## 光谱颜色映射每个“AgentRunStatus”都映射到“constants.ts”中定义的光谱颜色：状态 |颜色 |福胜利 |动画 ---|---|---|--- `待处理` |板岩| `hsl(220 14% 46%)` |脉冲（空闲） `进行中` |蓝色| `hsl(217 91% 60%)` |旋转（主动） `等待验证` |琥珀 | `hsl(38 92% 50%)` |脉冲（主动） `验证进行中` |琥珀 | `hsl(38 92% 50%)` |旋转（主动） `验证已通过` |绿色| `hsl(142 76% 36%)` |无（空闲） `验证失败` |红色| `hsl(0 84% 60%)` |脉搏（紧急） `已完成` |祖母绿| `#00FF88` |无（空闲） `失败` |红色| `#FF4444` |脉搏（紧急） `被阻止` |板岩|静音 |无（空闲） `升级为人类` |洋红色| `#FF00FF` |脉搏（紧急）通过“constants.ts”中的“getStatusConfig(status)”访问。每个配置包括“颜色”（主色、发光、背景）、“图标”、“动画”和“强度”。 DataStrip 变体使用简化的光谱颜色：“info=#00F5FF”、“success=#00FF88”、“warning=#FFB800”、“error=#FF4444”。 ** ** ## 动画模式所有动画均使用 Framer Motion。 CSS 转换是**禁止的**。 ### 交错进入组件按延迟偏移顺序动画： <运动.div 初始={{ 不透明度: 0, y: 20 }} 动画={{ 不透明度: 1, y: 0 }} 过渡={{ 延迟: 0.1 * 索引, 缓和: [0.19, 1, 0.22, 1] }} > ### 呼吸球状态指示器使用呼吸动画来表示活动状态： <运动.span className="h-1.5 w-1.5 四舍五入" 样式={{背景颜色：config.colour.primary}} animate={{ 不透明度: [1, 0.4, 1], 比例: [1, 1.2, 1] }} 过渡={{持续时间：2，重复：无限，ease：'easeInOut'}} /> ### 环境光活性剂触发径向渐变背景发光： {activeRuns.length > 0 && ( <运动.div 初始={{不透明度:0}} 动画={{不透明度:0.1}} className="pointer-events-none 绝对插入-0" style={{ 背景: '径向渐变(椭圆 20% 10%, hsl(217 91% 60% / 0.15) 0%, 透明 50%)' }} /> )} ### 状态转换使用 useStatusTransitions 钩子来检测状态变化并应用过渡动画（成功波纹、错误摇动）。 ** ** ## 数据获取模式 ### 服务器组件（初始加载）使用 Next.js 服务器组件通过 `cache: 'no-store'` 进行初始数据获取：异步函数 fetchAgentStats() { const backendUrl = process.env.BACKEND_URL || 'http://localhost:8000'; const res = wait fetch(`${backendUrl}/api/agents/stats`, { 缓存: '无存储' }); if (!res.ok) 返回 FALLBACK_STATS；返回 res.json(); } 始终提供后备数据，以便即使后端不可用时页面也会呈现。 ### 投票（分析仪表板）对于非实时页面，以 30 秒的间隔轮询：使用效果（（）=> { fetchMetrics(); const 间隔 = setInterval(fetchMetrics, 30_000); 返回（）=>清除间隔（间隔）； }, []); ### Supabase Realtime（指挥中心）对于状态命令中心，订阅 `agent_runs` 表更改：常量通道=supabase .channel('代理运行') .on('postgres_changes', { 事件: '*', 架构: 'public', 表: 'agent_runs' }, （有效负载：RealtimePayload）=> { if (payload.eventType === 'INSERT') addRun(payload.new); if (payload.eventType === '更新') updateRun(payload.new); }) .subscribe(); 类型“RealtimeEvent”、“RealtimePayload”和“ConnectionStatus”在“types.ts”中定义。 ### 连接状态始终使用“ConnectionIndicator”组件显示连接状态： * **已连接**（翡翠呼吸点+“Live”标签） * **重新连接**（琥珀色圆点 +“重新连接”标签） * **已断开连接**（红点+“离线”标签） ** ** ## 加载和空状态 ### 加载骨架每个仪表板页面必须显示与最终布局结构相匹配的骨架：函数加载骨架（）{ 返回（

<运动.div className="h-10 w-64 圆形-sm bg-white/5" 动画={{ 不透明度: [0.5, 1, 0.5] }} 过渡={{持续时间：1.5，重复：无穷大}} /> {/* 更多符合真实布局的骨架元素 */}

）； } 规则：对骨架块使用“bg-white/5”，仅使用“rounded-sm”，呼吸不透明动画，每个元素交错延迟。 ### 空状态当没有可用数据时，显示带有呼吸球的居中空状态：

<运动.div className="h-3 w-3 圆形全 bg-white/20" animate={{ 比例: [1, 1.5, 1], 不透明度: [0.5, 1, 0.5] }} 过渡={{持续时间：2，重复：无限，ease：'easeInOut'}} />

没有活动代理

描述文本。

** ** ## 组件构成 ### 新仪表板页面模板每个仪表板页面都遵循以下结构： // 1. 服务器组件包装器（数据获取）导出默认异步函数 DashboardPage() { const data = 等待 fetchData(); 返回（

{/* 标头 */}

类别标签

页面标题

{/* 内容 — 时间线或轨道，从不网格 */} }> {/* 页脚 */} <页脚类名=“px-8 py-4”>

{new Date().toLocaleDateString('en-AU')}

）； } ### 何时使用每个组件需要|组件|导入自 ---|---|--- 内联指标行 | `数据条` | `状态指挥中心` 具有趋势的单一统计数据 | `公制瓷砖` | `状态指挥中心` 代理执行状态 | `代理节点` | `状态指挥中心` 循环进展| `ProgressOrb` 或 `ProgressRing` | `状态指挥中心` 状态点| `状态脉冲` | `状态指挥中心` 状态标签| `状态徽章` | `状态指挥中心` 步骤时间表| `活动时间轴` | `状态指挥中心` 通知侧边栏 | `通知流` | `状态指挥中心` 经过时间计数器| `经过计时器` | `状态指挥中心` ** ** ## 反模式反模式|为什么失败 |正确的做法 ---|---|--- `grid-cols-2` / `grid-cols-4` 度量卡 |违反科学奢华布局规则 | `DataStrip` 或时间线布局标准 `` 与 `rounded-lg` |错误的角落，错误的审美 | `rounded-sm border-[0.5px] border-white/[0.06]` CSS `过渡：全部 0.3 秒线性` |被 Bezier（逻辑委员会）禁止 |带有基于物理缓动的 Framer Motion 白色/浅色背景仪表板|违反 OLED 黑色要求 | `bg-[#050505]` 总是无加载骨架|数据加载时的布局变化 |骨架匹配最终布局结构无连接指示灯|用户无法判断数据是否实时 |每个实时页面中的“ConnectionIndicator” 硬编码状态颜色 |光谱调色板的漂移| `getStatusConfig(状态).颜色` 没有清理的`setInterval`卸载时内存泄漏 |清理中的“useEffect”和“clearInterval” ** ** ## 新仪表板页面清单 ### 布局 * OLED黑色背景（`bg-[#050505]`） * 时间线或轨道布局（无卡片网格） * `DataStrip` 用于汇总指标（不是指标网格） * 单像素边框（`border-[0.5px] border-white/[0.06]`） * 仅“rounded-sm”（无“rounded-lg”、“rounded-xl”） * JetBrains Mono 用于数据值 ### 数据 * 用于初始获取回退数据的服务器组件 * 轮询间隔（30s）或Supabase Realtime订阅 * 显示连接状态指示器 * 加载与最终布局匹配的骨架 * 空状态下有呼吸球 ### 动画 * 适用于所有过渡的 Framer Motion（无 CSS 过渡） * 列表项交错输入 * 活动状态指示器的呼吸动画 * 代理激活时周围会发光 ### 整合 * 使用 `metrics-collector` `MetricsRegistry` 作为数据源 * 来自`STATUS_CONFIG`常量的光谱颜色 * 澳大利亚语言环境格式（`formatDateAU`、`formatTimestampAU`） * 从 `status-command-center/types.ts` 导入的类型 ** ** ## 响应格式 [AGENT_ACTIVATED]：仪表板模式 [阶段]：{设计|实施 |评论} [状态]：{进行中|完成} {仪表板分析或实施指南} [NEXT_ACTION]：{下一步做什么} ## 集成点 ### 科学奢华 * OLED 黑色背景、光谱颜色、单像素边框、基于物理的动画 * 所有仪表板组件通过“constants.ts”自动强制执行设计系统 ### 指标收集器 * `MetricsRegistry` 提供数据层（计数器、仪表、直方图） * 时间序列聚合支持趋势图 * 摘要端点提要“DataStrip”和“MetricTile”组件 ### 状态机 * `AgentRunStatus`（10 个状态）直接映射到 `STATUS_CONFIG` 颜色/动画条目 * `useStatusTransitions` 钩子处理状态变化动画 ### 结构化日志记录 * 仪表板页面记录 `dashboard_loaded`、`dashboard_error` 事件 * 记录连接状态变化以供调试 ### Cron 调度程序 * 通过“DataStrip”或“MetricTile”显示的 Cron 作业指标 * 每日报告数据为分析仪表板趋势提供动力 ## 澳大利亚本地化 (en-AU) * **日期格式**：DD/MM/YYYY 通过 `formatDateAU()` 实用程序 * **时间** ：H:MM am/pm AEST/AEDT 通过 `formatTimeAU()` 和 `getAustralianTimezone()` * **货币** ：澳元 ($) — `total_cost_usd` 转换为澳元以供显示 * **拼写**：颜色、行为、分析、优化、中心 * **页脚**：仪表板页脚中的澳大利亚日期格式

仪表板模式

包含技能