nexus-terminal/.helloagents/plan/202603252343_dashboard-management-cockpit/proposal.md

变更提案: dashboard-management-cockpit

元信息

类型: 新功能
方案类型: implementation
优先级: P1
状态: 草稿
创建: 2026-03-25

---

1. 需求

背景

当前首页仪表盘主要由连接列表和最近活动组成，信息密度偏低，缺少“总览面板”应有的关键统计、趋势和分布视角。用户明确反馈该区域“太简陋”，希望加入各类数据统计，使首页能更快反映连接资产规模、近期活跃度和审计行为概况。

目标

• 将首页升级为管理驾驶舱式仪表盘，而不再只是列表首页。
• 新增可快速扫读的统计卡片、近 7 天趋势图、连接类型分布和高频连接排行。
• 通过后端聚合接口统一提供 dashboard summary，避免前端依赖多接口拼装复杂统计。
• 保留现有连接列表、最近活动和跳转链路，让首页既能看总览，也能继续执行常用操作。

约束条件

时间约束: 本轮内完成前后端联动与基础构建验证
性能约束: 仪表盘首页统计应通过单个 summary 接口返回，避免首屏并发拉取过多数据
兼容性约束: 保持现有 `/connections` 与 `/audit-logs` 页面和接口行为不变
业务约束: 统计口径优先使用当前数据库中已稳定存在的连接表和审计日志表，不依赖临时内存状态

验收标准

• 首页新增核心统计卡片，至少覆盖连接总数、近 7 天活跃连接数、审计日志总数、近 24 小时 SSH 成功/失败次数
• 首页新增趋势和分布图表，至少覆盖近 7 天审计事件趋势和连接类型分布
• 首页新增“近期最活跃连接”排行，基于审计日志中的连接事件聚合
• 后端提供单独的 dashboard summary API，并由前端页面消费
• packages/frontend 与 packages/backend 的构建校验通过

---

2. 方案

技术方案

在后端新增 dashboard 聚合模块，提供 GET /api/v1/dashboard/summary 接口，直接基于 SQLite 中的 connections、connection_tags、audit_logs 数据生成首页所需的统计摘要。前端新增 dashboard store 与 summary 类型定义，重构 DashboardView.vue，将当前首页拆分为“统计卡片 + 图表区 + 排行/列表区 + 最近活动”，并继续复用现有连接列表与最近活动交互。图表继续使用仓库已存在的 chart.js / vue-chartjs 技术栈。

影响范围

涉及模块:
  - backend: 新增 dashboard 聚合接口与数据查询逻辑
  - frontend: 新增 summary 类型和 store，重构 DashboardView 展示结构
  - frontend: 补充 dashboard 多语言文案
预计变更文件: 10-14

风险评估

风险	等级	应对
审计日志 details 为 JSON 字符串，连接排行和事件摘要解析不稳	中	后端统一做安全解析，解析失败时忽略单条异常数据，不阻断整体 summary
新增 dashboard 接口后，首页首屏依赖单次聚合查询，若 SQL 设计粗糙会拖慢加载	中	采用有限窗口统计和聚合 SQL，避免全量明细搬运到前端
DashboardView 重构后破坏现有连接列表或最近活动交互	中	保留现有 store 和核心交互函数，仅将展示层重组并补充 summary 数据源

---

3. 技术设计

架构设计

flowchart LR
    A[DashboardView] --> B[dashboard.store]
    B --> C[/api/v1/dashboard/summary]
    C --> D[dashboard.controller]
    D --> E[dashboard.service]
    E --> F[(connections)]
    E --> G[(connection_tags)]
    E --> H[(audit_logs)]

API设计

GET /api/v1/dashboard/summary

• 请求: 无
• 响应:

{
  "totals": {
    "connections": 0,
    "activeConnections7d": 0,
    "taggedConnections": 0,
    "auditLogs": 0
  },
  "sshOutcomes24h": {
    "success": 0,
    "failure": 0
  },
  "connectionTypes": [
    { "type": "SSH", "count": 0 }
  ],
  "activityTrend7d": [
    { "date": "2026-03-25", "count": 0 }
  ],
  "topConnections": [
    { "connectionId": 1, "connectionName": "prod-1", "host": "1.2.3.4", "count": 8 }
  ]
}

数据模型

