nexus-terminal/.helloagents/archive/2026-03/202603260043_dashboard-live-session-metrics/proposal.md

变更提案: dashboard-live-session-metrics

元信息

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

---

1. 需求

背景

首页 dashboard 已经具备稳定统计能力，但仍缺少运行态视角。用户继续要求补“在线会话数/实时指标”，并明确选择“混合视角”，意味着首页同时需要展示当前登录用户的运行态会话信息，以及整个系统范围内的总在线会话概况。

目标

• 在现有 dashboard summary 基础上补充运行态指标，而不是另起一套接口。
• 同时展示“当前用户视角”和“系统总览视角”的在线 SSH / 挂起会话指标。
• 补充能体现实时性的附加指标，例如被监控中的活跃状态流数量，让首页更接近真实运维总控台。
• 保持首页首屏仍为单次 summary 请求，不要求前端直接订阅 WebSocket 状态。

约束条件

时间约束: 本轮内完成前后端联动与基础构建验证
性能约束: 运行态统计应在现有 dashboard summary 接口内组合返回，避免首页新增额外请求
兼容性约束: 不改变现有 workspace WebSocket 协议与挂起会话 API 语义
业务约束: 当前用户口径必须与后端登录态一致；系统口径必须来自后端共享运行态，而不是浏览器本地 session store 猜测

验收标准

• GET /api/v1/dashboard/summary 返回新增的 live metrics 字段
• 首页同时展示当前用户在线 SSH / 挂起会话数与系统总在线 SSH / 挂起会话数
• 首页补充至少一个与实时运行态有关的附加指标，例如当前活跃状态监控流数量
• 前端 UI 对新增实时指标完成中英日文案适配
• packages/backend 与 packages/frontend 构建通过

---

2. 方案

技术方案

延续现有 dashboard 业务域，但把运行态统计从纯数据库聚合扩展为“数据库统计 + 内存运行态组合”。数据库部分继续由 dashboard.repository.ts 提供稳定统计；运行态部分由 dashboard.service.ts 直接组合后端共享的 clientStates 与 sshSuspendService：前者提供系统范围和按当前 req.session.userId 过滤的在线 SSH 会话数量，并进一步统计处于状态监控中的会话数量；后者补充当前用户与系统范围的挂起会话数。前端沿用现有 dashboard.store.ts，在 DashboardOverviewPanel.vue 中新增“实时会话”板块，使用清晰的双列卡片同时呈现“我的会话”和“系统会话”。

影响范围

涉及模块:
  - backend: 扩展 dashboard summary 组合逻辑，补运行态统计
  - backend: 为 sshSuspendService 暴露系统级计数方法
  - frontend: 扩展 summary 类型与总览组件
  - frontend: 更新 dashboard 文案
预计变更文件: 6-9

风险评估

风险	等级	应对
前端本地 session store 与后端真实在线会话不一致	中	在线/挂起口径统一以后端运行态为准，只在首页展示后端汇总结果
clientStates 中可能包含正在恢复、挂起标记中或半断开的会话	中	统计时显式按状态字段过滤，优先统计未被服务接管的可用活跃会话
sshSuspendService 目前只有按用户列出接口，没有系统汇总接口	低	为服务补一个只读统计方法，不改现有对外 API

---

3. 技术设计

架构设计

flowchart LR
    A[DashboardController] --> B[DashboardService]
    B --> C[dashboard.repository.ts]
    B --> D[clientStates]
    B --> E[sshSuspendService]
    B --> F[req.session.userId]

API设计

GET /api/v1/dashboard/summary

• 新增响应字段:

{
  "liveMetrics": {
    "currentUser": {
      "activeSshSessions": 0,
      "suspendedSessions": 0
    },
    "system": {
      "activeSshSessions": 0,
      "suspendedSessions": 0,
      "statusStreams": 0
    }
  }
}

数据模型

字段	类型	说明
liveMetrics.currentUser.activeSshSessions	number	当前登录用户的活跃 SSH 会话数
liveMetrics.currentUser.suspendedSessions	number	当前登录用户的挂起会话数
liveMetrics.system.activeSshSessions	number	系统范围的活跃 SSH 会话数
liveMetrics.system.suspendedSessions	number	系统范围的挂起会话数
liveMetrics.system.statusStreams	number	当前处于状态轮询中的活跃会话数

---

4. 核心场景

场景: 当前用户查看自己的在线与挂起会话

模块: frontend / backend 条件: 用户已登录并打开首页 dashboard。 行为: 后端基于当前 session 的 userId 统计用户活跃 SSH 会话和挂起会话，并在首页实时会话面板中显示。 结果: 用户能快速判断“我当前开了多少会话、还有多少挂起会话待恢复”。

场景: 管理员查看系统整体运行态

模块: frontend / backend 条件: 首页 dashboard 已完成 summary 拉取。 行为: 后端同时返回系统总活跃 SSH 会话数、总挂起会话数和状态监控流数量。 结果: 首页能同时表达“我的视角”和“系统视角”，满足混合视角需求。

---

5. 技术决策

dashboard-live-session-metrics#D001: 运行态指标继续并入 summary 接口，而不是前端再建额外实时 API

日期: 2026-03-26 状态: ✅采纳 背景: 现有 dashboard 已经是单接口驱动。继续拆新接口只会增加首页请求数和前端状态拼装复杂度。 选项分析:

选项	优点	缺点
A: 扩展现有 /api/v1/dashboard/summary	首页保持单请求，口径集中，最适合当前仪表盘架构	service 层需同时组合数据库与运行态来源
B: 新增独立 /api/v1/dashboard/live	可把稳定统计和实时统计分离	首页需要二次请求和额外错误处理，前端复杂度上升
决策: 选择方案A
理由: 这轮增强是现有 dashboard 的自然延展，不值得拆出第二条首页专用链路。
影响: backend, frontend

dashboard-live-session-metrics#D002: 在线/挂起统计口径以后端运行态为准，不使用浏览器本地 session store 作为首页事实来源

日期: 2026-03-26 状态: ✅采纳 背景: 前端 session store 只能反映当前浏览器标签页，无法代表同一用户其他浏览器窗口、恢复中的会话或后端已接管的挂起状态。 选项分析:

选项	优点	缺点
A: 后端 clientStates + sshSuspendService 统一统计	口径统一，能同时覆盖系统和当前用户	需要后端 service 增加只读组合逻辑
B: 首页直接读前端 session.store	实现快	只能看到当前浏览器局部状态，无法满足混合视角
决策: 选择方案A
理由: 用户明确要“当前用户 + 系统总览”混合视角，只能以后端运行态作为事实源。
影响: backend, frontend

---

6. 成果设计

设计方向

• 美学基调: 保持现有 dashboard 驾驶舱风格，但把运行态指标做成更“控制台式”的双层面板
• 记忆点: 首页同时出现“我的会话 / 系统会话”两组清晰分栏，不再只有静态总量
• 参考: 当前 dashboard 卡片体系 + 运维控制台常见的 live session summary

视觉要素

• 配色: 当前用户指标偏主色和绿色，系统总览指标偏青蓝和琥珀，避免与稳定总量卡片混淆
• 字体: 沿用现有项目后台字体体系
• 布局: 运行态指标独立为一块 summary panel，位于统计卡片区之后、图表区之前
• 动效: 只保留轻量 hover 和数字层级，不增加复杂动画
• 氛围: 强调“控制面板”而非“报表页”，以密度和清晰分组为主

技术约束

• 可访问性: 每个实时指标必须带文字标签，不用纯 icon 表达
• 响应式: 窄屏下“当前用户 / 系统总览”两组指标要能自然折叠为单栏