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:
@@ -1,2 +0,0 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-13
|
||||
@@ -1,147 +0,0 @@
|
||||
## Context
|
||||
|
||||
DiAL 是一个基于 Bun 的全栈拨测监控系统，当前前端统计指标体系存在以下问题：
|
||||
|
||||
1. **计算逻辑缺陷**：可用率基于全量历史数据计算（`store.ts:getAllTargetStats` 无 WHERE 时间条件），随运行时间增长近期变化被稀释；`computeTrendStats` 从已截断的百分比反推整数有累积精度损失；`lastCheckTime` 已返回但前端未展示
|
||||
2. **指标维度单一**：Summary 仅 3 个计数卡片；Drawer 统计区 4 个指标（总检查/正常/异常/可用率）本质是同一维度的冗余表达
|
||||
3. **缺少关键运维指标**：无 P95 延迟、无 MTTR、无故障分析、无连续状态信息
|
||||
|
||||
当前技术栈：后端 Bun + SQLite（bun:sqlite），前端 React + TDesign + recharts + TanStack Query。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 修复可用率时间窗口、趋势数据精度损失、lastCheckTime 未展示三个计算逻辑问题
|
||||
- Summary 增加「24h 异常事件数」卡片
|
||||
- 表格增加「连续状态」列（Tag 样式，按次数）
|
||||
- Drawer 统计区重构为 2×4 多维度布局（可用率/平均延迟/P95/检查总数 + MTTR/最长故障/故障次数/连续正常）
|
||||
- 趋势图增加延迟范围面积（min/max），去掉可用率线改为异常时刻红色标记点
|
||||
- 新增 `/api/targets/:id/stats` 端点，职责清晰（单目标非时序聚合指标）
|
||||
- Drawer 统计区支持时间窗口切换（24h/7d/30d），联动统计+趋势
|
||||
|
||||
**Non-Goals:**
|
||||
- 不做整体可用率（不同分组不同目的的 target 算到一起无意义）
|
||||
- 不做延迟 sparkline（表格已有状态条，信息密度够了）
|
||||
- 不做趋势对比（vs 上周）
|
||||
- 不做连续状态按时长展示（不同间隔的目标无法统一）
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1：P95 在应用层计算，不在 SQL 层
|
||||
|
||||
**选择**：新增 `getTargetDurations(targetId, from, to)` 方法，一次性取出时间窗口内所有成功检查的 `duration_ms`，在 TypeScript 层排序取 P95/P99。
|
||||
|
||||
**理由**：SQLite 无原生 PERCENTILE 函数，用子查询模拟的 SQL 复杂且性能不可控。应用层排序对于单目标时间窗口内的数据量（24h × 每分钟 1 次 = 1440 条）完全可接受。
|
||||
|
||||
**替代方案**：SQLite 扩展函数 / 窗口函数模拟 — 复杂度高，可移植性差。
|
||||
|
||||
**命名**：方法名统一为 `getTargetDurations`（非 `getTargetPercentiles`），因为该方法职责是取原始数据，百分位计算在调用方完成。
|
||||
|
||||
### Decision 2：新增独立 `/api/targets/:id/stats` 端点
|
||||
|
||||
**选择**：创建新端点而非扩展现有 `/api/targets/:id/trend`。
|
||||
|
||||
**理由**：
|
||||
- `/trend` 的职责是时序聚合数据（按小时分组），返回数组
|
||||
- `/stats` 的职责是非时序聚合指标（P95、MTTR、故障分析），返回单个对象
|
||||
- 两者语义清晰，避免一个大而全的端点
|
||||
- `/stats` 只在 Drawer 打开时请求，不影响列表页性能
|
||||
|
||||
**替代方案**：扩展 `/trend` 在响应中附加 summary 字段 — 混淆了时序和聚合两种数据语义。
|
||||
|
||||
### Decision 3：异常事件数按「状态翻转」计数
|
||||
|
||||
**选择**：统计 `matched` 从 1→0 的转换次数（跨所有目标），而非每次 `matched=0` 的检查次数。
|
||||
|
||||
**理由**：一个目标连续异常 10 次只算 1 次事件，反映的是「发生了几次故障」而非「有多少次检查失败」。后者已经在可用率中体现。
|
||||
|
||||
**实现**：SQL 使用 LAG 窗口函数检测前后状态变化：
|
||||
```sql
|
||||
SELECT COUNT(*) FROM (
|
||||
SELECT matched, LAG(matched) OVER (PARTITION BY target_id ORDER BY timestamp) as prev
|
||||
FROM check_results WHERE timestamp >= ?
|
||||
) WHERE matched = 0 AND (prev = 1 OR prev IS NULL)
|
||||
```
|
||||
|
||||
### Decision 4：连续状态从 recentSamples 前端计算
|
||||
|
||||
**选择**：不新增 API，从已有的 `recentSamples`（30 条）在前端计算连续状态次数。
|
||||
|
||||
**理由**：
|
||||
- `recentSamples` 已经按时间倒序返回，遍历到第一个状态不同的即可
|
||||
- 无需额外网络请求
|
||||
- 30 条样本对于连续状态计数足够（超过 30 次连续正常/异常的场景下，显示 "30+" 即可）
|
||||
|
||||
### Decision 5：趋势图去掉可用率线，改为异常标记点
|
||||
|
||||
**选择**：移除 availability 折线和右侧 Y 轴（%），改为单 Y 轴（ms）。在 avgDurationMs 线上，对 availability < 100 的时间点渲染红色 dot 标记异常。
|
||||
|
||||
**理由**：可用率通常是 100% 或接近 100%，作为连续曲线信息量极低（大部分时间是一条直线）。改为离散标记点后，异常时刻一目了然，且不占用 Y 轴空间。
|
||||
|
||||
**实现**：使用 recharts `<Line>` 的 `dot` 回调函数，对 `availability < 100` 的点渲染红色圆点（`fill: var(--td-error-color)`），其余点不渲染 dot。移除右侧 Y 轴和 availability Line 组件。
|
||||
|
||||
### Decision 6：时间窗口切换联动机制
|
||||
|
||||
**选择**：Drawer 中的时间窗口切换同时影响统计区和趋势图，stats 和 trend 同时刷新。
|
||||
|
||||
**实现**：
|
||||
- stats 请求直接复用 Drawer 现有的 `timeFrom`/`timeTo` 状态，不引入额外时间状态
|
||||
- 统计区数据来自 `/api/targets/:id/stats?from=&to=`
|
||||
- 趋势图数据来自 `/api/targets/:id/trend?from=&to=`
|
||||
- 切换快捷按钮（1h/6h/24h/7d）时，`timeFrom`/`timeTo` 更新，stats 和 trend 的 queryKey 变化触发同时刷新
|
||||
- 默认选中 24h
|
||||
- 表格的可用率固定 24h 窗口：前端 `useTargets` 请求 `/api/targets?window=24h`，后端解析 `window` 查询参数并转换为时间范围传递给 `getAllTargetStats(from, to)`，列标题改为"可用率(24h)"
|
||||
|
||||
### Decision 7：Drawer 统计区 2×4 布局
|
||||
|
||||
**选择**：统计区和可靠性区合并为一个 2 行 × 4 列的 Statistic 网格。
|
||||
|
||||
```
|
||||
┌────────────┬────────────┬────────────┬────────────┐
|
||||
│ 可用率 │ 平均延迟 │ P95延迟 │ 检查总数 │
|
||||
├────────────┼────────────┼────────────┼────────────┤
|
||||
│ MTTR │ 最长故障 │ 故障次数 │ 连续正常 │
|
||||
└────────────┴────────────┴────────────┴────────────┘
|
||||
```
|
||||
|
||||
**理由**：原来的「总检查/正常/异常/可用率」4 指标信息冗余，正常/异常计数已在环形图中展示。重构后每个格子都是独立维度，信息密度大幅提升。
|
||||
|
||||
### Decision 8：TrendPoint 增加 min/max 延迟字段
|
||||
|
||||
**选择**：在 SQL 聚合层直接计算 `MIN(duration_ms)` 和 `MAX(duration_ms)`，零额外成本。
|
||||
|
||||
**实现**：趋势图使用 recharts `<Area>` 组件渲染 min-max 范围（半透明品牌色填充），叠加 avg 实线。
|
||||
|
||||
### Decision 9：Summary lastCheckTime 展示为相对时间
|
||||
|
||||
**选择**：在 Summary 区域底部展示 "最后更新: X秒前" 文本，前端每秒更新。
|
||||
|
||||
**实现**：使用 `useState` + `setInterval` 每秒计算相对时间差。超过 60 秒时文字变为警告色（--td-warning-color），提示数据可能不新鲜。
|
||||
|
||||
### Decision 10：StatusDonut 数据来源改为 statsData
|
||||
|
||||
**选择**：StatusDonut 的 `up`/`down` 改为使用 `statsData.upChecks` / `statsData.downChecks`，不再从 trendData 反推。
|
||||
|
||||
**理由**：statsData 的 upChecks 是精确值（直接从 SQL COUNT 返回），与统计区的"检查总数"一致，消除了之前从百分比反推的精度损失。
|
||||
|
||||
**影响**：`computeTrendStats` 工具函数不再有调用方，直接删除。
|
||||
|
||||
### Decision 11：MTTR 窗口边界截断处理
|
||||
|
||||
**选择**：如果时间窗口内第一条记录即为 matched=0（故障跨越了 from 边界），该故障段不计入 MTTR 平均值，但计入 incidentCount。
|
||||
|
||||
**理由**：无法确定故障的真实开始时间，计入 MTTR 会低估实际恢复时间。incidentCount 计数是因为用户确实在窗口内经历了这次故障。
|
||||
|
||||
### Decision 12：getIncidents24h 作为独立方法
|
||||
|
||||
**选择**：`getIncidents24h()` 是 ProbeStore 的独立方法（单条 SQL），在 `handleSummary` 路由中调用并附加到响应。
|
||||
|
||||
**理由**：职责分离，getSummary() 保持原有的目标状态快照逻辑，incidents24h 是独立的时序分析查询。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[P95 数据量]** 30d 窗口下单目标可能有 ~43200 条记录需要排序 → 对于内存排序仍然可接受（<1MB），但如果未来数据量增长可考虑近似算法
|
||||
- **[异常事件计数的 LAG 查询]** 窗口函数在大数据量下可能较慢 → 24h 窗口内数据量有限（所有目标 × 24h ÷ 间隔），可接受；如果性能不佳可改为应用层遍历
|
||||
- **[前端连续状态上限 30]** recentSamples 固定 30 条，连续状态超过 30 次时显示 "30+" → 对于运维场景足够，真正需要精确值时可查看 Drawer 详情
|
||||
- **[趋势图去掉可用率线]** 用户可能习惯看可用率曲线 → 异常标记点提供了等价信息且更直观，环形图仍展示可用率分布
|
||||
- **[LAG 窗口边界误差]** 使用 LAG 窗口函数检测状态翻转时，若故障跨越时间窗口 from 边界（窗口内第一条即为 matched=0），会被计为一次新事件，实际可能是窗口外已开始的故障延续 → 对于 24h 窗口内的事件计数，该误差可接受且难以避免（需要额外查询窗口外数据才能消除）
|
||||
@@ -1,33 +0,0 @@
|
||||
## Why
|
||||
|
||||
当前前端统计指标存在三个层面的问题：（1）计算逻辑缺陷——可用率无时间窗口导致历史数据稀释近期变化、`computeTrendStats` 从百分比反推整数有精度损失、`lastCheckTime` 返回但未展示；（2）指标维度单一——Summary 只有计数、Drawer 统计区 4 个指标本质是同一维度的重复表达、表格缺少连续状态等关键运维信息；（3）缺少性能和可靠性指标——无 P95 延迟、无 MTTR、无故障分析。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **计算逻辑修复**：可用率查询增加时间窗口参数（默认 24h）；Trend API 直接返回 `upChecks` 消除前端反推精度损失；Summary 展示 `lastCheckTime` 相对时间
|
||||
- **Summary 增强**：新增第 4 张卡片「24h 异常事件数」（状态翻转计数）
|
||||
- **表格增强**：新增「连续状态」列，Tag 样式展示连续正常/异常次数
|
||||
- **Drawer 统计区重构**：从冗余的 4 指标改为多维度布局（可用率 / 平均延迟 / P95 延迟 / 检查总数），支持时间窗口切换（24h/7d/30d）联动
|
||||
- **Drawer 可靠性区块**：新增 MTTR / 最长故障 / 故障次数 / 连续正常 4 个指标，与统计区合并为 2×4 布局
|
||||
- **趋势图增强**：增加延迟范围面积图（min/max），去掉可用率线改为异常时刻红色标记点
|
||||
- **新增 Stats API**：`GET /api/targets/:id/stats` 端点，返回 P95（应用层排序计算）、MTTR、故障分析等深度统计
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `target-stats-api`: 单目标深度统计 API 端点，提供 P95/P99 延迟、MTTR、故障分析等非时序聚合指标
|
||||
|
||||
### Modified Capabilities
|
||||
- `probe-api`: Summary API 增加 `incidents24h` 字段；Targets API 可用率改为固定 24h 窗口；Trend API 增加 `upChecks`/`minDurationMs`/`maxDurationMs` 字段
|
||||
- `probe-data-store`: `getAllTargetStats`/`getTargetStats` 增加时间窗口参数；`getTrend` 增加 min/max 聚合；新增异常事件计数和检查序列查询方法
|
||||
- `probe-dashboard`: Summary Cards 从 3 张扩展为 4 张，增加 `lastCheckTime` 展示
|
||||
- `target-table`: 新增「连续状态」列（Tag 样式），可用率列标题改为"可用率(24h)"
|
||||
- `target-detail-drawer`: 概览面板统计区重构为 2×4 多维度布局，趋势图改为延迟范围面积图+异常标记点，删除 computeTrendStats，StatusDonut 数据来源改为 statsData
|
||||
|
||||
## Impact
|
||||
|
||||
- **后端**：`src/server/checker/store.ts` 增加带时间窗口的查询方法和新统计方法；新增 `src/server/routes/stats.ts` 路由
|
||||
- **共享类型**：`src/shared/api.ts` 扩展 `SummaryResponse`、`TargetStatus`、`TrendPoint`，新增 `TargetStatsResponse` 类型
|
||||
- **前端组件**：`SummaryCards`、`OverviewTab`、`TrendChart`、`target-table-columns` 均需修改；新增连续状态 Tag 组件
|
||||
- **前端工具**：`utils/stats.ts` 的 `computeTrendStats` 删除（不再有调用方）
|
||||
- **API 端点**：新增 `/api/targets/:id/stats`；修改 `/api/summary`、`/api/targets`、`/api/targets/:id/trend` 的响应结构
|
||||
@@ -1,53 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 总览统计 API
|
||||
系统 SHALL 提供 `GET /api/summary` 端点，返回所有目标的总体统计信息，包含异常事件计数。
|
||||
|
||||
#### Scenario: 获取总览统计
|
||||
- **WHEN** 客户端请求 `GET /api/summary`
|
||||
- **THEN** 系统 SHALL 返回 JSON 包含 total（总目标数）、up（正常数）、down（异常数）、lastCheckTime（最近一次检查时间）、incidents24h（过去 24 小时内的异常事件数，按状态翻转计数）
|
||||
|
||||
#### Scenario: 异常事件计数逻辑
|
||||
- **WHEN** 计算 incidents24h
|
||||
- **THEN** 系统 SHALL 统计过去 24 小时内所有目标中 matched 从 1 变为 0 的状态翻转次数；时间窗口起始即为 matched=0 且无前序记录的情况 SHALL 计为 1 次事件
|
||||
|
||||
### Requirement: 目标列表 API
|
||||
系统 SHALL 提供 `GET /api/targets` 端点，返回所有 typed target 及其最新状态、分组信息和结构化采样数据，可用率基于 window 查询参数指定的时间窗口计算。
|
||||
|
||||
#### Scenario: 获取目标列表
|
||||
- **WHEN** 客户端请求 `GET /api/targets?window=24h`
|
||||
- **THEN** 系统 SHALL 解析 window 参数（支持格式如 "24h"、"7d"），将其转换为时间范围，返回 JSON 数组，每个元素的 stats.availability 和 stats.totalChecks SHALL 基于该时间窗口的数据计算
|
||||
|
||||
#### Scenario: window 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets` 未提供 window 参数
|
||||
- **THEN** 系统 SHALL 默认使用 24h 时间窗口
|
||||
|
||||
#### Scenario: 目标无历史记录
|
||||
- **WHEN** 某目标尚未执行过任何拨测
|
||||
- **THEN** 其 latestCheck 为 null，recentSamples 为空数组，stats.availability 为 0
|
||||
|
||||
### Requirement: 趋势 API 支持时间范围
|
||||
系统 SHALL 提供 `GET /api/targets/:id/trend` 端点，返回包含延迟范围和正常检查数的趋势数据。
|
||||
|
||||
#### Scenario: 指定时间范围查询趋势
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/trend?from=ISO&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回指定时间范围内按小时分组的聚合数据，每个数据点包含 hour、avgDurationMs、minDurationMs、maxDurationMs、availability、totalChecks、upChecks
|
||||
|
||||
#### Scenario: from 或 to 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/trend` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
### Requirement: 新增共享类型
|
||||
系统 SHALL 在 `src/shared/api.ts` 中定义扩展后的 `SummaryResponse`、`TrendPoint` 和 `TargetStats` 类型。
|
||||
|
||||
#### Scenario: SummaryResponse 类型
|
||||
- **WHEN** 前后端共享 `SummaryResponse` 类型
|
||||
- **THEN** 该类型 SHALL 包含 `total: number`、`up: number`、`down: number`、`lastCheckTime: string | null`、`incidents24h: number` 字段
|
||||
|
||||
#### Scenario: TrendPoint 类型
|
||||
- **WHEN** 前后端共享 `TrendPoint` 类型
|
||||
- **THEN** 该类型 SHALL 包含 `hour: string`、`avgDurationMs: number | null`、`minDurationMs: number | null`、`maxDurationMs: number | null`、`availability: number`、`totalChecks: number`、`upChecks: number` 字段
|
||||
|
||||
#### Scenario: TargetStats 类型
|
||||
- **WHEN** 前后端共享 `TargetStats` 类型
|
||||
- **THEN** 该类型 SHALL 包含 `availability: number`、`totalChecks: number` 字段（语义变更为基于时间窗口计算）
|
||||
@@ -1,20 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 总览统计卡片
|
||||
Dashboard SHALL 在页面顶部使用 TDesign Statistic 组件展示总览统计，包含总目标数、正常数、异常数和 24h 异常事件数，并展示数据新鲜度。
|
||||
|
||||
#### Scenario: 展示统计卡片
|
||||
- **WHEN** 用户打开 Dashboard 页面
|
||||
- **THEN** 页面顶部 SHALL 使用 TDesign Row/Col 布局展示 4 个 TDesign Card + Statistic 组合：全部目标数（color=blue）、正常目标数（color=green）、异常目标数（color=red）、24h 异常事件数（color=orange）
|
||||
|
||||
#### Scenario: 展示数据新鲜度
|
||||
- **WHEN** Summary 数据包含 lastCheckTime
|
||||
- **THEN** 统计卡片行底部 SHALL 展示相对时间文本（如"最后更新: 3秒前"），使用 TDesign Typography.Text（theme="secondary"）
|
||||
|
||||
#### Scenario: 数据新鲜度警告
|
||||
- **WHEN** lastCheckTime 距当前时间超过 60 秒
|
||||
- **THEN** 相对时间文本 SHALL 使用警告色（--td-warning-color）
|
||||
|
||||
#### Scenario: 统计数据自动刷新
|
||||
- **WHEN** 页面处于打开状态
|
||||
- **THEN** 统计卡片 SHALL 通过 TanStack Query 的 refetchInterval=8000 自动刷新数据
|
||||
@@ -1,80 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 聚合查询支持
|
||||
数据存储 SHALL 支持按时间段聚合查询，用于计算可用率、平均耗时、延迟范围等统计指标。所有聚合查询 SHALL 支持时间窗口参数。
|
||||
|
||||
#### Scenario: 计算目标可用率（带时间窗口）
|
||||
- **WHEN** 查询某目标在指定时间范围内的可用率
|
||||
- **THEN** 系统 SHALL 返回该时间范围内 matched=1 的记录数占总记录数的百分比
|
||||
|
||||
#### Scenario: 计算目标平均耗时
|
||||
- **WHEN** 查询某目标在指定时间范围内的平均耗时
|
||||
- **THEN** 系统 SHALL 返回 duration_ms 的平均值（仅计算 matched=1 的记录）
|
||||
|
||||
#### Scenario: 按小时聚合趋势数据（含延迟范围）
|
||||
- **WHEN** 查询某目标在指定时间范围内的趋势数据
|
||||
- **THEN** 系统 SHALL 返回按小时分组的聚合数据，包括每小时的 avgDurationMs、minDurationMs（成功检查的最小延迟）、maxDurationMs（成功检查的最大延迟）、availability、totalChecks、upChecks
|
||||
|
||||
#### Scenario: UP/DOWN 判定
|
||||
- **THEN** 系统 SHALL 基于 latestCheck.matched 判定目标 UP 或 DOWN：matched=true 为 UP，matched=false 为 DOWN
|
||||
|
||||
### Requirement: 目标统计查询支持时间窗口
|
||||
`getAllTargetStats` 和 `getTargetStats` SHALL 接受可选的时间窗口参数，限制聚合的数据范围。
|
||||
|
||||
#### Scenario: 带时间窗口的批量统计
|
||||
- **WHEN** 调用 `getAllTargetStats(from, to)`
|
||||
- **THEN** 系统 SHALL 仅聚合 timestamp 在 from 到 to 范围内的 check_results 记录
|
||||
|
||||
#### Scenario: 不传时间窗口
|
||||
- **WHEN** 调用 `getAllTargetStats()` 不传时间参数
|
||||
- **THEN** 系统 SHALL 默认使用过去 24 小时作为时间窗口
|
||||
|
||||
#### Scenario: 带时间窗口的单目标统计
|
||||
- **WHEN** 调用 `getTargetStats(targetId, from, to)`
|
||||
- **THEN** 系统 SHALL 仅聚合指定时间范围内的记录
|
||||
|
||||
### Requirement: 趋势数据时间范围查询
|
||||
系统 SHALL 支持按任意时间范围查询趋势聚合数据，返回包含延迟范围和正常检查数的完整聚合。
|
||||
|
||||
#### Scenario: 按时间范围查询趋势（含延迟范围）
|
||||
- **WHEN** 查询指定 target 在 from 到 to 时间范围内的趋势数据
|
||||
- **THEN** 系统 SHALL 返回按小时分组的聚合数据，每个数据点包含 hour、avgDurationMs、minDurationMs、maxDurationMs、availability、totalChecks、upChecks
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 异常事件计数查询
|
||||
ProbeStore SHALL 提供 `getIncidents24h()` 方法，统计过去 24 小时内所有目标的异常事件数。
|
||||
|
||||
#### Scenario: 计算异常事件数
|
||||
- **WHEN** 调用 `getIncidents24h()`
|
||||
- **THEN** 系统 SHALL 统计过去 24 小时内所有目标中 matched 从 1 变为 0 的状态翻转次数
|
||||
|
||||
#### Scenario: 窗口起始即为故障
|
||||
- **WHEN** 某目标在 24 小时窗口内第一条记录为 matched=0 且窗口前无记录
|
||||
- **THEN** 该故障 SHALL 计为 1 次事件
|
||||
|
||||
#### Scenario: 连续异常只计一次
|
||||
- **WHEN** 某目标连续 10 次 matched=0
|
||||
- **THEN** 该连续异常段 SHALL 仅计为 1 次事件
|
||||
|
||||
### Requirement: 目标延迟百分位查询
|
||||
ProbeStore SHALL 提供 `getTargetDurations(targetId, from, to)` 方法，返回时间窗口内所有成功检查的 duration_ms 数组。
|
||||
|
||||
#### Scenario: 获取延迟数据
|
||||
- **WHEN** 调用 `getTargetDurations(targetId, from, to)`
|
||||
- **THEN** 系统 SHALL 返回该目标在时间范围内所有 matched=1 的 duration_ms 值数组，按升序排列
|
||||
|
||||
#### Scenario: 无成功检查
|
||||
- **WHEN** 时间窗口内无 matched=1 的记录
|
||||
- **THEN** 系统 SHALL 返回空数组
|
||||
|
||||
### Requirement: 目标故障段查询
|
||||
ProbeStore SHALL 提供 `getCheckSequence(targetId, from, to)` 方法，返回时间窗口内的检查序列用于故障分析。
|
||||
|
||||
#### Scenario: 获取检查序列
|
||||
- **WHEN** 调用 `getCheckSequence(targetId, from, to)`
|
||||
- **THEN** 系统 SHALL 返回该目标在时间范围内所有检查记录的 `{ timestamp: string, matched: number }` 数组，按 timestamp 升序排列
|
||||
|
||||
#### Scenario: 无检查记录
|
||||
- **WHEN** 时间窗口内无记录
|
||||
- **THEN** 系统 SHALL 返回空数组
|
||||
@@ -1,111 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 概览面板组件化
|
||||
概览 Tab SHALL 作为独立组件 `OverviewTab` 实现，展示多维度统计、趋势图、状态分布和基本信息。
|
||||
|
||||
#### Scenario: OverviewTab 组件职责
|
||||
- **WHEN** 概览 Tab 渲染
|
||||
- **THEN** `OverviewTab` 组件 SHALL 负责多维度统计卡片（2×4 布局）、趋势图（延迟范围面积图+异常标记点）、状态分布环形图和基本信息的渲染
|
||||
|
||||
#### Scenario: 统计计算不再使用 computeTrendStats
|
||||
- **WHEN** OverviewTab 需要 totalChecks、upChecks、downChecks
|
||||
- **THEN** SHALL 直接使用 statsData 中的 totalChecks、upChecks、downChecks 字段，`computeTrendStats` 工具函数 SHALL 被删除
|
||||
|
||||
#### Scenario: OverviewTab props
|
||||
- **WHEN** OverviewTab 渲染
|
||||
- **THEN** 组件 SHALL 接收 `target: TargetStatus`、`trendData: TrendPoint[]`、`trendLoading: boolean`、`statsData: TargetStatsResponse | null`、`statsLoading: boolean` 作为 props
|
||||
|
||||
### Requirement: 概览面板
|
||||
概览 Tab SHALL 按区域展示多维度统计、趋势图、状态分布和基本信息。
|
||||
|
||||
#### Scenario: 区域排列顺序
|
||||
- **WHEN** 概览面板渲染
|
||||
- **THEN** 面板 SHALL 按以下顺序展示区域：统计 → 趋势 → 状态分布 → 基本信息，每个区域前 SHALL 显示 TDesign Divider（align="left"）作为小标题
|
||||
|
||||
#### Scenario: 统计区多维度布局
|
||||
- **WHEN** 概览面板渲染
|
||||
- **THEN** 面板 SHALL 在"统计"区域使用 2 行 × 4 列的 TDesign Row/Col + Statistic 布局：第一行为可用率（suffix="%"）、平均延迟（suffix="ms"）、P95 延迟（suffix="ms"）、检查总数；第二行为 MTTR（动态单位）、最长故障（动态单位）、故障次数（suffix="次"）、连续正常（suffix="次"，固定标题"连续正常"，当目标当前处于异常状态时值为 0）
|
||||
|
||||
#### Scenario: MTTR 和最长故障动态单位
|
||||
- **WHEN** MTTR 或最长故障值小于 60000ms
|
||||
- **THEN** SHALL 以秒为单位展示（suffix="秒"）
|
||||
- **WHEN** 值大于等于 60000ms 且小于 3600000ms
|
||||
- **THEN** SHALL 以分钟为单位展示（suffix="分钟"）
|
||||
- **WHEN** 值大于等于 3600000ms
|
||||
- **THEN** SHALL 以小时为单位展示（suffix="小时"）
|
||||
|
||||
#### Scenario: 统计区数据来源
|
||||
- **WHEN** 统计区渲染
|
||||
- **THEN** 第一行数据 SHALL 来自 statsData（TargetStatsResponse），第二行数据同样来自 statsData
|
||||
|
||||
#### Scenario: 统计区加载状态
|
||||
- **WHEN** statsData 正在加载
|
||||
- **THEN** 统计区 SHALL 显示 TDesign Skeleton 加载占位
|
||||
|
||||
#### Scenario: 趋势图延迟范围面积
|
||||
- **WHEN** 概览面板渲染且趋势数据可用
|
||||
- **THEN** 趋势图 SHALL 使用 recharts Area 组件渲染 minDurationMs 到 maxDurationMs 的延迟范围（半透明品牌色填充），叠加 avgDurationMs 实线
|
||||
|
||||
#### Scenario: 趋势图异常标记点
|
||||
- **WHEN** 趋势数据中某小时的 availability < 100
|
||||
- **THEN** 趋势图 SHALL 在 avgDurationMs 线上该时间点渲染红色圆点（fill: var(--td-error-color)），使用 recharts Line 的 dot 回调函数实现；图表 SHALL 仅保留左侧 Y 轴（ms），移除右侧 Y 轴（%）和 availability 折线
|
||||
|
||||
#### Scenario: 趋势数据加载中
|
||||
- **WHEN** 概览面板渲染且趋势数据正在加载
|
||||
- **THEN** "趋势"区域 SHALL 显示 TDesign Skeleton 加载占位
|
||||
|
||||
#### Scenario: 状态分布环形图
|
||||
- **WHEN** 概览面板渲染且 statsData 可用
|
||||
- **THEN** 面板 SHALL 在"状态分布"区域展示 recharts 环形图（StatusDonut），使用 statsData.upChecks 和 statsData.downChecks 作为数据源，外圈显示 UP/DOWN 比例，中间显示可用率百分比
|
||||
|
||||
#### Scenario: 状态分布加载状态
|
||||
- **WHEN** statsData 正在加载
|
||||
- **THEN** 状态分布区域 SHALL 显示 TDesign Skeleton 加载占位
|
||||
|
||||
#### Scenario: 元信息展示
|
||||
- **WHEN** 概览面板渲染
|
||||
- **THEN** 面板 SHALL 在"基本信息"区域使用 TDesign Descriptions 组件展示目标元信息：目标地址、检查间隔、最新检查时间、状态详情
|
||||
|
||||
### Requirement: 时间范围选择器
|
||||
Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录两个面板的数据。时间选择器 SHALL 分两行显示：第一行为快捷按钮，第二行为日期时间范围选择器。
|
||||
|
||||
#### Scenario: 快捷时间按钮
|
||||
- **WHEN** Drawer 渲染
|
||||
- **THEN** 时间选择区第一行 SHALL 显示 TDesign RadioGroup（variant=default-filled）快捷按钮：1小时、6小时、24小时、7天
|
||||
|
||||
#### Scenario: 点击快捷按钮
|
||||
- **WHEN** 用户点击快捷按钮（如 "24小时"）
|
||||
- **THEN** 系统 SHALL 自动设置对应的起止时间，DateRangePicker 显示对应的时间范围，该按钮高亮
|
||||
|
||||
#### Scenario: 快捷按钮联动统计区
|
||||
- **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
|
||||
- **THEN** 统计区和趋势图 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/stats` 和 `/api/targets/:id/trend` 数据
|
||||
|
||||
#### Scenario: 自定义日期时间范围
|
||||
- **WHEN** 用户通过 TDesign DateRangePicker（mode=date, enableTimePicker, format="YYYY-MM-DD HH:mm"）修改时间范围
|
||||
- **THEN** 快捷按钮 SHALL 取消高亮，系统重新请求对应时间范围的数据
|
||||
|
||||
#### Scenario: 默认时间范围
|
||||
- **WHEN** Drawer 打开
|
||||
- **THEN** 时间选择器 SHALL 默认选中 "24小时" 快捷按钮
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Stats 数据查询 Hook
|
||||
系统 SHALL 提供 `useTargetStats` hook 查询单目标深度统计数据。
|
||||
|
||||
#### Scenario: stats queryKey
|
||||
- **WHEN** 查询某目标的统计数据
|
||||
- **THEN** queryKey SHALL 为 ["stats", targetId, from, to]
|
||||
|
||||
#### Scenario: stats 条件查询
|
||||
- **WHEN** 用户未选中任何目标
|
||||
- **THEN** stats 的 useQuery SHALL enabled=false，不发起请求
|
||||
|
||||
#### Scenario: stats 数据返回
|
||||
- **WHEN** stats 查询成功
|
||||
- **THEN** hook SHALL 返回 `TargetStatsResponse` 类型数据
|
||||
|
||||
#### Scenario: 时间范围变化时重新请求
|
||||
- **WHEN** 用户更改时间范围
|
||||
- **THEN** stats 的 useQuery SHALL 因 queryKey 变化自动重新请求
|
||||
@@ -1,106 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 单目标深度统计 API
|
||||
系统 SHALL 提供 `GET /api/targets/:id/stats` 端点，返回单个目标在指定时间窗口内的非时序聚合统计指标。
|
||||
|
||||
#### Scenario: 获取目标统计
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/stats?from=ISO&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回 JSON 对象包含 p95DurationMs、p99DurationMs、avgDurationMs、mttr、longestOutage、incidentCount、currentStreak、totalChecks、upChecks、downChecks、availability
|
||||
|
||||
#### Scenario: from 或 to 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/stats` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: 目标不存在
|
||||
- **WHEN** 客户端请求 `GET /api/targets/999/stats`
|
||||
- **THEN** 系统 SHALL 返回 404 状态码和错误信息
|
||||
|
||||
#### Scenario: 无效的目标 ID
|
||||
- **WHEN** 客户端请求 `GET /api/targets/abc/stats`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
### Requirement: P95/P99 延迟计算
|
||||
系统 SHALL 在应用层计算 P95 和 P99 延迟百分位数。
|
||||
|
||||
#### Scenario: 正常计算 P95
|
||||
- **WHEN** 时间窗口内存在成功检查记录（matched=1）
|
||||
- **THEN** 系统 SHALL 取出所有成功检查的 duration_ms，在应用层排序后取第 95 百分位值返回为 p95DurationMs
|
||||
|
||||
#### Scenario: 正常计算 P99
|
||||
- **WHEN** 时间窗口内存在成功检查记录
|
||||
- **THEN** 系统 SHALL 取第 99 百分位值返回为 p99DurationMs
|
||||
|
||||
#### Scenario: 无成功检查记录
|
||||
- **WHEN** 时间窗口内无 matched=1 的记录
|
||||
- **THEN** p95DurationMs 和 p99DurationMs SHALL 返回 null
|
||||
|
||||
#### Scenario: 百分位计算方法
|
||||
- **WHEN** 计算第 N 百分位
|
||||
- **THEN** 系统 SHALL 将 duration_ms 升序排列，取 index = ceil(count * N / 100) - 1 位置的值
|
||||
|
||||
### Requirement: MTTR 计算
|
||||
系统 SHALL 计算平均恢复时间（Mean Time To Recovery）。
|
||||
|
||||
#### Scenario: 存在已恢复的故障段
|
||||
- **WHEN** 时间窗口内存在至少一个已恢复的故障段（连续 matched=0 后跟 matched=1）
|
||||
- **THEN** 系统 SHALL 计算所有已恢复故障段的平均持续时间（从首个 matched=0 的 timestamp 到恢复后首个 matched=1 的 timestamp 之差），返回为 mttr（毫秒）
|
||||
|
||||
#### Scenario: 无已恢复的故障段
|
||||
- **WHEN** 时间窗口内无已恢复的故障段（全部正常，或当前仍在故障中且无历史恢复）
|
||||
- **THEN** mttr SHALL 返回 null
|
||||
|
||||
#### Scenario: 当前正在故障中
|
||||
- **WHEN** 时间窗口内最后一段故障尚未恢复
|
||||
- **THEN** 该未恢复的故障段 SHALL 不计入 MTTR 平均值
|
||||
|
||||
#### Scenario: 窗口起始即为故障且后续恢复
|
||||
- **WHEN** 时间窗口内第一条记录即为 matched=0（故障跨越了 from 边界），且该故障段在窗口内恢复
|
||||
- **THEN** 该故障段 SHALL 不计入 MTTR 平均值（因无法确定真实故障开始时间），但 SHALL 计入 incidentCount
|
||||
|
||||
### Requirement: 最长故障时长
|
||||
系统 SHALL 计算时间窗口内最长的单次故障持续时间。
|
||||
|
||||
#### Scenario: 存在故障段
|
||||
- **WHEN** 时间窗口内存在故障段
|
||||
- **THEN** 系统 SHALL 返回最长故障段的持续时间为 longestOutage（毫秒）
|
||||
|
||||
#### Scenario: 无故障
|
||||
- **WHEN** 时间窗口内无 matched=0 的记录
|
||||
- **THEN** longestOutage SHALL 返回 null
|
||||
|
||||
#### Scenario: 当前正在故障中
|
||||
- **WHEN** 最后一段故障尚未恢复
|
||||
- **THEN** 该故障段的持续时间 SHALL 计算为从故障开始到时间窗口 to 参数的时间差
|
||||
|
||||
### Requirement: 故障事件计数
|
||||
系统 SHALL 计算时间窗口内的故障事件次数。
|
||||
|
||||
#### Scenario: 计算故障事件数
|
||||
- **WHEN** 时间窗口内存在状态翻转（matched 从 1 变为 0）
|
||||
- **THEN** 系统 SHALL 返回翻转次数为 incidentCount
|
||||
|
||||
#### Scenario: 无故障事件
|
||||
- **WHEN** 时间窗口内所有检查均为 matched=1
|
||||
- **THEN** incidentCount SHALL 返回 0
|
||||
|
||||
#### Scenario: 窗口起始即为故障
|
||||
- **WHEN** 时间窗口内第一条记录即为 matched=0 且无前序记录可判断翻转
|
||||
- **THEN** 该故障 SHALL 计为 1 次事件
|
||||
|
||||
### Requirement: 当前连续状态
|
||||
系统 SHALL 返回目标当前的连续状态信息。
|
||||
|
||||
#### Scenario: 当前连续正常
|
||||
- **WHEN** 目标最近的检查记录连续为 matched=1
|
||||
- **THEN** currentStreak SHALL 返回 `{ up: true, count: N }`，N 为连续正常的检查次数
|
||||
|
||||
#### Scenario: 当前连续异常
|
||||
- **WHEN** 目标最近的检查记录连续为 matched=0
|
||||
- **THEN** currentStreak SHALL 返回 `{ up: false, count: N }`，N 为连续异常的检查次数
|
||||
|
||||
### Requirement: TargetStatsResponse 共享类型
|
||||
系统 SHALL 在 `src/shared/api.ts` 中定义 `TargetStatsResponse` 类型。
|
||||
|
||||
#### Scenario: 类型定义
|
||||
- **WHEN** 前后端引用 `TargetStatsResponse` 类型
|
||||
- **THEN** 该类型 SHALL 包含 p95DurationMs（number | null）、p99DurationMs（number | null）、avgDurationMs（number | null）、mttr（number | null）、longestOutage（number | null）、incidentCount（number）、currentStreak（{ up: boolean; count: number }）、totalChecks（number）、upChecks（number）、downChecks（number）、availability（number）
|
||||
@@ -1,28 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 连续状态列
|
||||
表格 SHALL 包含「连续状态」列，展示目标当前连续正常或异常的次数。
|
||||
|
||||
#### Scenario: 连续状态列渲染
|
||||
- **WHEN** 表格渲染
|
||||
- **THEN** 表格 SHALL 在「最近状态」列之后、「延迟」列之前展示「连续状态」列，标题为"连续"，宽度 100px
|
||||
|
||||
#### Scenario: 连续正常展示
|
||||
- **WHEN** 目标当前连续正常
|
||||
- **THEN** 列 SHALL 使用 TDesign Tag 组件（theme=success, variant=light, size=small）展示 "▲ N次"
|
||||
|
||||
#### Scenario: 连续异常展示
|
||||
- **WHEN** 目标当前连续异常
|
||||
- **THEN** 列 SHALL 使用 TDesign Tag 组件（theme=danger, variant=light, size=small）展示 "▼ N次"
|
||||
|
||||
#### Scenario: 连续状态计算
|
||||
- **WHEN** 计算连续状态
|
||||
- **THEN** 系统 SHALL 从 recentSamples（按时间倒序）遍历，统计从最新记录开始连续相同状态的次数
|
||||
|
||||
#### Scenario: 超过样本上限
|
||||
- **WHEN** 连续状态次数等于 recentSamples 长度（30）
|
||||
- **THEN** 列 SHALL 展示 "▲ 30+" 或 "▼ 30+"
|
||||
|
||||
#### Scenario: 无样本数据
|
||||
- **WHEN** 目标的 recentSamples 为空数组
|
||||
- **THEN** 列 SHALL 展示 "-"
|
||||
@@ -1,55 +0,0 @@
|
||||
## 1. 共享类型与数据层
|
||||
|
||||
- [ ] 1.1 扩展 `src/shared/api.ts`：SummaryResponse 增加 incidents24h；TrendPoint 增加 upChecks/minDurationMs/maxDurationMs；新增 TargetStatsResponse 类型
|
||||
- [ ] 1.2 ProbeStore 修改 `getAllTargetStats(from?, to?)` 和 `getTargetStats(targetId, from?, to?)` 增加时间窗口参数，默认 24h
|
||||
- [ ] 1.3 ProbeStore 修改 `getTrend` SQL 增加 MIN/MAX duration_ms 和 upChecks 聚合字段
|
||||
- [ ] 1.4 ProbeStore 新增 `getIncidents24h()` 独立方法，使用 LAG 窗口函数统计所有目标的状态翻转次数
|
||||
- [ ] 1.5 ProbeStore 新增 `getTargetDurations(targetId, from, to)` 方法，返回成功检查的 duration_ms 升序数组
|
||||
- [ ] 1.6 ProbeStore 新增 `getCheckSequence(targetId, from, to)` 方法，返回检查序列用于故障分析
|
||||
- [ ] 1.7 编写 ProbeStore 新增/修改方法的单元测试
|
||||
|
||||
## 2. 后端 API 路由
|
||||
|
||||
- [ ] 2.1 修改 `src/server/routes/summary.ts`：调用 store.getIncidents24h()，响应增加 incidents24h 字段
|
||||
- [ ] 2.2 修改 `src/server/routes/targets.ts`：解析 `?window=24h` 查询参数，转换为时间范围传递给 getAllTargetStats(from, to)，缺省默认 24h
|
||||
- [ ] 2.3 修改 `src/server/routes/trend.ts`：响应增加 upChecks/minDurationMs/maxDurationMs 字段
|
||||
- [ ] 2.4 新增 `src/server/routes/stats.ts`：实现 GET /api/targets/:id/stats?from=&to= 端点，应用层计算 P95/P99、MTTR、最长故障、故障次数、连续状态
|
||||
- [ ] 2.5 在 `src/server/server.ts` 路由注册中挂载 stats 路由
|
||||
- [ ] 2.6 编写 stats 路由的集成测试（含 P95 计算、MTTR 计算、窗口边界截断、无数据等边界情况）
|
||||
- [ ] 2.7 编写 summary/targets/trend 路由修改的测试更新
|
||||
|
||||
## 3. 前端工具函数
|
||||
|
||||
- [ ] 3.1 删除 `src/web/utils/stats.ts` 中的 `computeTrendStats` 函数（不再有调用方）
|
||||
- [ ] 3.2 新增连续状态计算工具函数 `getConsecutiveStatus(samples: RecentSample[]): { up: boolean; count: number }`
|
||||
- [ ] 3.3 新增时间格式化工具函数：相对时间（X秒前/X分钟前）、动态单位（ms→秒/分钟/小时）
|
||||
- [ ] 3.4 编写工具函数的单元测试
|
||||
|
||||
## 4. 前端数据层
|
||||
|
||||
- [ ] 4.1 修改 `src/web/hooks/use-queries.ts`：useTargets 请求改为 `/api/targets?window=24h`，后端解析 window 参数转换为时间范围
|
||||
- [ ] 4.2 新增 useTargetStats hook（queryKey: ["stats", targetId, from, to]，enabled 依赖 targetId 存在）
|
||||
- [ ] 4.3 修改 `use-target-detail.ts`：集成 useTargetStats 调用，复用现有 timeFrom/timeTo 状态
|
||||
|
||||
## 5. 前端组件 — Summary Cards
|
||||
|
||||
- [ ] 5.1 修改 `SummaryCards.tsx`：从 3 列（span=4）扩展为 4 列（span=3），新增 24h 异常事件数卡片（color=orange）
|
||||
- [ ] 5.2 在 SummaryCards 底部增加 lastCheckTime 相对时间展示（useState + setInterval 每秒更新），超过 60 秒变警告色
|
||||
|
||||
## 6. 前端组件 — Target Table
|
||||
|
||||
- [ ] 6.1 修改 `target-table-columns.tsx`：可用率列标题改为"可用率(24h)"
|
||||
- [ ] 6.2 修改 `target-table-columns.tsx`：在「最近状态」列后新增「连续」列（width=100），使用 TDesign Tag（theme=success/danger, variant=light, size=small）渲染 "▲ N次" / "▼ N次"
|
||||
|
||||
## 7. 前端组件 — Drawer 概览
|
||||
|
||||
- [ ] 7.1 修改 `OverviewTab.tsx`：props 增加 statsData/statsLoading；删除 computeTrendStats 调用；统计区重构为 2×4 Statistic 布局，数据来自 statsData
|
||||
- [ ] 7.2 修改 `OverviewTab.tsx`：StatusDonut 数据来源改为 statsData.upChecks / statsData.downChecks
|
||||
- [ ] 7.3 修改 `TrendChart.tsx`：移除右侧 Y 轴和 availability Line；增加 Area 组件渲染 min/max 延迟范围（半透明品牌色填充）；avgDurationMs Line 的 dot 回调对 availability < 100 的点渲染红色圆点
|
||||
- [ ] 7.4 修改 `TargetDetailDrawer.tsx`：TIME_SHORTCUTS 保持 1h/6h/24h/7d 四个选项，默认选中 24h
|
||||
- [ ] 7.5 修改 `TargetDetailDrawer.tsx`：集成 useTargetStats，传递 statsData/statsLoading 给 OverviewTab
|
||||
|
||||
## 8. 质量保障
|
||||
|
||||
- [ ] 8.1 运行完整测试套件，确保所有测试通过
|
||||
- [ ] 8.2 运行 lint 和格式检查，修复所有问题
|
||||
@@ -1,29 +1,88 @@
|
||||
## Purpose
|
||||
|
||||
定义拨测系统的 REST API 端点：总览统计、目标列表含分组和结构化采样数据、带时间范围和分页的历史记录、按时间范围的趋势聚合。
|
||||
定义拨测系统的 REST API 端点：Dashboard 聚合 API、单目标指标 API、带时间范围和分页的历史记录、共享类型定义和 API 错误处理。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 总览统计 API
|
||||
系统 SHALL 提供 `GET /api/summary` 端点，返回所有目标的总体统计信息（不含平均耗时）。
|
||||
### Requirement: Dashboard 聚合 API
|
||||
系统 SHALL 提供 `GET /api/dashboard` 端点，返回 Dashboard 首屏所需的总览统计和目标列表数据。
|
||||
|
||||
#### Scenario: 获取总览统计
|
||||
- **WHEN** 客户端请求 `GET /api/summary`
|
||||
- **THEN** 系统 SHALL 返回 JSON 包含 total（总目标数）、up（正常数）、down（异常数）、lastCheckTime（最近一次检查时间）
|
||||
#### Scenario: 获取 Dashboard 数据
|
||||
- **WHEN** 客户端请求 `GET /api/dashboard?window=24h&recentLimit=30`
|
||||
- **THEN** 系统 SHALL 返回 JSON 包含 summary 和 targets 字段
|
||||
|
||||
### Requirement: 目标列表 API
|
||||
系统 SHALL 提供 `GET /api/targets` 端点，返回所有 typed target 及其最新状态、分组信息和结构化采样数据。
|
||||
#### Scenario: summary 字段
|
||||
- **WHEN** Dashboard 响应包含 summary
|
||||
- **THEN** summary SHALL 包含 total（总目标数）、up（当前正常目标数）、down（当前异常目标数）、lastCheckTime（最近一次检查时间）、incidents（指定窗口内异常事件数）、window（from/to/label）字段
|
||||
|
||||
#### Scenario: 获取目标列表
|
||||
- **WHEN** 客户端请求 `GET /api/targets`
|
||||
- **THEN** 系统 SHALL 返回 JSON 数组，每个元素包含目标基本信息（id、name、group、type、target、interval）、最近一次检查结果（timestamp、matched、durationMs、statusDetail、failure）、统计摘要（totalChecks、availability）和结构化采样数据 recentSamples（代替原 sparkline）
|
||||
#### Scenario: targets 字段
|
||||
- **WHEN** Dashboard 响应包含 targets
|
||||
- **THEN** targets 数组中每个元素 SHALL 包含目标基本信息（id、name、group、type、target、interval）、latestCheck、stats、currentStreak 和 recentSamples 字段
|
||||
|
||||
#### Scenario: window 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/dashboard` 未提供 window 参数
|
||||
- **THEN** 系统 SHALL 默认使用 window=`24h`
|
||||
|
||||
#### Scenario: window 参数语义
|
||||
- **WHEN** 系统处理 Dashboard 请求
|
||||
- **THEN** 系统 SHALL 以服务端当前时间作为 window.to，以 window 参数换算 window.from，并在响应中回显 window.from、window.to、window.label
|
||||
|
||||
#### Scenario: window 参数有效值
|
||||
- **WHEN** 客户端请求 Dashboard 端点并指定 window 参数
|
||||
- **THEN** 系统 SHALL 接受 `24h` 作为有效值；其他值 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: 不支持的 window 参数
|
||||
- **WHEN** 客户端请求 `GET /api/dashboard?window=abc`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: recentLimit 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/dashboard?window=24h` 未提供 recentLimit 参数
|
||||
- **THEN** 系统 SHALL 默认使用 recentLimit=30
|
||||
|
||||
#### Scenario: 不支持的 recentLimit 参数
|
||||
- **WHEN** 客户端请求 `GET /api/dashboard?recentLimit=0` 或超过系统上限的 recentLimit
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: 目标无历史记录
|
||||
- **WHEN** 某目标尚未执行过任何拨测
|
||||
- **THEN** 其 latestCheck 为 null，recentSamples 为空数组
|
||||
- **THEN** 其 latestCheck 为 null，recentSamples 为空数组，stats.totalChecks 为 0，stats.availability 为 0，currentStreak 为 null
|
||||
|
||||
### Requirement: Dashboard 指标字段
|
||||
Dashboard API SHALL 返回基于时间窗口计算的目标统计和连续状态字段。
|
||||
|
||||
#### Scenario: 目标 stats 字段
|
||||
- **WHEN** Dashboard 响应包含目标 stats
|
||||
- **THEN** stats SHALL 包含 totalChecks、upChecks、downChecks、availability 字段，且这些字段 SHALL 基于请求 window 对应的时间范围计算
|
||||
|
||||
#### Scenario: 目标 currentStreak 字段
|
||||
- **WHEN** Dashboard 响应包含目标 currentStreak
|
||||
- **THEN** currentStreak SHALL 为 `{ up: boolean, count: number, capped?: boolean }` 或 null
|
||||
|
||||
#### Scenario: currentStreak 达到 recentLimit
|
||||
- **WHEN** 连续状态次数达到 recentLimit 上限
|
||||
- **THEN** currentStreak.capped SHALL 为 true
|
||||
|
||||
#### Scenario: recentSamples 字段
|
||||
- **WHEN** Dashboard 响应包含 recentSamples
|
||||
- **THEN** 每个 recentSamples 元素 SHALL 包含 timestamp、durationMs、up 字段，其中 up 为 boolean 且等于 matched
|
||||
|
||||
### Requirement: 单目标指标 API
|
||||
系统 SHALL 提供 `GET /api/targets/:id/metrics` 端点，返回 Drawer 概览所需的单目标统计和趋势数据。端点的详细计算规则（P95/P99、MTTR、故障分析、趋势分桶等）定义在 `target-metrics-api` 能力中。
|
||||
|
||||
#### Scenario: 指定时间范围查询指标
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics?from=ISO&to=ISO&bucket=1h`
|
||||
- **THEN** 系统 SHALL 返回 targetId、window、stats、trend 字段
|
||||
|
||||
#### Scenario: from 或 to 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: bucket 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics?from=ISO&to=ISO` 未提供 bucket 参数
|
||||
- **THEN** 系统 SHALL 默认使用 bucket=`1h`
|
||||
|
||||
### Requirement: 历史记录 API
|
||||
系统 SHALL 提供 `GET /api/targets/:id/history` 端点，支持时间范围筛选和分页返回指定目标的拨测记录。
|
||||
系统 SHALL 保留 `GET /api/targets/:id/history` 端点，支持时间范围筛选和分页返回指定目标的拨测记录。
|
||||
|
||||
#### Scenario: 获取指定时间范围内的历史记录
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&page=1&pageSize=20`
|
||||
@@ -37,38 +96,24 @@
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
### Requirement: 趋势 API 支持时间范围
|
||||
系统 SHALL 提供 `GET /api/targets/:id/trend` 端点，支持 `from` 和 `to` 查询参数指定时间范围。
|
||||
|
||||
#### Scenario: 指定时间范围查询趋势
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/trend?from=ISO&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回指定时间范围内按小时分组的聚合数据
|
||||
|
||||
#### Scenario: from 或 to 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/trend` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
### Requirement: 目标列表返回分组和采样数据
|
||||
`GET /api/targets` SHALL 返回每个目标的分组信息和结构化采样数据，替代原有 sparkline。
|
||||
|
||||
#### Scenario: 返回分组信息
|
||||
- **WHEN** 客户端请求 `GET /api/targets`
|
||||
- **THEN** 响应中每个目标 SHALL 包含 `group` 字段，值为该目标所属的分组名称
|
||||
|
||||
#### Scenario: 返回 recentSamples
|
||||
- **WHEN** 客户端请求 `GET /api/targets`
|
||||
- **THEN** 响应中每个目标 SHALL 包含 `recentSamples` 数组，每个元素包含 `timestamp`（ISO 8601）、`durationMs`（number | null）、`up`（boolean，matched === true）
|
||||
|
||||
#### Scenario: recentSamples 数量
|
||||
- **WHEN** 客户端请求 `GET /api/targets`
|
||||
- **THEN** 每个目标的 recentSamples SHALL 最多包含 30 个元素，按时间倒序排列
|
||||
|
||||
#### Scenario: 目标无历史记录
|
||||
- **WHEN** 某目标尚未执行过任何拨测
|
||||
- **THEN** 其 recentSamples SHALL 为空数组
|
||||
|
||||
### Requirement: 新增共享类型
|
||||
系统 SHALL 在 `src/shared/api.ts` 中定义 `CheckResult`、`RecentSample` 和 `HistoryResponse` 类型。
|
||||
系统 SHALL 在 `src/shared/api.ts` 中定义 Dashboard 和 Metrics 相关共享类型。
|
||||
|
||||
#### Scenario: DashboardResponse 类型
|
||||
- **WHEN** 前后端共享 `DashboardResponse` 类型
|
||||
- **THEN** 该类型 SHALL 包含 summary 和 targets 字段
|
||||
|
||||
#### Scenario: TargetStatus 类型
|
||||
- **WHEN** 前后端共享 `TargetStatus` 类型
|
||||
- **THEN** 该类型 SHALL 包含 stats（totalChecks、upChecks、downChecks、availability）、currentStreak 和 recentSamples 字段
|
||||
|
||||
#### Scenario: TargetMetricsResponse 类型
|
||||
- **WHEN** 前后端共享 `TargetMetricsResponse` 类型
|
||||
- **THEN** 该类型 SHALL 包含 targetId、window、stats 和 trend 字段
|
||||
|
||||
#### Scenario: TrendPoint 类型
|
||||
- **WHEN** 前后端共享 `TrendPoint` 类型
|
||||
- **THEN** 该类型 SHALL 包含 bucketStart、avgDurationMs、minDurationMs、maxDurationMs、availability、totalChecks、upChecks、downChecks 字段
|
||||
|
||||
#### Scenario: CheckResult 类型
|
||||
- **WHEN** 前后端共享 `CheckResult` 类型
|
||||
@@ -93,13 +138,17 @@
|
||||
系统 SHALL 对不存在的目标 ID、无效参数和超出范围的分页参数返回适当的 HTTP 错误响应。
|
||||
|
||||
#### Scenario: 查询不存在的目标
|
||||
- **WHEN** 客户端请求 `GET /api/targets/999/history`
|
||||
- **WHEN** 客户端请求 `GET /api/targets/999/metrics?from=ISO&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回 404 状态码和错误信息
|
||||
|
||||
#### Scenario: 无效的 from/to 参数
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=invalid`
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics?from=invalid&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: from 晚于 to
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics?from=<较晚时间>&to=<较早时间>`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息，提示 from 必须早于 to
|
||||
|
||||
#### Scenario: 无效的分页参数
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&page=abc`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
@@ -112,12 +161,8 @@
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&pageSize=200`
|
||||
- **THEN** 系统 SHALL 正常返回数据
|
||||
|
||||
#### Scenario: from 或 to 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/trend` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: 无效的目标 ID
|
||||
- **WHEN** 客户端请求 `GET /api/targets/abc/history`
|
||||
- **WHEN** 客户端请求 `GET /api/targets/abc/metrics?from=ISO&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
### Requirement: 失败信息 API 契约
|
||||
|
||||
@@ -1,19 +1,46 @@
|
||||
## Purpose
|
||||
|
||||
定义拨测系统前端 Dashboard 页面：总览统计卡片、页面标题、加载和错误状态处理。分组表格布局见 `target-table`，目标详情 Drawer 见 `target-detail-drawer`，数据轮询和缓存见 `tanstack-query-data-layer`。
|
||||
定义拨测系统前端 Dashboard 页面：总览统计卡片（含数据新鲜度）、Dashboard 数据查询、页面标题、加载和错误状态处理。分组表格布局见 `target-table`，目标详情 Drawer 见 `target-detail-drawer`，数据轮询和缓存见 `tanstack-query-data-layer`。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 总览统计卡片
|
||||
Dashboard SHALL 在页面顶部使用 TDesign Statistic 组件展示总览统计，包含总目标数、正常数和异常数。
|
||||
### Requirement: Dashboard 数据查询
|
||||
Dashboard SHALL 通过 `GET /api/dashboard` 获取首屏总览统计和目标列表数据。
|
||||
|
||||
#### Scenario: 展示统计卡片
|
||||
- **WHEN** 用户打开 Dashboard 页面
|
||||
- **THEN** 页面顶部 SHALL 使用 TDesign Row/Col 布局展示 3 个 TDesign Card + Statistic 组合：全部目标数（color=blue）、正常目标数（color=green）、异常目标数（color=red）
|
||||
#### Scenario: 查询 Dashboard 数据
|
||||
- **WHEN** 页面处于打开状态
|
||||
- **THEN** 前端 SHALL 使用 TanStack Query 请求 `GET /api/dashboard?window=24h&recentLimit=30`
|
||||
|
||||
#### Scenario: 统计数据自动刷新
|
||||
- **WHEN** 页面处于打开状态
|
||||
- **THEN** 统计卡片 SHALL 通过 TanStack Query 的 refetchInterval=8000 自动刷新数据
|
||||
- **THEN** Dashboard 数据 SHALL 通过 TanStack Query 的 refetchInterval=8000 自动刷新
|
||||
|
||||
#### Scenario: 元信息独立查询
|
||||
- **WHEN** 页面需要 checker 类型列表
|
||||
- **THEN** 前端 SHALL 继续通过 `GET /api/meta` 独立查询 checkerTypes
|
||||
|
||||
### Requirement: 总览统计卡片
|
||||
Dashboard SHALL 在页面顶部使用 TDesign Statistic 组件展示总览统计，包含总目标数、正常数、异常数和窗口异常事件数，并展示数据新鲜度。
|
||||
|
||||
#### Scenario: 展示统计卡片
|
||||
- **WHEN** 用户打开 Dashboard 页面
|
||||
- **THEN** 页面顶部 SHALL 使用 TDesign Row/Col 布局展示 4 个 TDesign Card + Statistic 组合：全部目标数（color=blue）、正常目标数（color=green）、异常目标数（color=red）、24h 异常事件数（color=orange）
|
||||
|
||||
#### Scenario: 异常事件数据来源
|
||||
- **WHEN** SummaryCards 渲染 24h 异常事件数
|
||||
- **THEN** 该数值 SHALL 使用 DashboardResponse.summary.incidents 字段，标题 SHALL 基于当前 window 展示为"24h 异常事件数"
|
||||
|
||||
#### Scenario: 展示数据新鲜度
|
||||
- **WHEN** Summary 数据包含 lastCheckTime
|
||||
- **THEN** 统计卡片行底部 SHALL 展示相对时间文本（如"最后更新: 3秒前"），使用 TDesign Typography.Text（theme="secondary"）
|
||||
|
||||
#### Scenario: 数据新鲜度警告
|
||||
- **WHEN** lastCheckTime 距当前时间超过 60 秒
|
||||
- **THEN** 相对时间文本 SHALL 使用警告色（--td-warning-color）
|
||||
|
||||
#### Scenario: 无检查时间
|
||||
- **WHEN** Summary 数据 lastCheckTime 为 null
|
||||
- **THEN** 数据新鲜度 SHALL 展示为"尚无检查数据"或等价占位文本
|
||||
|
||||
### Requirement: 页面标题
|
||||
Dashboard 页面 SHALL 使用 TDesign Typography 组件渲染标题和副标题。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
## Purpose
|
||||
|
||||
定义基于 SQLite 的拨测数据持久化存储：targets 同步（含分组信息）、check_results 追加写入、结构化采样数据查询、时间范围和分页查询、索引与聚合查询。
|
||||
定义基于 SQLite 的拨测数据持久化存储：targets 同步（含分组信息）、check_results 追加写入、Dashboard 和 Metrics 数据查询支持、延迟百分位取数、时间范围和分页查询、索引与聚合查询。
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -61,26 +61,72 @@
|
||||
- **WHEN** 查询所有 targets
|
||||
- **THEN** 结果 SHALL 将 "default" 分组目标排在首位，其余分组按 YAML 配置中首次出现的顺序（即 id 自增顺序）排列
|
||||
|
||||
### Requirement: 结构化采样数据查询
|
||||
系统 SHALL 提供 `getRecentSamples` 方法替代 `getSparkline`，返回包含状态信息的结构化采样数据。
|
||||
### Requirement: 聚合查询支持
|
||||
数据存储 SHALL 支持按时间段获取指标计算所需数据，用于后端应用层计算可用率、平均耗时、延迟范围、趋势分桶和可靠性指标。
|
||||
|
||||
#### Scenario: 获取最近采样数据
|
||||
- **WHEN** 调用 `getRecentSamples(targetId, 30)`
|
||||
- **THEN** 系统 SHALL 返回最多 30 条记录，每条包含 timestamp、duration_ms、matched
|
||||
#### Scenario: 轻数据库计算边界
|
||||
- **WHEN** 实现指标相关数据查询
|
||||
- **THEN** 数据库 SHALL 主要负责存储、过滤、排序、分页、LIMIT 和标准 SQL 基础聚合，业务指标语义 SHALL 在后端应用层计算
|
||||
|
||||
#### Scenario: 采样数据排序
|
||||
- **WHEN** 获取采样数据
|
||||
- **THEN** 记录 SHALL 按 timestamp 降序排列（最新在前）
|
||||
#### Scenario: 可使用的基础 SQL 聚合
|
||||
- **WHEN** 查询需要减少返回数据量
|
||||
- **THEN** 系统 MAY 使用标准 SQL 的 COUNT、SUM(CASE)、AVG、MIN、MAX、GROUP BY 等基础能力
|
||||
|
||||
### Requirement: 趋势数据时间范围查询
|
||||
系统 SHALL 支持按任意时间范围查询趋势聚合数据，替代固定 hours 参数。
|
||||
#### Scenario: 避免数据库承载业务语义
|
||||
- **WHEN** 实现状态翻转、故障段、MTTR、最长故障、连续状态、百分位或趋势分桶
|
||||
- **THEN** 系统 SHALL 在后端应用层实现这些规则，不依赖 SQLite 专有函数或复杂窗口函数承载业务语义
|
||||
|
||||
#### Scenario: 按时间范围查询趋势
|
||||
- **WHEN** 查询指定 target 在 from 到 to 时间范围内的趋势数据
|
||||
- **THEN** 系统 SHALL 返回按小时分组的聚合数据，包括每小时的 avgDurationMs、availability 和 totalChecks
|
||||
#### Scenario: UP/DOWN 判定
|
||||
- **WHEN** 系统需要判定目标当前状态
|
||||
- **THEN** 系统 SHALL 基于 latestCheck.matched 判定目标 UP 或 DOWN：matched=true 为 UP，matched=false 为 DOWN
|
||||
|
||||
### Requirement: Dashboard 数据查询支持
|
||||
ProbeStore SHALL 提供 Dashboard 聚合响应所需的批量取数能力。
|
||||
|
||||
#### Scenario: 批量获取最新检查
|
||||
- **WHEN** Dashboard API 需要计算当前 up/down 和 lastCheckTime
|
||||
- **THEN** Store SHALL 支持批量获取每个 target 的最新检查记录，避免 N+1 查询
|
||||
|
||||
#### Scenario: 批量获取窗口统计基础数据
|
||||
- **WHEN** Dashboard API 需要计算各 target 在指定 window 内的 totalChecks、upChecks、downChecks 和 availability
|
||||
- **THEN** Store SHALL 支持按 target_id 批量返回指定时间窗口内的基础计数数据
|
||||
|
||||
#### Scenario: 批量获取最近样本
|
||||
- **WHEN** Dashboard API 需要展示 recentSamples 和计算 capped currentStreak
|
||||
- **THEN** Store SHALL 支持批量获取每个 target 最近 recentLimit 条检查记录，按 target_id 分组且每组按 timestamp 降序排列
|
||||
|
||||
#### Scenario: 获取 Dashboard 异常事件序列
|
||||
- **WHEN** Dashboard API 需要计算 incidents
|
||||
- **THEN** Store SHALL 支持获取指定时间窗口内所有 target 的 `{ target_id, timestamp, matched }` 序列，按 target_id 和 timestamp 升序排列，供后端应用层计算状态翻转
|
||||
|
||||
### Requirement: 单目标指标取数支持
|
||||
ProbeStore SHALL 提供单目标 metrics 响应所需的取数能力。
|
||||
|
||||
#### Scenario: 获取目标检查点序列
|
||||
- **WHEN** Metrics API 需要计算趋势分桶、故障段、MTTR、最长故障、故障次数和连续状态
|
||||
- **THEN** Store SHALL 支持获取指定 target 在 from 到 to 时间范围内的 `{ timestamp, matched, duration_ms }` 数组，按 timestamp 升序排列
|
||||
|
||||
#### Scenario: 无检查记录
|
||||
- **WHEN** 时间窗口内无检查记录
|
||||
- **THEN** Store SHALL 返回空数组
|
||||
|
||||
### Requirement: 目标延迟百分位取数
|
||||
ProbeStore SHALL 提供 `getTargetDurations(targetId, from, to)` 方法，返回时间窗口内所有成功检查的 duration_ms 数组。
|
||||
|
||||
#### Scenario: 获取延迟数据
|
||||
- **WHEN** 调用 `getTargetDurations(targetId, from, to)`
|
||||
- **THEN** 系统 SHALL 返回该目标在时间范围内所有 matched=1 且 duration_ms 不为 null 的 duration_ms 值数组
|
||||
|
||||
#### Scenario: 延迟数据排序
|
||||
- **WHEN** 获取延迟数据
|
||||
- **THEN** 返回数组 SHALL 按 duration_ms 升序排列，供后端应用层计算 P95/P99
|
||||
|
||||
#### Scenario: 无成功检查
|
||||
- **WHEN** 时间窗口内无 matched=1 且 duration_ms 不为 null 的记录
|
||||
- **THEN** 系统 SHALL 返回空数组
|
||||
|
||||
### Requirement: 历史记录时间范围和分页查询
|
||||
系统 SHALL 支持按时间范围筛选并分页查询历史记录。
|
||||
系统 SHALL 继续支持按时间范围筛选并分页查询历史记录。
|
||||
|
||||
#### Scenario: 按时间范围筛选历史记录
|
||||
- **WHEN** 查询指定 target 在 from 到 to 时间范围内的历史记录
|
||||
@@ -90,24 +136,6 @@
|
||||
- **WHEN** 查询指定 page 和 pageSize 的历史记录
|
||||
- **THEN** 系统 SHALL 返回对应页的数据和总记录数
|
||||
|
||||
### Requirement: 聚合查询支持
|
||||
数据存储 SHALL 支持按时间段聚合查询，用于计算可用率、平均耗时、P99 耗时等统计指标。
|
||||
|
||||
#### Scenario: 计算目标可用率
|
||||
- **WHEN** 查询某目标在指定时间范围内的可用率
|
||||
- **THEN** 系统 SHALL 返回 matched=true 的记录数占总记录数的百分比
|
||||
|
||||
#### Scenario: 计算目标平均耗时
|
||||
- **WHEN** 查询某目标在指定时间范围内的平均耗时
|
||||
- **THEN** 系统 SHALL 返回 duration_ms 的平均值（仅计算 matched=true 的记录）
|
||||
|
||||
#### Scenario: 按小时聚合趋势数据
|
||||
- **WHEN** 查询某目标在指定时间范围内的趋势数据
|
||||
- **THEN** 系统 SHALL 返回按小时分组的聚合数据，包括每小时的平均耗时和可用率
|
||||
|
||||
#### Scenario: UP/DOWN 判定
|
||||
- **THEN** 系统 SHALL 基于 latestCheck.matched 判定目标 UP 或 DOWN：matched=true 为 UP，matched=false 为 DOWN
|
||||
|
||||
### Requirement: 目标展示摘要持久化
|
||||
数据存储 SHALL 为每个 target 持久化一个领域无关的展示摘要字段 `target`。
|
||||
|
||||
|
||||
@@ -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 DateRangePicker（mode=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 Divider（align="left"）作为小标题，不使用内联 style 的 h4 标签
|
||||
- **THEN** 面板 SHALL 按以下顺序展示区域：统计 → 趋势 → 状态分布 → 基本信息，每个区域前 SHALL 显示 TDesign Divider（align="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** 概览面板渲染
|
||||
|
||||
164
openspec/specs/target-metrics-api/spec.md
Normal file
164
openspec/specs/target-metrics-api/spec.md
Normal file
@@ -0,0 +1,164 @@
|
||||
## Purpose
|
||||
|
||||
定义单目标指标 API 的端点、响应类型、延迟百分位计算、MTTR 计算、最长故障时长计算、故障事件计数、当前连续状态、趋势数据应用层分桶和无数据口径。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 单目标指标 API
|
||||
系统 SHALL 提供 `GET /api/targets/:id/metrics` 端点，返回单个目标在指定时间窗口内的概览统计和趋势数据。
|
||||
|
||||
#### Scenario: 获取目标指标
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics?from=ISO&to=ISO&bucket=1h`
|
||||
- **THEN** 系统 SHALL 返回 JSON 对象包含 targetId、window、stats、trend 字段
|
||||
|
||||
#### Scenario: from 或 to 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: 目标不存在
|
||||
- **WHEN** 客户端请求 `GET /api/targets/999/metrics?from=ISO&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回 404 状态码和错误信息
|
||||
|
||||
#### Scenario: 无效的目标 ID
|
||||
- **WHEN** 客户端请求 `GET /api/targets/abc/metrics?from=ISO&to=ISO`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: bucket 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics?from=ISO&to=ISO` 未提供 bucket 参数
|
||||
- **THEN** 系统 SHALL 默认使用 bucket=`1h`
|
||||
|
||||
#### Scenario: 不支持的 bucket 参数
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/metrics?from=ISO&to=ISO&bucket=5m`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
### Requirement: TargetMetricsResponse 共享类型
|
||||
系统 SHALL 在 `src/shared/api.ts` 中定义 `TargetMetricsResponse` 类型。
|
||||
|
||||
#### Scenario: 类型定义
|
||||
- **WHEN** 前后端引用 `TargetMetricsResponse` 类型
|
||||
- **THEN** 该类型 SHALL 包含 targetId（number）、window（from/to/bucket）、stats 和 trend 字段
|
||||
|
||||
#### Scenario: stats 字段
|
||||
- **WHEN** metrics 响应包含 stats
|
||||
- **THEN** stats SHALL 包含 totalChecks、upChecks、downChecks、availability、avgDurationMs、p95DurationMs、p99DurationMs、mttr、longestOutage、incidentCount、currentStreak 字段
|
||||
|
||||
#### Scenario: trend 字段
|
||||
- **WHEN** metrics 响应包含 trend
|
||||
- **THEN** trend SHALL 为数组，每个元素包含 bucketStart、avgDurationMs、minDurationMs、maxDurationMs、availability、totalChecks、upChecks、downChecks 字段
|
||||
|
||||
### Requirement: P95/P99 延迟计算
|
||||
系统 SHALL 在后端应用层计算 P95 和 P99 延迟百分位数。
|
||||
|
||||
#### Scenario: 正常计算 P95
|
||||
- **WHEN** 时间窗口内存在成功检查记录（matched=1 且 duration_ms 不为 null）
|
||||
- **THEN** 系统 SHALL 取出所有成功检查的 duration_ms，在后端应用层排序后取第 95 百分位值返回为 p95DurationMs
|
||||
|
||||
#### Scenario: 正常计算 P99
|
||||
- **WHEN** 时间窗口内存在成功检查记录
|
||||
- **THEN** 系统 SHALL 取第 99 百分位值返回为 p99DurationMs
|
||||
|
||||
#### Scenario: 无成功检查记录
|
||||
- **WHEN** 时间窗口内无 matched=1 且 duration_ms 不为 null 的记录
|
||||
- **THEN** p95DurationMs 和 p99DurationMs SHALL 返回 null
|
||||
|
||||
#### Scenario: 百分位计算方法
|
||||
- **WHEN** 计算第 N 百分位
|
||||
- **THEN** 系统 SHALL 将 duration_ms 升序排列，取 index = ceil(count * N / 100) - 1 位置的值
|
||||
|
||||
### Requirement: MTTR 计算
|
||||
系统 SHALL 在后端应用层计算平均恢复时间（Mean Time To Recovery）。
|
||||
|
||||
#### Scenario: 存在已恢复的故障段
|
||||
- **WHEN** 时间窗口内存在至少一个已恢复的故障段（连续 matched=0 后跟 matched=1）
|
||||
- **THEN** 系统 SHALL 计算所有已恢复故障段的平均持续时间（从首个 matched=0 的 timestamp 到恢复后首个 matched=1 的 timestamp 之差），返回为 mttr（毫秒）
|
||||
|
||||
#### Scenario: 无已恢复的故障段
|
||||
- **WHEN** 时间窗口内无已恢复的故障段（全部正常，或当前仍在故障中且无历史恢复）
|
||||
- **THEN** mttr SHALL 返回 null
|
||||
|
||||
#### Scenario: 当前正在故障中
|
||||
- **WHEN** 时间窗口内最后一段故障尚未恢复
|
||||
- **THEN** 该未恢复的故障段 SHALL 不计入 MTTR 平均值
|
||||
|
||||
#### Scenario: 窗口起始即为故障且后续恢复
|
||||
- **WHEN** 时间窗口内第一条记录即为 matched=0（故障跨越了 from 边界），且该故障段在窗口内恢复
|
||||
- **THEN** 该故障段 SHALL 不计入 MTTR 平均值（因无法确定真实故障开始时间），但 SHALL 计入 incidentCount
|
||||
|
||||
### Requirement: 最长故障时长
|
||||
系统 SHALL 在后端应用层计算时间窗口内最长的单次故障持续时间。
|
||||
|
||||
#### Scenario: 存在故障段
|
||||
- **WHEN** 时间窗口内存在故障段
|
||||
- **THEN** 系统 SHALL 返回最长故障段的持续时间为 longestOutage（毫秒）
|
||||
|
||||
#### Scenario: 无故障
|
||||
- **WHEN** 时间窗口内无 matched=0 的记录
|
||||
- **THEN** longestOutage SHALL 返回 null
|
||||
|
||||
#### Scenario: 窗口起始即为故障
|
||||
- **WHEN** 时间窗口内第一条记录即为 matched=0
|
||||
- **THEN** 该故障段的持续时间 SHALL 从 from 参数开始计算
|
||||
|
||||
#### Scenario: 当前正在故障中
|
||||
- **WHEN** 最后一段故障尚未恢复
|
||||
- **THEN** 该故障段的持续时间 SHALL 计算为从故障开始到时间窗口 to 参数的时间差
|
||||
|
||||
### Requirement: 故障事件计数
|
||||
系统 SHALL 在后端应用层计算时间窗口内的故障事件次数。
|
||||
|
||||
#### Scenario: 计算故障事件数
|
||||
- **WHEN** 时间窗口内存在状态翻转（matched 从 1 变为 0）
|
||||
- **THEN** 系统 SHALL 返回翻转次数为 incidentCount
|
||||
|
||||
#### Scenario: 无故障事件
|
||||
- **WHEN** 时间窗口内所有检查均为 matched=1
|
||||
- **THEN** incidentCount SHALL 返回 0
|
||||
|
||||
#### Scenario: 窗口起始即为故障
|
||||
- **WHEN** 时间窗口内第一条记录即为 matched=0 且无前序记录可判断翻转
|
||||
- **THEN** 该故障 SHALL 计为 1 次事件
|
||||
|
||||
#### Scenario: 连续异常只计一次
|
||||
- **WHEN** 某目标连续 10 次 matched=0
|
||||
- **THEN** 该连续异常段 SHALL 仅计为 1 次事件
|
||||
|
||||
### Requirement: 当前连续状态
|
||||
系统 SHALL 返回目标当前的连续状态信息。
|
||||
|
||||
#### Scenario: 当前连续正常
|
||||
- **WHEN** 目标最近的检查记录连续为 matched=1
|
||||
- **THEN** currentStreak SHALL 返回 `{ up: true, count: N }`，N 为连续正常的检查次数
|
||||
|
||||
#### Scenario: 当前连续异常
|
||||
- **WHEN** 目标最近的检查记录连续为 matched=0
|
||||
- **THEN** currentStreak SHALL 返回 `{ up: false, count: N }`，N 为连续异常的检查次数
|
||||
|
||||
#### Scenario: 连续状态达到取数上限
|
||||
- **WHEN** 连续状态次数达到后端取数或计算上限
|
||||
- **THEN** currentStreak SHALL 返回 `{ up: boolean, count: N, capped: true }`，前端据此展示上限标记
|
||||
|
||||
#### Scenario: 无检查记录
|
||||
- **WHEN** 目标没有任何检查记录
|
||||
- **THEN** currentStreak SHALL 返回 null
|
||||
|
||||
### Requirement: 趋势数据应用层分桶
|
||||
系统 SHALL 在后端应用层按 UTC 小时分桶生成趋势数据。
|
||||
|
||||
#### Scenario: 按小时生成趋势
|
||||
- **WHEN** metrics 请求 bucket=`1h`
|
||||
- **THEN** 系统 SHALL 按 UTC 小时生成 trend 数组，每个点包含该小时内的 totalChecks、upChecks、downChecks、availability、avgDurationMs、minDurationMs、maxDurationMs
|
||||
|
||||
#### Scenario: 小时内无成功检查
|
||||
- **WHEN** 某小时内存在检查记录但无成功检查记录
|
||||
- **THEN** avgDurationMs、minDurationMs、maxDurationMs SHALL 返回 null，availability SHALL 基于 upChecks/totalChecks 返回 0
|
||||
|
||||
#### Scenario: 小时内无检查记录
|
||||
- **WHEN** 某小时内没有任何检查记录
|
||||
- **THEN** 系统 MAY 不返回该小时对应的 trend 点
|
||||
|
||||
### Requirement: 无数据口径
|
||||
系统 SHALL 对无数据窗口返回稳定的空指标口径。
|
||||
|
||||
#### Scenario: 窗口内无检查记录
|
||||
- **WHEN** 指定时间窗口内没有任何检查记录
|
||||
- **THEN** stats SHALL 返回 totalChecks=0、upChecks=0、downChecks=0、availability=0、avgDurationMs=null、p95DurationMs=null、p99DurationMs=null、mttr=null、longestOutage=null、incidentCount=0、currentStreak=null，trend SHALL 返回空数组
|
||||
@@ -52,12 +52,36 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立
|
||||
|
||||
#### Scenario: 可用率列
|
||||
- **WHEN** 表格渲染
|
||||
- **THEN** 可用率列 SHALL 使用 TDesign Progress 组件（theme=line, size=small）渲染，颜色通过 CSS 自定义属性 `--avail-N`（基于项目自定义色值）控制，每 10% 一档，label 显示百分比数值，支持排序（升序优先，最差排最前）。color-threshold 函数 SHALL 返回 CSS 自定义属性引用而非硬编码色值
|
||||
- **THEN** 可用率列标题 SHALL 展示为"可用率(24h)"（基于 Dashboard 默认 window=24h），使用 TDesign Progress 组件（theme=line, size=small）渲染，颜色通过 CSS 自定义属性 `--avail-N`（基于项目自定义色值）控制，每 10% 一档，label 显示百分比数值，支持排序（升序优先，最差排最前）。前端 SHALL 使用 DashboardResponse.targets[].stats.availability 字段作为数据来源。color-threshold 函数 SHALL 返回 CSS 自定义属性引用而非硬编码色值
|
||||
|
||||
#### Scenario: 最近状态列
|
||||
- **WHEN** 表格渲染
|
||||
- **THEN** 最近状态列 SHALL 使用 StatusBar 组件渲染采样色块，宽度 220px。StatusBar SHALL 通过 CSS 类（`.status-bar-block--up` / `.status-bar-block--down` / `.status-bar-block--empty`）控制色块颜色，不使用内联 style
|
||||
|
||||
#### Scenario: 连续状态列渲染
|
||||
- **WHEN** 表格渲染
|
||||
- **THEN** 表格 SHALL 在「最近状态」列之后、「延迟」列之前展示「连续状态」列，标题为"连续"，宽度 100px
|
||||
|
||||
#### Scenario: 连续正常展示
|
||||
- **WHEN** 目标 currentStreak 为 `{ up: true, count: N }`
|
||||
- **THEN** 列 SHALL 使用 TDesign Tag 组件（theme=success, variant=light, size=small）展示 "▲ N次"
|
||||
|
||||
#### Scenario: 连续异常展示
|
||||
- **WHEN** 目标 currentStreak 为 `{ up: false, count: N }`
|
||||
- **THEN** 列 SHALL 使用 TDesign Tag 组件（theme=danger, variant=light, size=small）展示 "▼ N次"
|
||||
|
||||
#### Scenario: 连续状态数据来源
|
||||
- **WHEN** 表格需要渲染连续状态
|
||||
- **THEN** 前端 SHALL 使用 DashboardResponse.targets[].currentStreak 字段，不在表格列中自行遍历 recentSamples 计算核心指标
|
||||
|
||||
#### Scenario: 超过样本上限
|
||||
- **WHEN** currentStreak.capped 为 true
|
||||
- **THEN** 列 SHALL 展示 "▲ N+" 或 "▼ N+"
|
||||
|
||||
#### Scenario: 无样本数据
|
||||
- **WHEN** 目标 currentStreak 为 null
|
||||
- **THEN** 列 SHALL 展示 "-"
|
||||
|
||||
#### Scenario: 延迟列
|
||||
- **WHEN** 表格渲染
|
||||
- **THEN** 延迟列 SHALL 显示最近一次检查的延迟毫秒数，右对齐。颜色 SHALL 通过 CSS 类实现：≤100ms 使用 `.latency-ok`、100-500ms 使用 `.latency-warn`、>500ms 使用 `.latency-error`。无数据 SHALL 使用 `.text-disabled` 类显示 "-"，数值 SHALL 使用 `.tabular-nums` 类等宽显示。不使用内联 style
|
||||
|
||||
Reference in New Issue
Block a user