1
0

feat: 前端指标体系增强 — Dashboard/Metrics API、2×4 统计区、趋势图面积+异常标记、连续状态列

- 新增 GET /api/dashboard 合并原 summary+targets 首屏接口
- 新增 GET /api/targets/:id/metrics 合并原 stats+trend 概览接口
- 后端指标纯函数:可用率、百分位、故障段分析、连续状态、UTC 小时分桶
- ProbeStore 窗口取数方法替代全量历史查询
- SummaryCards 扩展为 4 卡片(新增异常事件数)+ 数据新鲜度展示
- 表格新增「连续」列(Tag 渲染 capped 状态)
- OverviewTab 重构为 2×4 Statistic 多维度布局
- TrendChart 改为延迟范围面积图 + 红色异常标记点
- 删除旧路由(summary/targets/trend)和 computeTrendStats
- 同步 delta specs 到主 specs 并归档变更
This commit is contained in:
2026-05-14 12:32:41 +08:00
parent e983e5d75d
commit 1c5cfafda6
47 changed files with 1768 additions and 1231 deletions

View File

@@ -1,6 +1,6 @@
## Purpose
定义目标详情 Drawer时间范围筛选TDesign RadioGroup + DateRangePicker、Tabs 组织概览/记录两个面板、统计图表和分页检查结果列表。
定义目标详情 Drawer时间范围筛选TDesign RadioGroup + DateRangePicker,含快捷按钮联动概览和记录面板、Tabs 组织概览/记录两个面板、Metrics 数据查询 Hook、多维度统计图表2×4 布局)和分页检查结果列表。
## Requirements
@@ -36,19 +36,19 @@ Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer展示
- **THEN** 时间选择器、Tabs 等区块之间的间距 SHALL 通过 TDesign Space 组件direction="vertical", size={16})统一管理,不使用内联 style 的 marginBottom
### Requirement: 概览面板组件化
概览 Tab SHALL 作为独立组件 `OverviewTab` 实现,接收数据 props 进行渲染
概览 Tab SHALL 作为独立组件 `OverviewTab` 实现,展示多维度统计、趋势图、状态分布和基本信息
#### Scenario: OverviewTab 组件职责
- **WHEN** 概览 Tab 渲染
- **THEN** `OverviewTab` 组件 SHALL 负责统计卡片、趋势图、状态分布环形图和基本信息的渲染
- **THEN** `OverviewTab` 组件 SHALL 负责多维度统计卡片2×4 布局)、趋势图(延迟范围面积图+异常标记点)、状态分布环形图和基本信息的渲染
#### Scenario: 统计计算使用纯函数
- **WHEN** OverviewTab 需要计算 totalChecks、upChecks、downChecks
- **THEN** 计算逻辑 SHALL 通过 `utils/stats.ts` 中的纯函数实现,并使用 `useMemo` 缓存结果
#### Scenario: 统计计算不再使用 computeTrendStats
- **WHEN** OverviewTab 需要 totalChecks、upChecks、downChecks
- **THEN** SHALL 直接使用 metricsData.stats 中的 totalChecks、upChecks、downChecks 字段,`computeTrendStats` 工具函数 SHALL 被删除
#### Scenario: OverviewTab props
- **WHEN** OverviewTab 渲染
- **THEN** 组件 SHALL 接收 `target: TargetStatus``trendData: TrendPoint[]``trendLoading: boolean` 作为 props
- **THEN** 组件 SHALL 接收 `target: TargetStatus``metricsData: TargetMetricsResponse | null``metricsLoading: boolean` 作为 props
### Requirement: 记录面板组件化
记录 Tab SHALL 作为独立组件 `HistoryTab` 实现。
@@ -94,6 +94,29 @@ StatusBar 组件 SHALL 支持可配置的格数。
- **WHEN** StatusBar 渲染且 samples 数量少于 maxSlots
- **THEN** 多余的格子 SHALL 显示为 empty 状态
### Requirement: Metrics 数据查询 Hook
系统 SHALL 提供 `useTargetMetrics` hook 查询单目标指标数据。
#### Scenario: metrics queryKey
- **WHEN** 查询某目标的指标数据
- **THEN** queryKey SHALL 为 ["metrics", targetId, from, to, bucket]
#### Scenario: metrics 条件查询
- **WHEN** 用户未选中任何目标
- **THEN** metrics 的 useQuery SHALL enabled=false不发起请求
#### Scenario: metrics 数据返回
- **WHEN** metrics 查询成功
- **THEN** hook SHALL 返回 `TargetMetricsResponse` 类型数据
#### Scenario: 时间范围变化时重新请求
- **WHEN** 用户更改时间范围
- **THEN** metrics 的 useQuery SHALL 因 queryKey 变化自动重新请求
#### Scenario: Drawer 关闭清理查询缓存
- **WHEN** 用户关闭 Drawer
- **THEN** 系统 MAY 清理 metrics 和 history 查询缓存,避免旧目标数据残留
### Requirement: 时间范围选择器
Drawer SHALL 在 Tabs 外层提供时间范围选择器,影响概览和记录两个面板的数据。时间选择器 SHALL 分两行显示:第一行为快捷按钮,第二行为日期时间范围选择器。
@@ -105,6 +128,14 @@ Drawer SHALL 在 Tabs 外层提供时间范围选择器,影响概览和记录
- **WHEN** 用户点击快捷按钮(如 "24小时"
- **THEN** 系统 SHALL 自动设置对应的起止时间DateRangePicker 显示对应的时间范围,该按钮高亮
#### Scenario: 快捷按钮联动统计区
- **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
- **THEN** 概览面板 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/metrics` 数据
#### Scenario: 快捷按钮联动历史记录
- **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
- **THEN** 记录面板 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/history` 数据,并重置页码为 1
#### Scenario: 自定义日期时间范围
- **WHEN** 用户通过 TDesign DateRangePickermode=date, enableTimePicker, format="YYYY-MM-DD HH:mm")修改时间范围
- **THEN** 快捷按钮 SHALL 取消高亮,系统重新请求对应时间范围的数据
@@ -137,31 +168,67 @@ Drawer 内部 SHALL 使用 TDesign Tabs 组织概览和记录两个面板。TabP
- **THEN** TabPanel SHALL 通过 `className` prop 传入自定义类名(`tab-panel-padded`)控制内边距,不通过入侵 TDesign 内部类名(`.t-tab-panel`)覆盖
### Requirement: 概览面板
概览 Tab SHALL 按区域展示目标统计摘要、趋势图、状态分布和基本信息,每个区域使用 TDesign Divider 组件作为小标题分隔
概览 Tab SHALL 按区域展示多维度统计、趋势图、状态分布和基本信息。
#### Scenario: 区域排列顺序
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 按以下顺序展示区域:统计 → 趋势 → 状态分布 → 基本信息,每个区域前 SHALL 显示 TDesign Divideralign="left")作为小标题,不使用内联 style 的 h4 标签
- **THEN** 面板 SHALL 按以下顺序展示区域:统计 → 趋势 → 状态分布 → 基本信息,每个区域前 SHALL 显示 TDesign Divideralign="left")作为小标题
#### Scenario: 区域间距
#### Scenario: 统计区多维度布局
- **WHEN** 概览面板渲染
- **THEN** 各区域之间的间距 SHALL 通过 TDesign Space 组件direction="vertical")统一管理,不使用内联 style 的 margin
- **THEN** 面板 SHALL 在"统计"区域使用 2 行 × 4 列的 TDesign Row/Col + Statistic 布局第一行为可用率suffix="%"、平均延迟suffix="ms"、P95 延迟suffix="ms")、检查总数;第二行为 MTTR动态单位、最长故障动态单位、故障次数suffix="次"、连续正常suffix="次",固定标题"连续正常",当目标当前处于异常状态时值为 0
#### Scenario: 统计数值卡片
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 在"统计"区域使用 TDesign Statistic 组件展示 4 个统计值总检查color=blue、正常color=green、异常color=red、可用率color=green, suffix="%"),使用 TDesign Row/Col 横向排列。Row 的外层间距 SHALL 通过 TDesign Space 或 CSS 类控制,不使用内联 style
#### Scenario: P99 暂不展示
- **WHEN** metricsData.stats 包含 p99DurationMs
- **THEN** 当前 2×4 统计区 SHALL 不展示 P99 延迟
#### Scenario: 趋势折线图
- **WHEN** 概览面板渲染且趋势数据可用
- **THEN** 面板 SHALL 在"趋势"区域展示 recharts 双 Y 轴折线图TrendChart耗时线--td-brand-color和可用率线--td-success-color
#### Scenario: MTTR 和最长故障动态单位
- **WHEN** MTTR 或最长故障值小于 60000ms
- **THEN** SHALL 以秒为单位展示suffix="秒"
- **WHEN** 值大于等于 60000ms 且小于 3600000ms
- **THEN** SHALL 以分钟为单位展示suffix="分钟"
- **WHEN** 值大于等于 3600000ms
- **THEN** SHALL 以小时为单位展示suffix="小时"
#### Scenario: 统计区数据来源
- **WHEN** 统计区渲染
- **THEN** 第一行和第二行数据 SHALL 来自 metricsData.stats
#### Scenario: 统计区加载状态
- **WHEN** metricsData 正在加载
- **THEN** 统计区 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 统计区无数据
- **WHEN** metricsData 为 null 且未处于加载状态
- **THEN** 统计区 SHALL 展示占位状态,不从其他数据源反推统计值
#### Scenario: 延迟类指标无数据
- **WHEN** metricsData.stats 中 avgDurationMs 或 p95DurationMs 为 null
- **THEN** 对应 Statistic SHALL 展示值为 0 且不带单位后缀TDesign Statistic value 仅接受 number无数据时通过缺省 suffix 区分)
#### Scenario: 趋势图延迟范围面积
- **WHEN** 概览面板渲染且 metricsData.trend 可用
- **THEN** 趋势图 SHALL 使用 recharts Area 组件渲染 minDurationMs 到 maxDurationMs 的延迟范围(半透明品牌色填充),叠加 avgDurationMs 实线
#### Scenario: 趋势图时间轴标签本地化
- **WHEN** 趋势图渲染 X 轴标签
- **THEN** 前端 SHALL 使用 `toLocaleTimeString` 或等价方法将 UTC `bucketStart` 转换为本地时间标签(如 "08:00"),不直接展示 UTC 时间字符串
#### Scenario: 趋势图异常标记点
- **WHEN** metricsData.trend 中某小时的 availability < 100
- **THEN** 趋势图 SHALL 在 avgDurationMs 线上该时间点渲染红色圆点fill: var(--td-error-color)),使用 recharts Line 的 dot 回调函数实现;图表 SHALL 仅保留左侧 Y 轴ms移除右侧 Y 轴(%)和 availability 折线
#### Scenario: 趋势数据加载中
- **WHEN** 概览面板渲染且趋势数据正在加载
- **WHEN** metricsData 正在加载
- **THEN** "趋势"区域 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 状态分布环形图
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 在"状态分布"区域展示 recharts 环形图StatusDonut外圈显示 UP/DOWN 比例,中间显示可用率百分比
- **WHEN** 概览面板渲染且 metricsData 可用
- **THEN** 面板 SHALL 在"状态分布"区域展示 recharts 环形图StatusDonut使用 metricsData.stats.upChecks 和 metricsData.stats.downChecks 作为数据源,外圈显示 UP/DOWN 比例,中间显示可用率百分比
#### Scenario: 状态分布加载状态
- **WHEN** metricsData 正在加载
- **THEN** 状态分布区域 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 元信息展示
- **WHEN** 概览面板渲染