# 变更提案: dashboard-management-cockpit

## 元信息
```yaml
类型: 新功能
方案类型: implementation
优先级: P1
状态: 草稿
创建: 2026-03-25
```

---

## 1. 需求

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

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

### 约束条件
```yaml
时间约束: 本轮内完成前后端联动与基础构建验证
性能约束: 仪表盘首页统计应通过单个 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` 技术栈。

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

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

---

## 3. 技术设计

### 架构设计
```mermaid
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
- **请求**: 无
- **响应**:
```json
{
  "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 反馈，避免夸张动画影响管理界面稳定感
- **氛围**: 保留现有边框卡片语言，通过更清晰的区块分层、数据注释和图例提升专业感

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