字段	类型	说明
totals.connections	number	连接总数
totals.activeConnections7d	number	最近 7 天内 last_connected_at 有值的连接数
totals.taggedConnections	number	至少绑定一个标签的连接数
totals.auditLogs	number	审计日志总数
sshOutcomes24h.success	number	24 小时内 SSH 成功次数
sshOutcomes24h.failure	number	24 小时内 SSH 失败次数
connectionTypes[]	{ type, count }[]	按连接类型统计
activityTrend7d[]	{ date, count }[]	近 7 天事件趋势
topConnections[]	{ connectionId, connectionName, host, count }[]	近期最活跃连接排行

---

4. 核心场景

场景: 首页快速判断系统活跃度

模块: frontend / backend 条件: 用户登录后进入首页仪表盘。 行为: 页面调用 summary 接口并展示总量卡片、近 7 天趋势和 24 小时 SSH 结果摘要。 结果: 用户无需进入连接页和审计页，就能快速判断近期使用情况与异常趋势。

场景: 从总览切换到具体操作

模块: frontend 条件: 用户在仪表盘查看高频连接、连接列表和最近活动。 行为: 用户可直接从连接列表发起连接，或从最近活动跳转到完整审计日志页。 结果: 仪表盘成为“总览 + 操作入口”的组合页，而非只读报表。

---

5. 技术决策

dashboard-management-cockpit#D001: 采用后端聚合 summary 接口，而不是前端多接口拼装

日期: 2026-03-25 状态: ✅采纳 背景: 管理驾驶舱需要同时展示总量、趋势、分布和排行。若继续依赖前端分别拉取连接列表和审计日志再本地聚合，首页逻辑会迅速变重，且趋势统计需要更多分页数据支撑。 选项分析:

选项	优点	缺点
A: 新增后端 summary 接口	首页只需一次请求，统计口径集中统一，前端组件更清晰	需要新增后端模块和类型定义
B: 前端继续基于 /connections 与 /audit-logs 本地聚合	不需要新增后端路由	首页需要管理更多请求和聚合逻辑，趋势/排行容易依赖不完整数据
决策: 选择方案A
理由: 这次需求明确是“管理驾驶舱版”而非轻量美化，后端聚合更适合承载统计口径和后续扩展。
影响: backend, frontend

dashboard-management-cockpit#D002: 首页统计只使用数据库稳定数据，不引入在线会话内存态

日期: 2026-03-25 状态: ✅采纳 背景: 在线会话数等实时指标需要额外打通 WebSocket 或运行时状态管理，而当前仓库首页并无现成只读接口。 选项分析:

选项	优点	缺点
A: 先基于连接表和审计日志做稳定指标	实现确定性高，口径清晰，适合本轮交付	暂不覆盖实时在线会话数
B: 额外引入内存会话态指标	指标更丰富	改动范围扩大，需处理跨进程/重启后一致性问题
决策: 选择方案A
理由: 用户当前核心诉求是“首页更像仪表盘”，稳定的趋势和资产统计优先级高于易漂移的瞬时在线数。
影响: backend, frontend

---

6. 成果设计

设计方向

• 美学基调: 延续现有后台控制台风格，但提升为更有层次的运营驾驶舱布局，强调信息密度和扫读效率
• 记忆点: 首页首屏以一排高对比统计卡片和双图表区形成明显“总览区”，不再像普通列表页
• 参考: 当前项目的卡片/边框/主题变量体系 + 运维控制台式信息编排

视觉要素

• 配色: 继续使用现有主题 token；通过不同强调色区分卡片状态，例如主色用于总量、绿色/红色用于 SSH 成功失败、蓝青色用于趋势图
• 字体: 沿用项目现有字体体系，避免引入与整体后台风格冲突的新字体
• 布局: 顶部四卡片总览，中部双栏图表，下部左侧活跃连接排行、右侧最近活动，连接列表保留为可操作区域
• 动效: 卡片和图表使用轻量渐进出现与 hover 反馈，避免夸张动画影响管理界面稳定感
• 氛围: 保留现有边框卡片语言，通过更清晰的区块分层、数据注释和图例提升专业感

技术约束

• 可访问性: 图表需要同时提供标题和数字文本，避免纯图形表达
• 响应式: 桌面端优先双栏布局，窄屏时需自然折叠为单栏