1
0

feat: 新增两个 OpenSpec 变更提案 — CMD Checker 增强与前端指标增强

This commit is contained in:
2026-05-14 01:39:26 +08:00
parent 6e485cc991
commit 0fa2c0c811
18 changed files with 952 additions and 0 deletions

View File

@@ -0,0 +1,53 @@
## 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 为 nullrecentSamples 为空数组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` 字段(语义变更为基于时间窗口计算)

View File

@@ -0,0 +1,20 @@
## 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.Texttheme="secondary"
#### Scenario: 数据新鲜度警告
- **WHEN** lastCheckTime 距当前时间超过 60 秒
- **THEN** 相对时间文本 SHALL 使用警告色(--td-warning-color
#### Scenario: 统计数据自动刷新
- **WHEN** 页面处于打开状态
- **THEN** 统计卡片 SHALL 通过 TanStack Query 的 refetchInterval=8000 自动刷新数据

View File

@@ -0,0 +1,80 @@
## 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 或 DOWNmatched=true 为 UPmatched=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 返回空数组

View File

@@ -0,0 +1,111 @@
## 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 Divideralign="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 来自 statsDataTargetStatsResponse第二行数据同样来自 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 RadioGroupvariant=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 DateRangePickermode=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 变化自动重新请求

View File

@@ -0,0 +1,106 @@
## 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 包含 p95DurationMsnumber | null、p99DurationMsnumber | null、avgDurationMsnumber | null、mttrnumber | null、longestOutagenumber | null、incidentCountnumber、currentStreak{ up: boolean; count: number }、totalChecksnumber、upChecksnumber、downChecksnumber、availabilitynumber

View File

@@ -0,0 +1,28 @@
## 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 展示 "-"