diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index cd4fcb6..320e902 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -30,10 +30,9 @@ src/ routes/ API 路由 handler（按端点拆分） health.ts GET /health（无 store 参数） meta.ts GET /api/meta - summary.ts GET /api/summary - targets.ts GET /api/targets + dashboard.ts GET /api/dashboard + metrics.ts GET /api/targets/:id/metrics history.ts GET /api/targets/:id/history - trend.ts GET /api/targets/:id/trend checker/ types.ts 基础类型定义（ResolvedTargetBase、RawTargetConfig、DefaultsConfig、CheckResult 等基础 interface） config-loader.ts YAML 配置解析、契约校验、语义校验与运行期解析（输出 ResolvedConfig） @@ -73,11 +72,10 @@ src/ target-table-sorters.ts 表格排序器 color-threshold.ts 可用率颜色阈值函数 hooks/ TanStack Query 数据层 - use-queries.ts 全局面板查询 hook（summary/targets/meta） + use-queries.ts 全局面板查询 hook（dashboard/meta/metrics） use-target-detail.ts 目标详情 Drawer 状态与条件查询 hook utils/ 前端工具函数 - time.ts 时间处理（subtractHours） - stats.ts 趋势统计计算（computeTrendStats） + time.ts 时间处理（subtractHours、相对时间、动态时长单位） scripts/ 构建、schema 生成和清理脚本 tests/ Bun test 测试（结构镜像 src 目录） openspec/ OpenSpec 变更与规格文档 @@ -142,10 +140,9 @@ routes: { "/*": homepage, // HTML import，SPA fallback "/api/*": () => jsonResponse(createApiError("API route not found", 404), { mode, status: 404 }), "/api/meta": { GET: () => handleMeta(mode) }, - "/api/summary": { GET: () => handleSummary(store, mode) }, - "/api/targets": { GET: () => handleTargets(store, mode) }, + "/api/dashboard": { GET: (req) => handleDashboard(new URL(req.url), store, mode) }, "/api/targets/:id/history": { GET: (req) => handleHistory(req.params.id, new URL(req.url), store, mode) }, - "/api/targets/:id/trend": { GET: (req) => handleTrend(req.params.id, new URL(req.url), store, mode) }, + "/api/targets/:id/metrics": { GET: (req) => handleMetrics(req.params.id, new URL(req.url), store, mode) }, "/health": { GET: () => handleHealth(mode) }, } ``` @@ -157,20 +154,17 @@ Handler 函数签名因端点而异： export function handleHealth(mode: RuntimeMode): Response; export function handleMeta(mode: RuntimeMode): Response; -// 仅有 store 的路由 -export function handleSummary(store: ProbeStore, mode: RuntimeMode): Response; -export function handleTargets(store: ProbeStore, mode: RuntimeMode): Response; - // 带 target ID 和查询参数的路由 +export function handleDashboard(url: URL, store: ProbeStore, mode: RuntimeMode): Response; export function handleHistory(idStr: string, url: URL, store: ProbeStore, mode: RuntimeMode): Response; -export function handleTrend(idStr: string, url: URL, store: ProbeStore, mode: RuntimeMode): Response; +export function handleMetrics(idStr: string, url: URL, store: ProbeStore, mode: RuntimeMode): Response; ``` **请求处理流程**： 1. `Bun.serve` 的 `routes` 对象按路径 + HTTP 方法匹配请求 2. 未匹配方法的请求落入 `/api/*` 通配符（返回 404） -3. 各 handler 内部通过 `middleware.ts` 提供的 `validateTargetId`、`validateTimeRange`、`validatePagination` 做参数校验，`pageSize` 最大值为 `200` +3. 各 handler 内部通过 `middleware.ts` 提供的 `validateTargetId`、`validateTimeRange`、`validatePagination`、`validateDashboardWindow`、`validateRecentLimit`、`validateMetricsBucket` 做参数校验，`pageSize` 最大值为 `200` 4. 校验函数返回 `Response` 实例表示校验失败（直接返回），返回数据对象表示通过 5. 业务逻辑通过 `store` 查询数据，用 `helpers.ts` 的 `jsonResponse`、`mapCheckResult`、`formatDuration` 等格式化输出 @@ -190,7 +184,7 @@ export function handleTrend(idStr: string, url: URL, store: ProbeStore, mode: Ru - `formatDuration(ms)` — 毫秒转为可读时长字符串 - `jsonResponse(body, options)` — JSON 响应构造 - `mapCheckResult(row)` — 数据库行转 API CheckResult -- **`middleware.ts`**：API 参数校验函数（`validateTargetId`、`validateTimeRange`、`validatePagination`，其中 `pageSize` 上限为 `200`） +- **`middleware.ts`**：API 参数校验函数（`validateTargetId`、`validateTimeRange`、`validatePagination`、`validateDashboardWindow`、`validateRecentLimit`、`validateMetricsBucket`，其中 `pageSize` 和 `recentLimit` 上限为 `200`） ### 1.5 类型定义规范 @@ -428,19 +422,20 @@ TcpChecker implements Checker **核心方法**： -| 方法 | 用途 | -| ----------------------- | ---------------------------------------------------------------- | -| `syncTargets(targets)` | 启动期同步 targets（基于 name 做 upsert + delete 事务） | -| `insertCheckResult()` | 写入单条检查结果 | -| `getTargets()` | 查询全部 targets（default 分组优先排序） | -| `getLatestChecksMap()` | 批量获取每个 target 的最新检查结果（单次 SQL 聚合） | -| `getAllTargetStats()` | 批量获取每个 target 的可用率统计（GROUP BY 聚合） | -| `getAllRecentSamples()` | 批量获取每个 target 的最近 N 条采样（window function） | -| `getSummary()` | 获取总览统计（基于 `getLatestChecksMap` 内存计算 up/down/total） | -| `getTrend()` | 获取按小时聚合的趋势数据 | -| `getHistory()` | 分页查询历史记录 | -| `getRecentSamples()` | 获取最近 N 条采样数据（用于状态条渲染） | -| `prune(retentionMs)` | 按 retention 策略清理过期数据（由 engine 定时调用） | +| 方法 | 用途 | +| ------------------------------------------ | ----------------------------------------------------------- | +| `syncTargets(targets)` | 启动期同步 targets（基于 name 做 upsert + delete 事务） | +| `insertCheckResult()` | 写入单条检查结果 | +| `getTargets()` | 查询全部 targets（default 分组优先排序） | +| `getLatestChecksMap()` | 批量获取每个 target 的最新检查结果（单次 SQL 聚合） | +| `getAllTargetWindowStats(from, to)` | 批量获取窗口内每个 target 的 total/up/down 基础计数 | +| `getDashboardIncidentStates(from, to)` | 获取 Dashboard 窗口内状态序列，供应用层计算 incidents | +| `getAllRecentSamples(limit)` | 批量获取每个 target 的最近 N 条采样（用于状态条和连续状态） | +| `getTargetCheckpoints(targetId, from, to)` | 获取单目标窗口内检查点序列，供 metrics 应用层分桶和故障分析 | +| `getTargetDurations(targetId, from, to)` | 获取单目标窗口内成功检查耗时升序数组，供应用层计算 P95/P99 | +| `getHistory()` | 分页查询历史记录 | +| `getRecentSamples()` | 获取最近 N 条采样数据（用于状态条渲染） | +| `prune(retentionMs)` | 按 retention 策略清理过期数据（由 engine 定时调用） | **Statement 使用规范**： @@ -453,7 +448,13 @@ TcpChecker implements Checker - 避免 N+1 查询：批量场景优先用单次 SQL 聚合（GROUP BY、子查询 JOIN）+ 内存组装 - 新增批量查询方法时必须编写对应单元测试 -- `getSummary()` 和 `GET /api/targets` 的响应组装已通过 `getLatestChecksMap` + `getAllTargetStats` + `getAllRecentSamples` 实现批量查询 +- `GET /api/dashboard` 的响应组装通过 `getLatestChecksMap` + `getAllTargetWindowStats` + `getAllRecentSamples` + `getDashboardIncidentStates` 实现批量查询 + +**轻数据库指标计算规范**： + +- 数据库只负责存储、筛选、排序、分页、LIMIT 和标准 SQL 基础聚合（如 `COUNT`、`SUM(CASE)`、`AVG`、`MIN`、`MAX`、`GROUP BY`），用于减少应用层输入数据量 +- 指标语义必须在后端应用层实现，包括可用率舍入、百分位、状态翻转、故障段识别、MTTR、最长故障、连续状态、趋势 UTC 小时分桶和窗口边界处理 +- 禁止用 SQLite 专有时间函数承载趋势分桶语义，禁止用复杂 SQL/window function 承载故障事件或恢复时长等业务规则 **Schema**： @@ -553,15 +554,15 @@ main.tsx └── ErrorBoundary（React 错误边界） └── QueryClientProvider（TanStack Query 全局挂载） ├── App（根组件） + │ ├── useDashboard() ─── GET /api/dashboard?window=24h&recentLimit=30（8s 轮询） │ ├── SummaryCards（总览统计卡片） - │ │ └── useSummary() ─── GET /api/summary（8s 轮询） │ └── TargetBoard（目标列表） - │ ├── useTargets() ─── GET /api/targets（8s 轮询） - │ ├── useMeta() ────── GET /api/meta（应用生命周期内缓存） + │ ├── DashboardResponse.targets + │ ├── useMeta() ───── GET /api/meta（应用生命周期内缓存） │ └── TargetGroup[]（按 group 字段分组） │ └── PrimaryTable ← createTargetTableColumns(checkerTypes) │ └── TargetDetailDrawer（目标详情抽屉） - │ └── useTargetDetail() ── 按需发起 trend + history 查询 + │ └── useTargetDetail() ── 按需发起 metrics + history 查询 │ ├── OverviewTab → Statistic + TrendChart + StatusDonut + Descriptions │ └── HistoryTab → PrimaryTable（分页历史记录） └── ReactQueryDevtools（开发工具，仅开发环境） @@ -571,14 +572,14 @@ main.tsx ``` hooks/use-queries.ts（全局面板级查询） -├── queryKeys（summary/targets/meta 结构化 query key） -├── useSummary() → /api/summary（8s 自动轮询） -├── useTargets() → /api/targets（8s 自动轮询） -└── useMeta() → /api/meta（staleTime: Infinity） +├── queryKeys（dashboard/meta/metrics 结构化 query key） +├── useDashboard() → /api/dashboard?window=24h&recentLimit=30（8s 自动轮询） +├── useTargetMetrics() → /api/targets/:id/metrics（详情按需加载） +└── useMeta() → /api/meta（staleTime: Infinity） hooks/use-target-detail.ts（Drawer 状态与详情级条件查询） -├── 内部复用 useTargets() 的缓存来查找 selectedTarget -├── useQuery(/api/targets/:id/trend)（条件查询：enabled 仅当 Drawer 打开且时间范围有效） +├── 内部复用 useDashboard() 的缓存来查找 selectedTarget +├── useTargetMetrics(/api/targets/:id/metrics)（条件查询：enabled 仅当 Drawer 打开且时间范围有效） └── useQuery(/api/targets/:id/history)（条件查询：含分页） ``` @@ -588,10 +589,10 @@ hooks/use-target-detail.ts（Drawer 状态与详情级条件查询） ```typescript const queryKeys = { - summary: () => ["summary"] as const, - targets: () => ["targets"] as const, + dashboard: () => ["dashboard", "24h", 30] as const, meta: () => ["meta"] as const, - trend: (targetId: number, from: string, to: string) => ["trend", targetId, from, to] as const, + metrics: (targetId: number, from: string, to: string, bucket: "1h") => + ["metrics", targetId, from, to, bucket] as const, history: (targetId: number, from: string, to: string, page: number) => ["history", targetId, from, to, page] as const, }; ``` @@ -605,16 +606,16 @@ const queryKeys = { ```typescript // 全局面板级查询（需要持续刷新） useQuery({ - queryKey: queryKeys.summary(), - queryFn: () => fetchJson("/api/summary"), + queryKey: queryKeys.dashboard(), + queryFn: () => fetchJson("/api/dashboard?window=24h&recentLimit=30"), refetchInterval: 8000, // 自动轮询间隔 refetchIntervalInBackground: false, // 切后台不轮询 }); // 详情级查询（按需加载） useQuery({ - queryKey: selectedTargetId ? queryKeys.trend(id, from, to) : ["trend", "disabled"], - queryFn: () => fetchJson(`/api/targets/${id}/trend?...`), + queryKey: selectedTargetId ? queryKeys.metrics(id, from, to, "1h") : ["metrics", "disabled"], + queryFn: () => fetchJson(`/api/targets/${id}/metrics?...`), enabled: selectedTargetId !== null && !!timeFrom && !!timeTo, // 条件查询 }); ``` @@ -769,7 +770,7 @@ const server = Bun.serve({ routes: { "/*": homepage, // SPA fallback（开发模式自动注入 HMR） "/api/*": () => ..., // API 通配符（未匹配路由返回 404） - "/api/summary": { GET: () => handleSummary(store, mode) }, + "/api/dashboard": { GET: (req) => handleDashboard(new URL(req.url), store, mode) }, "/health": { GET: () => handleHealth(mode) }, // ... }, @@ -781,9 +782,9 @@ const server = Bun.serve({ #### 路由优先级 -Bun routes 的匹配规则：具体路径 > 通配符。`/api/summary` 优先于 `/api/*`，`/health` 优先于 `/*`。 +Bun routes 的匹配规则：具体路径 > 通配符。`/api/dashboard` 优先于 `/api/*`，`/health` 优先于 `/*`。 -未匹配 method 的请求（如 POST /api/summary）会落入 `/api/*` 通配符返回 404。 +未匹配 method 的请求（如 POST /api/dashboard）会落入 `/api/*` 通配符返回 404。 ### 3.3 构建打包 diff --git a/README.md b/README.md index 1d88cbf..28cebd1 100644 --- a/README.md +++ b/README.md @@ -166,18 +166,19 @@ JSON Schema：仓库根目录导出 `probe-config.schema.json`，可在 YAML 文 | ----------------------------------------------------------------- | ------------------------------------------------------------ | | `GET /health` | 健康检查 | | `GET /api/meta` | 运行时元信息（checker 类型列表） | -| `GET /api/summary` | 总览统计（total/up/down/lastCheckTime） | -| `GET /api/targets` | 目标列表及最新状态、分组和采样数据 | +| `GET /api/dashboard?window=24h&recentLimit=30` | Dashboard 首屏聚合数据（summary + targets） | +| `GET /api/targets/:id/metrics?from=ISO&to=ISO&bucket=1h` | 指定目标的统计、可靠性指标和按小时趋势 | | `GET /api/targets/:id/history?from=ISO&to=ISO&page=1&pageSize=20` | 指定目标的拨测记录（时间范围 + 分页，`pageSize` 最大 `200`） | -| `GET /api/targets/:id/trend?from=ISO&to=ISO` | 指定目标的按小时聚合趋势 | ### 响应字段 -**SummaryResponse**: `total`、`up`、`down`、`lastCheckTime` +**DashboardResponse**: `summary`、`targets` + +**DashboardResponse.summary**: `total`、`up`、`down`、`lastCheckTime`、`incidents`、`window` **MetaResponse**: `checkerTypes`（已注册 checker 类型标识符列表） -**TargetStatus**: `id`、`name`、`type`（checker 类型，如 http/cmd）、`target`（URL 或命令摘要）、`group`、`interval`、`latestCheck`、`stats`、`recentSamples` +**TargetStatus**: `id`、`name`、`type`（checker 类型，如 http/cmd）、`target`（URL 或命令摘要）、`group`、`interval`、`latestCheck`、`stats`、`currentStreak`、`recentSamples` **RecentSample**: `timestamp`、`durationMs`、`up` @@ -185,9 +186,15 @@ JSON Schema：仓库根目录导出 `probe-config.schema.json`，可在 YAML 文 **CheckFailure**: `kind`（error/mismatch）、`phase`、`path`、`message`、`expected?`（仅 mismatch）、`actual?`（仅 mismatch） -**TargetStats**: `totalChecks`、`availability` +**TargetStats**: `totalChecks`、`upChecks`、`downChecks`、`availability` -**TrendPoint**: `hour`、`avgDurationMs`、`availability`、`totalChecks` +**CurrentStreak**: `up`、`count`、`capped?` + +**TargetMetricsResponse**: `targetId`、`window`、`stats`、`trend` + +**TargetMetricsResponse.stats**: `totalChecks`、`upChecks`、`downChecks`、`availability`、`avgDurationMs`、`p95DurationMs`、`p99DurationMs`、`mttr`、`longestOutage`、`incidentCount`、`currentStreak` + +**TrendPoint**: `bucketStart`、`avgDurationMs`、`minDurationMs`、`maxDurationMs`、`availability`、`totalChecks`、`upChecks`、`downChecks` **HistoryResponse**: `items`（CheckResult[]）、`total`、`page`、`pageSize` diff --git a/openspec/changes/enhance-frontend-metrics/.openspec.yaml b/openspec/changes/enhance-frontend-metrics/.openspec.yaml deleted file mode 100644 index 93831bd..0000000 --- a/openspec/changes/enhance-frontend-metrics/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-05-13 diff --git a/openspec/changes/enhance-frontend-metrics/design.md b/openspec/changes/enhance-frontend-metrics/design.md deleted file mode 100644 index a404b0c..0000000 --- a/openspec/changes/enhance-frontend-metrics/design.md +++ /dev/null @@ -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 `` 的 `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 `` 组件渲染 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 窗口内的事件计数，该误差可接受且难以避免（需要额外查询窗口外数据才能消除） diff --git a/openspec/changes/enhance-frontend-metrics/proposal.md b/openspec/changes/enhance-frontend-metrics/proposal.md deleted file mode 100644 index e4cc98a..0000000 --- a/openspec/changes/enhance-frontend-metrics/proposal.md +++ /dev/null @@ -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` 的响应结构 diff --git a/openspec/changes/enhance-frontend-metrics/specs/probe-api/spec.md b/openspec/changes/enhance-frontend-metrics/specs/probe-api/spec.md deleted file mode 100644 index 362b506..0000000 --- a/openspec/changes/enhance-frontend-metrics/specs/probe-api/spec.md +++ /dev/null @@ -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` 字段（语义变更为基于时间窗口计算） diff --git a/openspec/changes/enhance-frontend-metrics/specs/probe-dashboard/spec.md b/openspec/changes/enhance-frontend-metrics/specs/probe-dashboard/spec.md deleted file mode 100644 index 8706c18..0000000 --- a/openspec/changes/enhance-frontend-metrics/specs/probe-dashboard/spec.md +++ /dev/null @@ -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 自动刷新数据 diff --git a/openspec/changes/enhance-frontend-metrics/specs/probe-data-store/spec.md b/openspec/changes/enhance-frontend-metrics/specs/probe-data-store/spec.md deleted file mode 100644 index 02a1df3..0000000 --- a/openspec/changes/enhance-frontend-metrics/specs/probe-data-store/spec.md +++ /dev/null @@ -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 返回空数组 diff --git a/openspec/changes/enhance-frontend-metrics/specs/target-detail-drawer/spec.md b/openspec/changes/enhance-frontend-metrics/specs/target-detail-drawer/spec.md deleted file mode 100644 index 6ce61b1..0000000 --- a/openspec/changes/enhance-frontend-metrics/specs/target-detail-drawer/spec.md +++ /dev/null @@ -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 变化自动重新请求 diff --git a/openspec/changes/enhance-frontend-metrics/specs/target-stats-api/spec.md b/openspec/changes/enhance-frontend-metrics/specs/target-stats-api/spec.md deleted file mode 100644 index 4b115cd..0000000 --- a/openspec/changes/enhance-frontend-metrics/specs/target-stats-api/spec.md +++ /dev/null @@ -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） diff --git a/openspec/changes/enhance-frontend-metrics/specs/target-table/spec.md b/openspec/changes/enhance-frontend-metrics/specs/target-table/spec.md deleted file mode 100644 index 34969f5..0000000 --- a/openspec/changes/enhance-frontend-metrics/specs/target-table/spec.md +++ /dev/null @@ -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 展示 "-" diff --git a/openspec/changes/enhance-frontend-metrics/tasks.md b/openspec/changes/enhance-frontend-metrics/tasks.md deleted file mode 100644 index 1d26ed7..0000000 --- a/openspec/changes/enhance-frontend-metrics/tasks.md +++ /dev/null @@ -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 和格式检查，修复所有问题 diff --git a/openspec/specs/probe-api/spec.md b/openspec/specs/probe-api/spec.md index eccfbf3..a8d3012 100644 --- a/openspec/specs/probe-api/spec.md +++ b/openspec/specs/probe-api/spec.md @@ -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 契约 diff --git a/openspec/specs/probe-dashboard/spec.md b/openspec/specs/probe-dashboard/spec.md index 0ae3e91..9b019e5 100644 --- a/openspec/specs/probe-dashboard/spec.md +++ b/openspec/specs/probe-dashboard/spec.md @@ -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 组件渲染标题和副标题。 diff --git a/openspec/specs/probe-data-store/spec.md b/openspec/specs/probe-data-store/spec.md index 463353f..b4727de 100644 --- a/openspec/specs/probe-data-store/spec.md +++ b/openspec/specs/probe-data-store/spec.md @@ -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`。 diff --git a/openspec/specs/target-detail-drawer/spec.md b/openspec/specs/target-detail-drawer/spec.md index f8f6b04..ef5992c 100644 --- a/openspec/specs/target-detail-drawer/spec.md +++ b/openspec/specs/target-detail-drawer/spec.md @@ -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** 概览面板渲染 diff --git a/openspec/specs/target-metrics-api/spec.md b/openspec/specs/target-metrics-api/spec.md new file mode 100644 index 0000000..1f04671 --- /dev/null +++ b/openspec/specs/target-metrics-api/spec.md @@ -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 返回空数组 diff --git a/openspec/specs/target-table/spec.md b/openspec/specs/target-table/spec.md index 166b2c4..f6ec46d 100644 --- a/openspec/specs/target-table/spec.md +++ b/openspec/specs/target-table/spec.md @@ -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 diff --git a/src/server/checker/store.ts b/src/server/checker/store.ts index 0afda87..77d050e 100644 --- a/src/server/checker/store.ts +++ b/src/server/checker/store.ts @@ -60,6 +60,8 @@ export class ProbeStore { getAllRecentSamples( limit: number, ): Map> { + if (this.closed) return new Map(); + const rows = this.db .query( `SELECT target_id, timestamp, duration_ms, matched @@ -91,24 +93,55 @@ export class ProbeStore { return result; } - getAllTargetStats(): Map { + getAllTargetWindowStats( + from: string, + to: string, + ): Map { + if (this.closed) return new Map(); + const rows = this.db .query( `SELECT target_id, COUNT(*) as totalChecks, - COALESCE(SUM(CASE WHEN matched = 1 THEN 1 ELSE 0 END), 0) as upCount + COALESCE(SUM(CASE WHEN matched = 1 THEN 1 ELSE 0 END), 0) as upChecks, + COALESCE(SUM(CASE WHEN matched = 0 THEN 1 ELSE 0 END), 0) as downChecks FROM check_results + WHERE timestamp >= ? AND timestamp <= ? GROUP BY target_id`, ) - .all() as Array<{ target_id: number; totalChecks: number; upCount: number }>; + .all(from, to) as Array<{ downChecks: number; target_id: number; totalChecks: number; upChecks: number }>; - const result = new Map(); + const result = new Map< + number, + { availability: number; downChecks: number; totalChecks: number; upChecks: number } + >(); for (const row of rows) { - const availability = row.totalChecks > 0 ? Math.round((row.upCount / row.totalChecks) * 100 * 100) / 100 : 0; - result.set(row.target_id, { availability, totalChecks: row.totalChecks }); + const availability = row.totalChecks > 0 ? Math.round((row.upChecks / row.totalChecks) * 100 * 100) / 100 : 0; + result.set(row.target_id, { + availability, + downChecks: row.downChecks, + totalChecks: row.totalChecks, + upChecks: row.upChecks, + }); } return result; } + getDashboardIncidentStates( + from: string, + to: string, + ): Array<{ matched: number; target_id: number; timestamp: string }> { + if (this.closed) return []; + + return this.db + .query( + `SELECT target_id, timestamp, matched + FROM check_results + WHERE timestamp >= ? AND timestamp <= ? + ORDER BY target_id ASC, timestamp ASC`, + ) + .all(from, to) as Array<{ matched: number; target_id: number; timestamp: string }>; + } + getHistory( targetId: number, from: string, @@ -165,49 +198,43 @@ export class ProbeStore { }>; } - getSummary(): { - down: number; - lastCheckTime: null | string; - total: number; - up: number; - } { - const targets = this.getTargets(); - const latestChecksMap = this.getLatestChecksMap(); - let up = 0; - let down = 0; - let lastCheckTime: null | string = null; - - for (const target of targets) { - const latest = latestChecksMap.get(target.id); - - if (latest) { - if (latest.matched) { - up++; - } else { - down++; - } - - if (!lastCheckTime || latest.timestamp > lastCheckTime) { - lastCheckTime = latest.timestamp; - } - } else { - down++; - } - } - - return { - down, - lastCheckTime, - total: targets.length, - up, - }; - } - getTargetById(id: number): null | StoredTarget { if (this.closed) return null; return this.db.query("SELECT * FROM targets WHERE id = ?").get(id) as null | StoredTarget; } + getTargetCheckpoints( + targetId: number, + from: string, + to: string, + ): Array<{ duration_ms: null | number; matched: number; timestamp: string }> { + if (this.closed) return []; + + return this.db + .query( + `SELECT timestamp, matched, duration_ms + FROM check_results + WHERE target_id = ? AND timestamp >= ? AND timestamp <= ? + ORDER BY timestamp ASC`, + ) + .all(targetId, from, to) as Array<{ duration_ms: null | number; matched: number; timestamp: string }>; + } + + getTargetDurations(targetId: number, from: string, to: string): number[] { + if (this.closed) return []; + + const rows = this.db + .query( + `SELECT duration_ms + FROM check_results + WHERE target_id = ? AND timestamp >= ? AND timestamp <= ? AND matched = 1 AND duration_ms IS NOT NULL + ORDER BY duration_ms ASC`, + ) + .all(targetId, from, to) as Array<{ duration_ms: number }>; + + return rows.map((row) => row.duration_ms); + } + getTargets(): StoredTarget[] { if (this.closed) return []; return this.db @@ -215,59 +242,40 @@ export class ProbeStore { .all() as StoredTarget[]; } - getTargetStats(targetId: number): { + getTargetWindowStats( + targetId: number, + from: string, + to: string, + ): { availability: number; + downChecks: number; totalChecks: number; + upChecks: number; } { + if (this.closed) return { availability: 0, downChecks: 0, totalChecks: 0, upChecks: 0 }; + const row = this.db .query( `SELECT COUNT(*) as totalChecks, - COALESCE(SUM(CASE WHEN matched = 1 THEN 1 ELSE 0 END), 0) as upCount + COALESCE(SUM(CASE WHEN matched = 1 THEN 1 ELSE 0 END), 0) as upChecks, + COALESCE(SUM(CASE WHEN matched = 0 THEN 1 ELSE 0 END), 0) as downChecks FROM check_results - WHERE target_id = ?`, + WHERE target_id = ? AND timestamp >= ? AND timestamp <= ?`, ) - .get(targetId) as { totalChecks: number; upCount: number }; + .get(targetId, from, to) as { downChecks: number; totalChecks: number; upChecks: number }; const totalChecks = row.totalChecks; - const availability = totalChecks > 0 ? (row.upCount / totalChecks) * 100 : 0; + const availability = totalChecks > 0 ? (row.upChecks / totalChecks) * 100 : 0; return { availability: Math.round(availability * 100) / 100, + downChecks: row.downChecks, totalChecks, + upChecks: row.upChecks, }; } - getTrend( - targetId: number, - from: string, - to: string, - ): Array<{ - availability: number; - avgDurationMs: null | number; - hour: string; - totalChecks: number; - }> { - return this.db - .query( - `SELECT - strftime('%Y-%m-%dT%H:00:00', timestamp) as hour, - AVG(CASE WHEN matched = 1 THEN duration_ms END) as avgDurationMs, - CASE WHEN COUNT(*) > 0 THEN (SUM(CASE WHEN matched = 1 THEN 1 ELSE 0 END) * 100.0 / COUNT(*)) ELSE 0 END as availability, - COUNT(*) as totalChecks - FROM check_results - WHERE target_id = ? AND timestamp >= ? AND timestamp <= ? - GROUP BY hour - ORDER BY hour`, - ) - .all(targetId, from, to) as Array<{ - availability: number; - avgDurationMs: null | number; - hour: string; - totalChecks: number; - }>; - } - insertCheckResult(result: { durationMs: null | number; failure: CheckFailure | null; diff --git a/src/server/metrics.ts b/src/server/metrics.ts new file mode 100644 index 0000000..72a3c79 --- /dev/null +++ b/src/server/metrics.ts @@ -0,0 +1,157 @@ +import type { CurrentStreak, TrendPoint } from "../shared/api"; + +export interface IncidentAnalysis { + incidentCount: number; + longestOutage: null | number; + mttr: null | number; +} + +export interface MetricCheckpoint { + durationMs: null | number; + matched: boolean; + timestamp: string; +} + +export function analyzeIncidentSequence(checkpoints: MetricCheckpoint[], from: string, to: string): IncidentAnalysis { + const sorted = sortCheckpoints(checkpoints); + const fromTime = new Date(from).getTime(); + const toTime = new Date(to).getTime(); + const recoveredDurations: number[] = []; + + let incidentCount = 0; + let longestOutage: null | number = null; + let outageStart: null | number = null; + let outageStartedAtWindowBoundary = false; + let previousMatched: boolean | null = null; + + for (const checkpoint of sorted) { + const timestamp = new Date(checkpoint.timestamp).getTime(); + + if (!checkpoint.matched) { + if (previousMatched !== false) { + incidentCount++; + outageStart = previousMatched === null ? fromTime : timestamp; + outageStartedAtWindowBoundary = previousMatched === null; + } + } else if (previousMatched === false && outageStart !== null) { + const duration = Math.max(0, timestamp - outageStart); + longestOutage = maxNullable(longestOutage, duration); + if (!outageStartedAtWindowBoundary) { + recoveredDurations.push(duration); + } + outageStart = null; + outageStartedAtWindowBoundary = false; + } + + previousMatched = checkpoint.matched; + } + + if (previousMatched === false && outageStart !== null) { + const duration = Math.max(0, toTime - outageStart); + longestOutage = maxNullable(longestOutage, duration); + } + + return { + incidentCount, + longestOutage, + mttr: calculateAverageDuration(recoveredDurations), + }; +} + +export function buildHourlyTrend(checkpoints: MetricCheckpoint[]): TrendPoint[] { + const buckets = new Map< + string, + { + downChecks: number; + durations: number[]; + totalChecks: number; + upChecks: number; + } + >(); + + for (const checkpoint of checkpoints) { + const bucketStart = getUtcHourStart(checkpoint.timestamp); + const bucket = buckets.get(bucketStart) ?? { downChecks: 0, durations: [], totalChecks: 0, upChecks: 0 }; + + bucket.totalChecks++; + if (checkpoint.matched) { + bucket.upChecks++; + if (checkpoint.durationMs !== null) { + bucket.durations.push(checkpoint.durationMs); + } + } else { + bucket.downChecks++; + } + + buckets.set(bucketStart, bucket); + } + + return [...buckets.entries()] + .sort(([left], [right]) => left.localeCompare(right)) + .map(([bucketStart, bucket]) => ({ + availability: calculateAvailability(bucket.upChecks, bucket.totalChecks), + avgDurationMs: calculateAverageDuration(bucket.durations), + bucketStart, + downChecks: bucket.downChecks, + maxDurationMs: bucket.durations.length > 0 ? Math.max(...bucket.durations) : null, + minDurationMs: bucket.durations.length > 0 ? Math.min(...bucket.durations) : null, + totalChecks: bucket.totalChecks, + upChecks: bucket.upChecks, + })); +} + +export function calculateAvailability(upChecks: number, totalChecks: number): number { + if (totalChecks <= 0) return 0; + return roundToTwo((upChecks / totalChecks) * 100); +} + +export function calculateAverageDuration(durations: number[]): null | number { + if (durations.length === 0) return null; + const total = durations.reduce((sum, duration) => sum + duration, 0); + return roundToTwo(total / durations.length); +} + +export function calculateCurrentStreak(checkpoints: MetricCheckpoint[], limit?: number): CurrentStreak | null { + const sorted = sortCheckpoints(checkpoints); + const latest = sorted.at(-1); + if (!latest) return null; + + let count = 0; + for (let index = sorted.length - 1; index >= 0; index--) { + const checkpoint = sorted[index]; + if (checkpoint?.matched !== latest.matched) break; + count++; + } + + return { + ...(limit !== undefined && count >= limit ? { capped: true } : {}), + count, + up: latest.matched, + }; +} + +export function calculatePercentile(durations: number[], percentile: number): null | number { + if (durations.length === 0) return null; + + const sorted = [...durations].sort((a, b) => a - b); + const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil((sorted.length * percentile) / 100) - 1)); + return sorted[index] ?? null; +} + +function getUtcHourStart(timestamp: string): string { + const date = new Date(timestamp); + date.setUTCMinutes(0, 0, 0); + return date.toISOString(); +} + +function maxNullable(left: null | number, right: number): number { + return left === null ? right : Math.max(left, right); +} + +function roundToTwo(value: number): number { + return Math.round(value * 100) / 100; +} + +function sortCheckpoints(checkpoints: MetricCheckpoint[]): MetricCheckpoint[] { + return [...checkpoints].sort((left, right) => left.timestamp.localeCompare(right.timestamp)); +} diff --git a/src/server/middleware.ts b/src/server/middleware.ts index c72d83c..51b9bbb 100644 --- a/src/server/middleware.ts +++ b/src/server/middleware.ts @@ -3,6 +3,30 @@ import type { RuntimeMode } from "../shared/api"; import { createApiError, jsonResponse } from "./helpers"; const MAX_PAGE_SIZE = 200; +const MAX_RECENT_LIMIT = 200; + +export function validateDashboardWindow( + windowParam: null | string, + mode: RuntimeMode, +): Response | { from: string; label: string; to: string } { + const window = windowParam ?? "24h"; + if (window !== "24h") { + return jsonResponse(createApiError("Unsupported window parameter", 400), { mode, status: 400 }); + } + + const to = new Date(); + const from = new Date(to.getTime() - 24 * 60 * 60 * 1000); + return { from: from.toISOString(), label: window, to: to.toISOString() }; +} + +export function validateMetricsBucket(bucketParam: null | string, mode: RuntimeMode): Response | { bucket: "1h" } { + const bucket = bucketParam ?? "1h"; + if (bucket !== "1h") { + return jsonResponse(createApiError("Unsupported bucket parameter", 400), { mode, status: 400 }); + } + + return { bucket }; +} export function validatePagination( pageParam: null | string, @@ -32,6 +56,19 @@ export function validatePagination( return { page, pageSize }; } +export function validateRecentLimit(limitParam: null | string, mode: RuntimeMode): Response | { recentLimit: number } { + const recentLimit = limitParam === null ? 30 : Number(limitParam); + if (!Number.isInteger(recentLimit) || recentLimit <= 0) { + return jsonResponse(createApiError("Invalid recentLimit parameter", 400), { mode, status: 400 }); + } + + if (recentLimit > MAX_RECENT_LIMIT) { + return jsonResponse(createApiError(`recentLimit must not exceed ${MAX_RECENT_LIMIT}`, 400), { mode, status: 400 }); + } + + return { recentLimit }; +} + export function validateTargetId(idStr: string, mode: RuntimeMode): Response | { id: number } { const id = Number(idStr); if (!Number.isInteger(id) || id <= 0) { @@ -49,9 +86,16 @@ export function validateTimeRange( return jsonResponse(createApiError("from and to parameters are required", 400), { mode, status: 400 }); } - if (isNaN(new Date(from).getTime()) || isNaN(new Date(to).getTime())) { + const fromDate = new Date(from); + const toDate = new Date(to); + + if (isNaN(fromDate.getTime()) || isNaN(toDate.getTime())) { return jsonResponse(createApiError("Invalid from or to parameter format", 400), { mode, status: 400 }); } - return { from, to }; + if (fromDate.getTime() > toDate.getTime()) { + return jsonResponse(createApiError("from must be earlier than to", 400), { mode, status: 400 }); + } + + return { from: fromDate.toISOString(), to: toDate.toISOString() }; } diff --git a/src/server/routes/dashboard.ts b/src/server/routes/dashboard.ts new file mode 100644 index 0000000..3d9e3e8 --- /dev/null +++ b/src/server/routes/dashboard.ts @@ -0,0 +1,100 @@ +import type { DashboardResponse, RuntimeMode } from "../../shared/api"; +import type { ProbeStore } from "../checker/store"; + +import { formatDuration, jsonResponse, mapCheckResult } from "../helpers"; +import { analyzeIncidentSequence, calculateCurrentStreak, type MetricCheckpoint } from "../metrics"; +import { validateDashboardWindow, validateRecentLimit } from "../middleware"; + +export function handleDashboard(url: URL, store: ProbeStore, mode: RuntimeMode): Response { + const windowResult = validateDashboardWindow(url.searchParams.get("window"), mode); + if (windowResult instanceof Response) return windowResult; + + const limitResult = validateRecentLimit(url.searchParams.get("recentLimit"), mode); + if (limitResult instanceof Response) return limitResult; + + const targets = store.getTargets(); + const latestChecksMap = store.getLatestChecksMap(); + const windowStats = store.getAllTargetWindowStats(windowResult.from, windowResult.to); + const recentSamplesMap = store.getAllRecentSamples(limitResult.recentLimit); + const incidentStates = groupDashboardIncidentStates( + store.getDashboardIncidentStates(windowResult.from, windowResult.to), + ); + + let up = 0; + let down = 0; + let lastCheckTime: null | string = null; + let incidents = 0; + + const responseTargets: DashboardResponse["targets"] = targets.map((target) => { + const latest = latestChecksMap.get(target.id) ?? null; + const stats = windowStats.get(target.id) ?? { availability: 0, downChecks: 0, totalChecks: 0, upChecks: 0 }; + const recentSamples = recentSamplesMap.get(target.id) ?? []; + const currentStreak = calculateCurrentStreak( + recentSamples.map((sample) => ({ + durationMs: sample.duration_ms, + matched: sample.matched === 1, + timestamp: sample.timestamp, + })), + limitResult.recentLimit, + ); + + if (latest?.matched === 1) { + up++; + } else { + down++; + } + + if (latest && (!lastCheckTime || latest.timestamp > lastCheckTime)) { + lastCheckTime = latest.timestamp; + } + + incidents += analyzeIncidentSequence( + incidentStates.get(target.id) ?? [], + windowResult.from, + windowResult.to, + ).incidentCount; + + return { + currentStreak, + group: target.grp, + id: target.id, + interval: formatDuration(target.interval_ms), + latestCheck: latest ? mapCheckResult(latest) : null, + name: target.name, + recentSamples: recentSamples.map((sample) => ({ + durationMs: sample.duration_ms, + timestamp: sample.timestamp, + up: sample.matched === 1, + })), + stats, + target: target.target, + type: target.type, + }; + }); + + const response: DashboardResponse = { + summary: { + down, + incidents, + lastCheckTime, + total: targets.length, + up, + window: windowResult, + }, + targets: responseTargets, + }; + + return jsonResponse(response, { mode }); +} + +function groupDashboardIncidentStates( + states: Array<{ matched: number; target_id: number; timestamp: string }>, +): Map { + const result = new Map(); + for (const state of states) { + const list = result.get(state.target_id) ?? []; + list.push({ durationMs: null, matched: state.matched === 1, timestamp: state.timestamp }); + result.set(state.target_id, list); + } + return result; +} diff --git a/src/server/routes/metrics.ts b/src/server/routes/metrics.ts new file mode 100644 index 0000000..91f0733 --- /dev/null +++ b/src/server/routes/metrics.ts @@ -0,0 +1,67 @@ +import type { RuntimeMode, TargetMetricsResponse } from "../../shared/api"; +import type { ProbeStore } from "../checker/store"; + +import { jsonResponse } from "../helpers"; +import { + analyzeIncidentSequence, + buildHourlyTrend, + calculateAverageDuration, + calculateCurrentStreak, + calculatePercentile, + type MetricCheckpoint, +} from "../metrics"; +import { validateMetricsBucket, validateTargetId, validateTimeRange } from "../middleware"; + +export function handleMetrics(idStr: string, url: URL, store: ProbeStore, mode: RuntimeMode): Response { + const idResult = validateTargetId(idStr, mode); + if (idResult instanceof Response) return idResult; + + const target = store.getTargetById(idResult.id); + if (!target) { + return jsonResponse({ error: "Target not found", status: 404 } as const, { mode, status: 404 }); + } + + const timeResult = validateTimeRange(url.searchParams.get("from"), url.searchParams.get("to"), mode); + if (timeResult instanceof Response) return timeResult; + + const bucketResult = validateMetricsBucket(url.searchParams.get("bucket"), mode); + if (bucketResult instanceof Response) return bucketResult; + + const checkpoints = store + .getTargetCheckpoints(idResult.id, timeResult.from, timeResult.to) + .map((checkpoint): MetricCheckpoint => { + return { + durationMs: checkpoint.duration_ms, + matched: checkpoint.matched === 1, + timestamp: checkpoint.timestamp, + }; + }); + const durations = store.getTargetDurations(idResult.id, timeResult.from, timeResult.to); + const stats = store.getTargetWindowStats(idResult.id, timeResult.from, timeResult.to); + const incidentAnalysis = analyzeIncidentSequence(checkpoints, timeResult.from, timeResult.to); + + const response: TargetMetricsResponse = { + stats: { + availability: stats.availability, + avgDurationMs: calculateAverageDuration(durations), + currentStreak: calculateCurrentStreak(checkpoints), + downChecks: stats.downChecks, + incidentCount: incidentAnalysis.incidentCount, + longestOutage: incidentAnalysis.longestOutage, + mttr: incidentAnalysis.mttr, + p95DurationMs: calculatePercentile(durations, 95), + p99DurationMs: calculatePercentile(durations, 99), + totalChecks: stats.totalChecks, + upChecks: stats.upChecks, + }, + targetId: idResult.id, + trend: buildHourlyTrend(checkpoints), + window: { + bucket: bucketResult.bucket, + from: timeResult.from, + to: timeResult.to, + }, + }; + + return jsonResponse(response, { mode }); +} diff --git a/src/server/routes/summary.ts b/src/server/routes/summary.ts deleted file mode 100644 index 5d7d277..0000000 --- a/src/server/routes/summary.ts +++ /dev/null @@ -1,16 +0,0 @@ -import type { RuntimeMode, SummaryResponse } from "../../shared/api"; -import type { ProbeStore } from "../checker/store"; - -import { jsonResponse } from "../helpers"; - -export function handleSummary(store: ProbeStore, mode: RuntimeMode): Response { - const summary = store.getSummary(); - const response: SummaryResponse = { - down: summary.down, - lastCheckTime: summary.lastCheckTime, - total: summary.total, - up: summary.up, - }; - - return jsonResponse(response, { mode }); -} diff --git a/src/server/routes/targets.ts b/src/server/routes/targets.ts deleted file mode 100644 index 0872606..0000000 --- a/src/server/routes/targets.ts +++ /dev/null @@ -1,38 +0,0 @@ -import type { RuntimeMode, TargetStatus } from "../../shared/api"; -import type { ProbeStore } from "../checker/store"; - -import { formatDuration, jsonResponse, mapCheckResult } from "../helpers"; - -export function handleTargets(store: ProbeStore, mode: RuntimeMode): Response { - const targets = store.getTargets(); - const latestChecksMap = store.getLatestChecksMap(); - const allStats = store.getAllTargetStats(); - const allRecentSamples = store.getAllRecentSamples(30); - - const result: TargetStatus[] = targets.map((target) => { - const latest = latestChecksMap.get(target.id) ?? null; - const stats = allStats.get(target.id) ?? { availability: 0, totalChecks: 0 }; - const recentSamples = allRecentSamples.get(target.id) ?? []; - - return { - group: target.grp, - id: target.id, - interval: formatDuration(target.interval_ms), - latestCheck: latest ? mapCheckResult(latest) : null, - name: target.name, - recentSamples: recentSamples.map((s) => ({ - durationMs: s.duration_ms, - timestamp: s.timestamp, - up: s.matched === 1, - })), - stats: { - availability: stats.availability, - totalChecks: stats.totalChecks, - }, - target: target.target, - type: target.type, - }; - }); - - return jsonResponse(result, { mode }); -} diff --git a/src/server/routes/trend.ts b/src/server/routes/trend.ts deleted file mode 100644 index 2724e58..0000000 --- a/src/server/routes/trend.ts +++ /dev/null @@ -1,27 +0,0 @@ -import type { RuntimeMode, TrendPoint } from "../../shared/api"; -import type { ProbeStore } from "../checker/store"; - -import { jsonResponse } from "../helpers"; -import { validateTargetId, validateTimeRange } from "../middleware"; - -export function handleTrend(idStr: string, url: URL, store: ProbeStore, mode: RuntimeMode): Response { - const idResult = validateTargetId(idStr, mode); - if (idResult instanceof Response) return idResult; - - const target = store.getTargetById(idResult.id); - if (!target) { - return jsonResponse({ error: "Target not found", status: 404 } as const, { mode, status: 404 }); - } - - const timeResult = validateTimeRange(url.searchParams.get("from"), url.searchParams.get("to"), mode); - if (timeResult instanceof Response) return timeResult; - - const trend: TrendPoint[] = store.getTrend(idResult.id, timeResult.from, timeResult.to).map((row) => ({ - availability: Math.round(row.availability * 100) / 100, - avgDurationMs: row.avgDurationMs, - hour: row.hour, - totalChecks: row.totalChecks, - })); - - return jsonResponse(trend, { mode }); -} diff --git a/src/server/server.ts b/src/server/server.ts index 125937a..4965806 100644 --- a/src/server/server.ts +++ b/src/server/server.ts @@ -4,12 +4,11 @@ import type { RuntimeConfig } from "./config"; import homepage from "../web/index.html"; import { createApiError, jsonResponse } from "./helpers"; +import { handleDashboard } from "./routes/dashboard"; import { handleHealth } from "./routes/health"; import { handleHistory } from "./routes/history"; import { handleMeta } from "./routes/meta"; -import { handleSummary } from "./routes/summary"; -import { handleTargets } from "./routes/targets"; -import { handleTrend } from "./routes/trend"; +import { handleMetrics } from "./routes/metrics"; export interface StartServerOptions { config: RuntimeConfig; @@ -30,20 +29,17 @@ export function startServer(options: StartServerOptions) { routes: { "/*": homepage, "/api/*": () => jsonResponse(createApiError("API route not found", 404), { mode, status: 404 }), + "/api/dashboard": { + GET: (req) => handleDashboard(new URL(req.url), store, mode), + }, "/api/meta": { GET: () => handleMeta(mode), }, - "/api/summary": { - GET: () => handleSummary(store, mode), - }, - "/api/targets": { - GET: () => handleTargets(store, mode), - }, "/api/targets/:id/history": { GET: (req) => handleHistory(req.params.id, new URL(req.url), store, mode), }, - "/api/targets/:id/trend": { - GET: (req) => handleTrend(req.params.id, new URL(req.url), store, mode), + "/api/targets/:id/metrics": { + GET: (req) => handleMetrics(req.params.id, new URL(req.url), store, mode), }, "/health": { GET: () => handleHealth(mode), diff --git a/src/shared/api.ts b/src/shared/api.ts index b6d9a64..190eed6 100644 --- a/src/shared/api.ts +++ b/src/shared/api.ts @@ -20,6 +20,28 @@ export interface CheckResult { timestamp: string; } +export interface CurrentStreak { + capped?: boolean; + count: number; + up: boolean; +} + +export interface DashboardResponse { + summary: { + down: number; + incidents: number; + lastCheckTime: null | string; + total: number; + up: number; + window: { + from: string; + label: string; + to: string; + }; + }; + targets: TargetStatus[]; +} + export interface HealthResponse { ok: true; service: "dial-server"; @@ -45,19 +67,38 @@ export interface RecentSample { export type RuntimeMode = "development" | "production" | "test"; -export interface SummaryResponse { - down: number; - lastCheckTime: null | string; - total: number; - up: number; +export interface TargetMetricsResponse { + stats: { + availability: number; + avgDurationMs: null | number; + currentStreak: CurrentStreak | null; + downChecks: number; + incidentCount: number; + longestOutage: null | number; + mttr: null | number; + p95DurationMs: null | number; + p99DurationMs: null | number; + totalChecks: number; + upChecks: number; + }; + targetId: number; + trend: TrendPoint[]; + window: { + bucket: "1h"; + from: string; + to: string; + }; } export interface TargetStats { availability: number; + downChecks: number; totalChecks: number; + upChecks: number; } export interface TargetStatus { + currentStreak: CurrentStreak | null; group: string; id: number; interval: string; @@ -72,6 +113,10 @@ export interface TargetStatus { export interface TrendPoint { availability: number; avgDurationMs: null | number; - hour: string; + bucketStart: string; + downChecks: number; + maxDurationMs: null | number; + minDurationMs: null | number; totalChecks: number; + upChecks: number; } diff --git a/src/web/app.tsx b/src/web/app.tsx index 7fe42b3..97f24dd 100644 --- a/src/web/app.tsx +++ b/src/web/app.tsx @@ -3,28 +3,25 @@ import { Alert, Loading, Typography } from "tdesign-react"; import { SummaryCards } from "./components/SummaryCards"; import { TargetBoard } from "./components/TargetBoard"; import { TargetDetailDrawer } from "./components/TargetDetailDrawer"; -import { useSummary, useTargets } from "./hooks/use-queries"; +import { useDashboard } from "./hooks/use-queries"; import { useTargetDetail } from "./hooks/use-target-detail"; export function App() { - const { data: summary, error: summaryError, isLoading: summaryLoading } = useSummary(); - const { data: targets, error: targetsError, isLoading: targetsLoading } = useTargets(); + const { data: dashboard, error: dashboardError, isLoading: dashboardLoading } = useDashboard(); const { closeDrawer, handlePageChange, handleTimeChange, historyData, historyLoading, + metricsData, + metricsLoading, openDrawer, selectedTarget, timeFrom, timeTo, - trendData, - trendLoading, } = useTargetDetail(); - const error = summaryError ?? targetsError; - return (
@@ -32,14 +29,14 @@ export function App() { 统一拨测平台
- {error && } + {dashboardError && } - {summaryLoading && targetsLoading ? ( + {dashboardLoading ? ( ) : ( <> - - + + )} @@ -47,14 +44,14 @@ export function App() { historyData={historyData} historyLoading={historyLoading} key={selectedTarget?.id} + metricsData={metricsData} + metricsLoading={metricsLoading} onClose={closeDrawer} onPageChange={handlePageChange} onTimeChange={handleTimeChange} target={selectedTarget} timeFrom={timeFrom} timeTo={timeTo} - trendData={trendData} - trendLoading={trendLoading} />
); diff --git a/src/web/components/OverviewTab.tsx b/src/web/components/OverviewTab.tsx index 9443968..31744c9 100644 --- a/src/web/components/OverviewTab.tsx +++ b/src/web/components/OverviewTab.tsx @@ -1,44 +1,88 @@ -import { useMemo } from "react"; import { Col, Descriptions, Divider, Row, Skeleton, Space, Statistic } from "tdesign-react"; -import type { TargetStatus, TrendPoint } from "../../shared/api"; +import type { TargetMetricsResponse, TargetStatus } from "../../shared/api"; -import { computeTrendStats } from "../utils/stats"; +import { formatDurationUnit } from "../utils/time"; import { StatusDonut } from "./StatusDonut"; import { TrendChart } from "./TrendChart"; interface OverviewTabProps { + metricsData: null | TargetMetricsResponse; + metricsLoading: boolean; target: TargetStatus; - trendData: TrendPoint[]; - trendLoading: boolean; } -export function OverviewTab({ target, trendData, trendLoading }: OverviewTabProps) { - const { downChecks, totalChecks, upChecks } = useMemo(() => computeTrendStats(trendData), [trendData]); +export function OverviewTab({ metricsData, metricsLoading, target }: OverviewTabProps) { + const stats = metricsData?.stats ?? null; + const mttr = formatDurationUnit(stats?.mttr ?? null); + const longestOutage = formatDurationUnit(stats?.longestOutage ?? null); + const currentUpStreak = stats?.currentStreak?.up ? stats.currentStreak.count : 0; return ( 统计 - - - - - - - - - - - - - - + {metricsLoading ? ( + + ) : stats ? ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ) : ( +
暂无指标数据
+ )} 趋势 - {trendLoading ? : } + {metricsLoading ? ( + + ) : metricsData ? ( + + ) : ( +
暂无趋势数据
+ )} 状态分布 - + {metricsLoading ? ( + + ) : stats ? ( + + ) : ( +
暂无状态数据
+ )} 基本信息 -
{availability}%
+
{total > 0 ? `${availability}%` : "-"}
); } diff --git a/src/web/components/SummaryCards.tsx b/src/web/components/SummaryCards.tsx index f29dc06..43fa0f3 100644 --- a/src/web/components/SummaryCards.tsx +++ b/src/web/components/SummaryCards.tsx @@ -1,29 +1,49 @@ -import { Card, Col, Row, Statistic } from "tdesign-react"; +import { useEffect, useState } from "react"; +import { Card, Col, Row, Statistic, Typography } from "tdesign-react"; -import type { SummaryResponse } from "../../shared/api"; +import type { DashboardResponse } from "../../shared/api"; + +import { formatRelativeTime, isOlderThan } from "../utils/time"; interface SummaryCardsProps { - summary: null | SummaryResponse; + summary: DashboardResponse["summary"] | null; } export function SummaryCards({ summary }: SummaryCardsProps) { + const [now, setNow] = useState(() => new Date()); + + useEffect(() => { + const timer = window.setInterval(() => setNow(new Date()), 1000); + return () => window.clearInterval(timer); + }, []); + if (!summary) return null; const cards = [ { color: "blue" as const, label: "全部目标", value: summary.total }, { color: "green" as const, label: "正常", value: summary.up }, { color: "red" as const, label: "异常", value: summary.down }, + { color: "orange" as const, label: `${summary.window.label} 异常事件数`, value: summary.incidents }, ]; + const freshnessWarning = isOlderThan(summary.lastCheckTime, 60000, now); return ( - - {cards.map((card) => ( - - - - - - ))} - +
+ + {cards.map((card) => ( + + + + + + ))} + + + {summary.lastCheckTime ? `最后更新: ${formatRelativeTime(summary.lastCheckTime, now)}` : "尚无检查数据"} + +
); } diff --git a/src/web/components/TargetDetailDrawer.tsx b/src/web/components/TargetDetailDrawer.tsx index 091f473..09ad9ad 100644 --- a/src/web/components/TargetDetailDrawer.tsx +++ b/src/web/components/TargetDetailDrawer.tsx @@ -3,7 +3,7 @@ import type { TabValue } from "tdesign-react"; import { useCallback, useState } from "react"; import { DateRangePicker, Drawer, RadioGroup, Space, Tabs, Tag, Typography } from "tdesign-react"; -import type { HistoryResponse, TargetStatus, TrendPoint } from "../../shared/api"; +import type { HistoryResponse, TargetMetricsResponse, TargetStatus } from "../../shared/api"; import { subtractHours } from "../utils/time"; import { HistoryTab } from "./HistoryTab"; @@ -13,14 +13,14 @@ import { StatusDot } from "./StatusDot"; interface TargetDetailDrawerProps { historyData: HistoryResponse; historyLoading: boolean; + metricsData: null | TargetMetricsResponse; + metricsLoading: boolean; onClose: () => void; onPageChange: (page: number) => void; onTimeChange: (from: string, to: string) => void; target: null | TargetStatus; timeFrom: string; timeTo: string; - trendData: TrendPoint[]; - trendLoading: boolean; } const TIME_SHORTCUTS = [ @@ -33,14 +33,14 @@ const TIME_SHORTCUTS = [ export function TargetDetailDrawer({ historyData, historyLoading, + metricsData, + metricsLoading, onClose, onPageChange, onTimeChange, target, timeFrom, timeTo, - trendData, - trendLoading, }: TargetDetailDrawerProps) { const [activeShortcut, setActiveShortcut] = useState("24h"); const [activeTab, setActiveTab] = useState("overview"); @@ -109,7 +109,7 @@ export function TargetDetailDrawer({ /> setActiveTab(val)} value={activeTab}> - + diff --git a/src/web/components/TrendChart.tsx b/src/web/components/TrendChart.tsx index ef3eff0..5bf43f4 100644 --- a/src/web/components/TrendChart.tsx +++ b/src/web/components/TrendChart.tsx @@ -1,7 +1,13 @@ -import { CartesianGrid, Line, LineChart, ResponsiveContainer, Tooltip, XAxis, YAxis } from "recharts"; +import { Area, CartesianGrid, Line, LineChart, ResponsiveContainer, Tooltip, XAxis, YAxis } from "recharts"; import type { TrendPoint } from "../../shared/api"; +interface IncidentDotProps { + cx?: number | string; + cy?: number | string; + payload?: TrendPoint; +} + interface TrendChartProps { data: TrendPoint[]; } @@ -13,7 +19,9 @@ export function TrendChart({ data }: TrendChartProps) { const chartData = data.map((point) => ({ ...point, - hour: point.hour.slice(11, 16), + durationRange: + point.minDurationMs !== null && point.maxDurationMs !== null ? [point.minDurationMs, point.maxDurationMs] : null, + label: formatBucketLabel(point.bucketStart), })); return ( @@ -21,50 +29,64 @@ export function TrendChart({ data }: TrendChartProps) { - + - { - const num = Number(value); const nameStr = String(name); + if (nameStr === "durationRange" && Array.isArray(value)) { + return [`${Math.round(Number(value[0]))}ms - ${Math.round(Number(value[1]))}ms`, "延迟范围"]; + } + const num = Number(value); if (nameStr === "avgDurationMs") return [`${Math.round(num)}ms`, "平均耗时"]; - if (nameStr === "availability") return [`${num.toFixed(1)}%`, "可用率"]; return [String(value), nameStr]; }} /> + - ); } + +function formatBucketLabel(bucketStart: string): string { + return new Date(bucketStart).toLocaleTimeString("zh-CN", { hour: "2-digit", hour12: false, minute: "2-digit" }); +} + +function renderIncidentDot(props: IncidentDotProps) { + const { cx, cy, payload } = props; + if (!payload || payload.availability >= 100 || payload.avgDurationMs === null) return <>; + + return ( + + ); +} diff --git a/src/web/constants/target-table-columns.tsx b/src/web/constants/target-table-columns.tsx index 62a5fcb..24bccc2 100644 --- a/src/web/constants/target-table-columns.tsx +++ b/src/web/constants/target-table-columns.tsx @@ -57,7 +57,7 @@ export function createTargetTableColumns(checkerTypes: string[]): Array) => { + const streak = row.currentStreak; + if (!streak) return "-"; + return ( + + {streak.up ? "▲" : "▼"} {streak.count} + {streak.capped ? "+" : "次"} + + ); + }, + colKey: "currentStreak", + title: "连续", + width: 100, + }, { align: "right", cell: ({ row }: PrimaryTableCellParams) => { diff --git a/src/web/hooks/use-queries.ts b/src/web/hooks/use-queries.ts index 75a039c..0bfb99d 100644 --- a/src/web/hooks/use-queries.ts +++ b/src/web/hooks/use-queries.ts @@ -1,11 +1,12 @@ import { useQuery } from "@tanstack/react-query"; -import type { MetaResponse, SummaryResponse, TargetStatus } from "../../shared/api"; +import type { DashboardResponse, MetaResponse, TargetMetricsResponse } from "../../shared/api"; const queryKeys = { + dashboard: () => ["dashboard", "24h", 30] as const, meta: () => ["meta"] as const, - summary: () => ["summary"] as const, - targets: () => ["targets"] as const, + metrics: (targetId: number, from: string, to: string, bucket: "1h") => + ["metrics", targetId, from, to, bucket] as const, }; export async function fetchJson(url: string): Promise { @@ -14,6 +15,15 @@ export async function fetchJson(url: string): Promise { return response.json() as Promise; } +export function useDashboard() { + return useQuery({ + queryFn: () => fetchJson("/api/dashboard?window=24h&recentLimit=30"), + queryKey: queryKeys.dashboard(), + refetchInterval: 8000, + refetchIntervalInBackground: false, + }); +} + export function useMeta() { return useQuery({ queryFn: () => fetchJson("/api/meta"), @@ -22,20 +32,15 @@ export function useMeta() { }); } -export function useSummary() { +export function useTargetMetrics(targetId: null | number, from: string, to: string, bucket: "1h") { return useQuery({ - queryFn: () => fetchJson("/api/summary"), - queryKey: queryKeys.summary(), - refetchInterval: 8000, - refetchIntervalInBackground: false, - }); -} - -export function useTargets() { - return useQuery({ - queryFn: () => fetchJson("/api/targets"), - queryKey: queryKeys.targets(), - refetchInterval: 8000, - refetchIntervalInBackground: false, + enabled: targetId !== null && !!from && !!to, + queryFn: () => { + if (targetId === null) throw new Error("未选择目标"); + return fetchJson( + `/api/targets/${targetId}/metrics?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}&bucket=${bucket}`, + ); + }, + queryKey: targetId !== null && from && to ? queryKeys.metrics(targetId, from, to, bucket) : ["metrics", "disabled"], }); } diff --git a/src/web/hooks/use-target-detail.ts b/src/web/hooks/use-target-detail.ts index 65f01e4..4071692 100644 --- a/src/web/hooks/use-target-detail.ts +++ b/src/web/hooks/use-target-detail.ts @@ -1,14 +1,13 @@ import { useQuery, useQueryClient } from "@tanstack/react-query"; import { useCallback, useState } from "react"; -import type { HistoryResponse, TargetStatus, TrendPoint } from "../../shared/api"; +import type { HistoryResponse, TargetStatus } from "../../shared/api"; import { subtractHours } from "../utils/time"; -import { fetchJson, useTargets } from "./use-queries"; +import { fetchJson, useDashboard, useTargetMetrics } from "./use-queries"; const detailQueryKeys = { history: (targetId: number, from: string, to: string, page: number) => ["history", targetId, from, to, page] as const, - trend: (targetId: number, from: string, to: string) => ["trend", targetId, from, to] as const, }; export function useTargetDetail() { @@ -18,28 +17,22 @@ export function useTargetDetail() { const [timeTo, setTimeTo] = useState(""); const [historyPage, setHistoryPage] = useState(1); - const { data: targetsData } = useTargets(); + const { data: dashboardData } = useDashboard(); const selectedTarget = - selectedTargetId !== null ? (targetsData?.find((target) => target.id === selectedTargetId) ?? null) : null; + selectedTargetId !== null + ? (dashboardData?.targets.find((target) => target.id === selectedTargetId) ?? null) + : null; - const trend = useQuery({ - enabled: selectedTargetId !== null && !!timeFrom && !!timeTo, - queryFn: () => - fetchJson( - `/api/targets/${selectedTargetId}/trend?from=${encodeURIComponent(timeFrom)}&to=${encodeURIComponent(timeTo)}`, - ), - queryKey: - selectedTargetId !== null && timeFrom && timeTo - ? detailQueryKeys.trend(selectedTargetId, timeFrom, timeTo) - : ["trend", "disabled"], - }); + const metrics = useTargetMetrics(selectedTargetId, timeFrom, timeTo, "1h"); const history = useQuery({ enabled: selectedTargetId !== null && !!timeFrom && !!timeTo, - queryFn: () => - fetchJson( + queryFn: () => { + if (selectedTargetId === null) throw new Error("未选择目标"); + return fetchJson( `/api/targets/${selectedTargetId}/history?from=${encodeURIComponent(timeFrom)}&to=${encodeURIComponent(timeTo)}&page=${historyPage}&pageSize=20`, - ), + ); + }, queryKey: selectedTargetId !== null && timeFrom && timeTo ? detailQueryKeys.history(selectedTargetId, timeFrom, timeTo, historyPage) @@ -57,7 +50,7 @@ export function useTargetDetail() { const closeDrawer = useCallback(() => { setSelectedTargetId(null); - queryClient.removeQueries({ queryKey: ["trend"] }); + queryClient.removeQueries({ queryKey: ["metrics"] }); queryClient.removeQueries({ queryKey: ["history"] }); }, [queryClient]); @@ -77,11 +70,11 @@ export function useTargetDetail() { handleTimeChange, historyData: history.data ?? { items: [], page: 1, pageSize: 20, total: 0 }, historyLoading: history.isLoading, + metricsData: metrics.data ?? null, + metricsLoading: metrics.isLoading, openDrawer, selectedTarget, timeFrom, timeTo, - trendData: trend.data ?? [], - trendLoading: trend.isLoading, }; } diff --git a/src/web/styles.css b/src/web/styles.css index db26141..7ff1703 100644 --- a/src/web/styles.css +++ b/src/web/styles.css @@ -157,6 +157,15 @@ margin-bottom: var(--td-comp-margin-xl); } +.summary-freshness { + display: block; + margin-top: var(--td-comp-margin-s); +} + +.summary-freshness--warning { + color: var(--td-warning-color); +} + .error-boundary-fallback { padding-top: 20vh; width: 100%; diff --git a/src/web/utils/stats.ts b/src/web/utils/stats.ts deleted file mode 100644 index 8bc9fde..0000000 --- a/src/web/utils/stats.ts +++ /dev/null @@ -1,23 +0,0 @@ -import type { TrendPoint } from "../../shared/api"; - -export interface TrendStats { - downChecks: number; - totalChecks: number; - upChecks: number; -} - -export function computeTrendStats(points: TrendPoint[]): TrendStats { - let totalChecks = 0; - let upChecks = 0; - - for (const point of points) { - totalChecks += point.totalChecks; - upChecks += Math.round((point.availability / 100) * point.totalChecks); - } - - return { - downChecks: totalChecks - upChecks, - totalChecks, - upChecks, - }; -} diff --git a/src/web/utils/time.ts b/src/web/utils/time.ts index 7edd903..6150e65 100644 --- a/src/web/utils/time.ts +++ b/src/web/utils/time.ts @@ -1,5 +1,41 @@ +export function formatDurationUnit(ms: null | number): { suffix: string; value: number } { + if (ms === null) return { suffix: "", value: 0 }; + if (ms < 60000) return { suffix: "秒", value: roundToOne(ms / 1000) }; + if (ms < 3600000) return { suffix: "分钟", value: roundToOne(ms / 60000) }; + return { suffix: "小时", value: roundToOne(ms / 3600000) }; +} + +export function formatRelativeTime(timestamp: null | string, now = new Date()): string { + if (!timestamp) return "尚无检查数据"; + + const time = new Date(timestamp).getTime(); + if (Number.isNaN(time)) return "尚无检查数据"; + + const diffSeconds = Math.max(0, Math.floor((now.getTime() - time) / 1000)); + if (diffSeconds < 60) return `${diffSeconds}秒前`; + + const diffMinutes = Math.floor(diffSeconds / 60); + if (diffMinutes < 60) return `${diffMinutes}分钟前`; + + const diffHours = Math.floor(diffMinutes / 60); + if (diffHours < 24) return `${diffHours}小时前`; + + return `${Math.floor(diffHours / 24)}天前`; +} + +export function isOlderThan(timestamp: null | string, ageMs: number, now = new Date()): boolean { + if (!timestamp) return false; + const time = new Date(timestamp).getTime(); + if (Number.isNaN(time)) return false; + return now.getTime() - time > ageMs; +} + export function subtractHours(date: Date, hours: number): Date { const result = new Date(date); result.setTime(result.getTime() - hours * 60 * 60 * 1000); return result; } + +function roundToOne(value: number): number { + return Math.round(value * 10) / 10; +} diff --git a/tests/server/app.test.ts b/tests/server/app.test.ts index 0125b0c..f25d21f 100644 --- a/tests/server/app.test.ts +++ b/tests/server/app.test.ts @@ -4,11 +4,11 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import type { + DashboardResponse, HealthResponse, HistoryResponse, MetaResponse, - SummaryResponse, - TargetStatus, + TargetMetricsResponse, } from "../../src/shared/api"; import { checkerRegistry } from "../../src/server/checker/runner"; @@ -73,7 +73,7 @@ describe("API 路由", () => { const targets = store.getTargets(); store.insertCheckResult({ - durationMs: 150, + durationMs: 100, failure: null, matched: true, statusDetail: "200 OK", @@ -93,7 +93,78 @@ describe("API 路由", () => { matched: false, statusDetail: null, targetId: targets[0]!.id, - timestamp: "2025-01-01T00:00:30.000Z", + timestamp: "2025-01-01T00:10:00.000Z", + }); + store.insertCheckResult({ + durationMs: null, + failure: { + actual: 500, + expected: 200, + kind: "error", + message: "状态码不匹配", + path: "$.status", + phase: "status", + }, + matched: false, + statusDetail: null, + targetId: targets[0]!.id, + timestamp: "2025-01-01T00:20:00.000Z", + }); + store.insertCheckResult({ + durationMs: 200, + failure: null, + matched: true, + statusDetail: "200 OK", + targetId: targets[0]!.id, + timestamp: "2025-01-01T00:40:00.000Z", + }); + store.insertCheckResult({ + durationMs: 400, + failure: null, + matched: true, + statusDetail: "200 OK", + targetId: targets[0]!.id, + timestamp: "2025-01-01T01:10:00.000Z", + }); + + const now = Date.now(); + store.insertCheckResult({ + durationMs: 120, + failure: null, + matched: true, + statusDetail: "200 OK", + targetId: targets[0]!.id, + timestamp: new Date(now - 90 * 60 * 1000).toISOString(), + }); + store.insertCheckResult({ + durationMs: null, + failure: { + actual: 500, + expected: 200, + kind: "error", + message: "状态码不匹配", + path: "$.status", + phase: "status", + }, + matched: false, + statusDetail: null, + targetId: targets[0]!.id, + timestamp: new Date(now - 60 * 60 * 1000).toISOString(), + }); + store.insertCheckResult({ + durationMs: null, + failure: { + actual: 500, + expected: 200, + kind: "error", + message: "状态码不匹配", + path: "$.status", + phase: "status", + }, + matched: false, + statusDetail: null, + targetId: targets[0]!.id, + timestamp: new Date(now - 30 * 60 * 1000).toISOString(), }); server = startServer({ @@ -119,40 +190,44 @@ describe("API 路由", () => { expect(body.service).toBe("dial-server"); }); - test("/api/summary 返回总览统计", async () => { - const response = await fetch(`${baseUrl}/api/summary`); - const body = (await response.json()) as SummaryResponse; - expect(response.status).toBe(200); - expect(body.total).toBe(2); - expect(body.up).toBeGreaterThanOrEqual(0); - expect(body.down).toBeGreaterThanOrEqual(0); - expect(body.up + body.down).toBe(2); - expect(body.lastCheckTime).not.toBeNull(); - }); - - test("/api/targets 返回目标列表", async () => { - const response = await fetch(`${baseUrl}/api/targets`); - const body = (await response.json()) as TargetStatus[]; + test("/api/dashboard 返回总览和目标列表", async () => { + const response = await fetch(`${baseUrl}/api/dashboard?window=24h&recentLimit=2`); + const body = (await response.json()) as DashboardResponse; expect(response.status).toBe(200); - expect(body).toHaveLength(2); + expect(body.summary.total).toBe(2); + expect(body.summary.up).toBe(0); + expect(body.summary.down).toBe(2); + expect(body.summary.incidents).toBe(1); + expect(body.summary.lastCheckTime).not.toBeNull(); + expect(body.summary.window.label).toBe("24h"); + expect(body.targets).toHaveLength(2); - const tA = body.find((t) => t.name === "test-a")!; + const tA = body.targets.find((t) => t.name === "test-a")!; expect(tA.type).toBe("http"); expect(tA.target).toBe("http://a.com"); expect(tA.group).toBe("default"); expect(tA.latestCheck).not.toBeNull(); expect(tA.latestCheck!.matched).toBe(false); expect(tA.latestCheck!.failure).not.toBeNull(); - expect(tA.recentSamples).toBeDefined(); - expect(Array.isArray(tA.recentSamples)).toBe(true); - expect(tA.stats.totalChecks).toBeDefined(); - expect(tA.stats.availability).toBeDefined(); + expect(tA.recentSamples).toHaveLength(2); + expect(tA.stats).toMatchObject({ availability: 33.33, downChecks: 2, totalChecks: 3, upChecks: 1 }); + expect(tA.currentStreak).toEqual({ capped: true, count: 2, up: false }); - const tB = body.find((t) => t.name === "test-b")!; + const tB = body.targets.find((t) => t.name === "test-b")!; expect(tB.type).toBe("cmd"); expect(tB.target).toBe("exec echo hello"); expect(tB.latestCheck).toBeNull(); + expect(tB.stats).toMatchObject({ availability: 0, downChecks: 0, totalChecks: 0, upChecks: 0 }); + expect(tB.currentStreak).toBeNull(); + }); + + test("dashboard 无效参数返回 400", async () => { + const invalidWindow = await fetch(`${baseUrl}/api/dashboard?window=7d`); + const invalidLimit = await fetch(`${baseUrl}/api/dashboard?recentLimit=0`); + + expect(invalidWindow.status).toBe(400); + expect(invalidLimit.status).toBe(400); }); test("/api/meta 返回 checker 类型列表", async () => { @@ -166,36 +241,36 @@ describe("API 路由", () => { }); test("不支持的 method 在有 API 通配符时返回 404", async () => { - const response = await fetch(`${baseUrl}/api/summary`, { method: "POST" }); + const response = await fetch(`${baseUrl}/api/dashboard`, { method: "POST" }); expect(response.status).toBe(404); }); test("/api/targets/:id/history 返回历史记录", async () => { const targets = store.getTargets(); const from = "2024-01-01T00:00:00.000Z"; - const to = "2026-12-31T23:59:59.999Z"; + const to = "2025-01-02T00:00:00.000Z"; const response = await fetch(`${baseUrl}/api/targets/${targets[0]!.id}/history?from=${from}&to=${to}`); const body = (await response.json()) as HistoryResponse; expect(response.status).toBe(200); - expect(body.items).toHaveLength(2); - expect(body.total).toBe(2); + expect(body.items).toHaveLength(5); + expect(body.total).toBe(5); expect(body.page).toBe(1); expect(body.pageSize).toBe(20); - expect(body.items[0]!.failure).not.toBeNull(); - expect(body.items[0]!.failure!.kind).toBe("error"); + const failedItem = body.items.find((item) => item.failure); + expect(failedItem?.failure?.kind).toBe("error"); }); test("/api/targets/:id/history 支持 page 参数", async () => { const targets = store.getTargets(); const from = "2024-01-01T00:00:00.000Z"; - const to = "2026-12-31T23:59:59.999Z"; + const to = "2025-01-02T00:00:00.000Z"; const response = await fetch(`${baseUrl}/api/targets/${targets[0]!.id}/history?from=${from}&to=${to}&pageSize=1`); const body = (await response.json()) as HistoryResponse; expect(response.status).toBe(200); expect(body.items).toHaveLength(1); - expect(body.total).toBe(2); + expect(body.total).toBe(5); }); test("history pageSize 超过上限返回 400", async () => { @@ -209,15 +284,64 @@ describe("API 路由", () => { expect(body["error"]).toBe("pageSize must not exceed 200"); }); - test("/api/targets/:id/trend 返回趋势数据", async () => { + test("/api/targets/:id/metrics 返回单目标统计和趋势", async () => { const targets = store.getTargets(); - const from = "2024-01-01T00:00:00.000Z"; - const to = "2026-12-31T23:59:59.999Z"; - const response = await fetch(`${baseUrl}/api/targets/${targets[0]!.id}/trend?from=${from}&to=${to}`); - const body = (await response.json()) as unknown[]; + const from = "2025-01-01T00:00:00.000Z"; + const to = "2025-01-01T01:59:59.999Z"; + const response = await fetch(`${baseUrl}/api/targets/${targets[0]!.id}/metrics?from=${from}&to=${to}&bucket=1h`); + const body = (await response.json()) as TargetMetricsResponse; expect(response.status).toBe(200); - expect(Array.isArray(body)).toBe(true); + expect(body.targetId).toBe(targets[0]!.id); + expect(body.window.bucket).toBe("1h"); + expect(body.stats).toMatchObject({ + availability: 60, + avgDurationMs: 233.33, + downChecks: 2, + incidentCount: 1, + longestOutage: 30 * 60 * 1000, + mttr: 30 * 60 * 1000, + p95DurationMs: 400, + p99DurationMs: 400, + totalChecks: 5, + upChecks: 3, + }); + expect(body.stats.currentStreak).toEqual({ count: 2, up: true }); + expect(body.trend[0]).toMatchObject({ + availability: 50, + avgDurationMs: 150, + bucketStart: "2025-01-01T00:00:00.000Z", + downChecks: 2, + maxDurationMs: 200, + minDurationMs: 100, + totalChecks: 4, + upChecks: 2, + }); + }); + + test("/api/targets/:id/metrics 无数据返回空指标", async () => { + const targets = store.getTargets(); + const target = targets.find((item) => item.name === "test-b")!; + const response = await fetch( + `${baseUrl}/api/targets/${target.id}/metrics?from=2025-01-01T00:00:00.000Z&to=2025-01-01T01:00:00.000Z`, + ); + const body = (await response.json()) as TargetMetricsResponse; + + expect(response.status).toBe(200); + expect(body.stats).toEqual({ + availability: 0, + avgDurationMs: null, + currentStreak: null, + downChecks: 0, + incidentCount: 0, + longestOutage: null, + mttr: null, + p95DurationMs: null, + p99DurationMs: null, + totalChecks: 0, + upChecks: 0, + }); + expect(body.trend).toEqual([]); }); test("查询不存在的目标返回 404", async () => { @@ -239,18 +363,18 @@ describe("API 路由", () => { expect(body["error"]).toContain("from and to"); }); - test("trend 缺少 from/to 参数返回 400", async () => { + test("metrics 缺少 from/to 参数返回 400", async () => { const targets = store.getTargets(); - const response = await fetch(`${baseUrl}/api/targets/${targets[0]!.id}/trend`); + const response = await fetch(`${baseUrl}/api/targets/${targets[0]!.id}/metrics`); const body = (await response.json()) as Record; expect(response.status).toBe(400); expect(body["error"]).toContain("from and to"); }); - test("trend 无效 targetId 返回 400", async () => { + test("metrics 无效 targetId 返回 400", async () => { const response = await fetch( - `${baseUrl}/api/targets/invalid/trend?from=2024-01-01T00:00:00Z&to=2024-01-02T00:00:00Z`, + `${baseUrl}/api/targets/invalid/metrics?from=2024-01-01T00:00:00Z&to=2024-01-02T00:00:00Z`, ); const body = (await response.json()) as Record; @@ -258,6 +382,19 @@ describe("API 路由", () => { expect(body["error"]).toBe("Invalid target ID"); }); + test("metrics 无效 bucket 和不存在目标返回错误", async () => { + const targets = store.getTargets(); + const invalidBucket = await fetch( + `${baseUrl}/api/targets/${targets[0]!.id}/metrics?from=2025-01-01T00:00:00.000Z&to=2025-01-01T01:00:00.000Z&bucket=5m`, + ); + const missingTarget = await fetch( + `${baseUrl}/api/targets/99999/metrics?from=2025-01-01T00:00:00.000Z&to=2025-01-01T01:00:00.000Z`, + ); + + expect(invalidBucket.status).toBe(400); + expect(missingTarget.status).toBe(404); + }); + test("未知 /api/* 返回 404", async () => { const response = await fetch(`${baseUrl}/api/missing`); expect(response.status).toBe(404); @@ -270,7 +407,7 @@ describe("API 路由", () => { store, }); try { - const response = await fetch(`http://127.0.0.1:${prodServer.port}/api/summary`); + const response = await fetch(`http://127.0.0.1:${prodServer.port}/api/dashboard`); expect(response.headers.get("x-content-type-options")).toBe("nosniff"); expect(response.headers.get("referrer-policy")).toBe("strict-origin-when-cross-origin"); } finally { diff --git a/tests/server/checker/store.test.ts b/tests/server/checker/store.test.ts index 82abbe3..f7b45f7 100644 --- a/tests/server/checker/store.test.ts +++ b/tests/server/checker/store.test.ts @@ -227,44 +227,55 @@ describe("ProbeStore", () => { expect(history.items).toHaveLength(20); }); - test("getTargetStats 计算可用率和 duration", () => { + test("getTargetWindowStats 按时间窗口计算基础计数", () => { const targets = store.getTargets(); const t1Id = targets[0]!.id; - const stats = store.getTargetStats(t1Id); + const stats = store.getTargetWindowStats(t1Id, "2025-01-01T00:00:00.000Z", "2025-01-01T00:01:00.000Z"); expect(stats.totalChecks).toBeGreaterThan(0); + expect(stats.upChecks + stats.downChecks).toBe(stats.totalChecks); expect(stats.availability).toBeGreaterThanOrEqual(0); expect(stats.availability).toBeLessThanOrEqual(100); }); - test("无记录目标的 stats", () => { + test("无记录目标的窗口 stats", () => { const targets = store.getTargets(); const t2Id = targets.find((t) => t.name === "test-cmd")!.id; - const stats = store.getTargetStats(t2Id); + const stats = store.getTargetWindowStats(t2Id, "2025-01-01T00:00:00.000Z", "2025-01-01T00:01:00.000Z"); expect(stats.totalChecks).toBe(0); + expect(stats.upChecks).toBe(0); + expect(stats.downChecks).toBe(0); expect(stats.availability).toBe(0); }); - test("getSummary 返回总览统计", () => { - const summary = store.getSummary(); - expect(summary.total).toBe(2); - expect(summary.up + summary.down).toBe(2); - expect(summary.lastCheckTime).not.toBeNull(); + test("getLatestChecksMap 支持 Dashboard 组装当前状态", () => { + const latestChecksMap = store.getLatestChecksMap(); + const targets = store.getTargets(); + const latest = latestChecksMap.get(targets[0]!.id); + + expect(latest).toBeDefined(); + expect(latest!.timestamp).toBe("2025-01-01T01:24:00.000Z"); }); - test("getTrend 返回趋势数据", () => { + test("getTargetCheckpoints 返回窗口内升序检查点", () => { const targets = store.getTargets(); const t1Id = targets[0]!.id; - const trend = store.getTrend(t1Id, "2024-01-01T00:00:00.000Z", "2026-12-31T23:59:59.999Z"); - expect(Array.isArray(trend)).toBe(true); - if (trend.length > 0) { - expect(trend[0]!.hour).toBeDefined(); - expect(trend[0]!.avgDurationMs).toBeDefined(); - expect(trend[0]!.availability).toBeGreaterThanOrEqual(0); - expect(trend[0]!.totalChecks).toBeGreaterThan(0); - } + const checkpoints = store.getTargetCheckpoints(t1Id, "2025-01-01T00:00:00.000Z", "2025-01-01T00:01:00.000Z"); + expect(checkpoints).toEqual([ + { duration_ms: 150.5, matched: 1, timestamp: "2025-01-01T00:00:00.000Z" }, + { duration_ms: 300, matched: 1, timestamp: "2025-01-01T00:00:30.000Z" }, + { duration_ms: null, matched: 0, timestamp: "2025-01-01T00:01:00.000Z" }, + ]); + }); + + test("getTargetDurations 返回成功检查耗时升序数组", () => { + const targets = store.getTargets(); + const t1Id = targets[0]!.id; + + const durations = store.getTargetDurations(t1Id, "2025-01-01T00:00:00.000Z", "2025-01-01T00:01:00.000Z"); + expect(durations).toEqual([150.5, 300]); }); test("getRecentSamples 返回最近采样数据", () => { @@ -439,17 +450,18 @@ describe("ProbeStore", () => { freshStore.close(); }); - test("getAllTargetStats 返回所有 target 的聚合统计", () => { + test("getAllTargetWindowStats 返回所有 target 的窗口聚合统计", () => { const targets = store.getTargets(); const t1Id = targets[0]!.id; const t2Id = targets[1]!.id; - const stats = store.getAllTargetStats(); + const stats = store.getAllTargetWindowStats("2024-01-01T00:00:00.000Z", "2026-12-31T23:59:59.999Z"); expect(stats).toBeInstanceOf(Map); const stats1 = stats.get(t1Id); expect(stats1).toBeDefined(); expect(stats1!.totalChecks).toBeGreaterThan(0); + expect(stats1!.upChecks + stats1!.downChecks).toBe(stats1!.totalChecks); expect(stats1!.availability).toBeGreaterThanOrEqual(0); const stats2 = stats.get(t2Id); @@ -459,7 +471,7 @@ describe("ProbeStore", () => { } }); - test("getAllTargetStats 对无记录的 target 不包含 key", () => { + test("getAllTargetWindowStats 对无记录的 target 不包含 key", () => { const freshStore = new ProbeStore(join(tempDir, "fresh-stats.db")); freshStore.syncTargets([ { @@ -479,13 +491,13 @@ describe("ProbeStore", () => { }, ]); - const stats = freshStore.getAllTargetStats(); + const stats = freshStore.getAllTargetWindowStats("2025-01-01T00:00:00.000Z", "2025-01-02T00:00:00.000Z"); expect(stats.size).toBe(0); freshStore.close(); }); - test("getAllTargetStats 与 getTargetStats 的 availability 精度一致", () => { + test("getAllTargetWindowStats 与 getTargetWindowStats 的 availability 精度一致", () => { const statsStore = new ProbeStore(join(tempDir, "stats-precision.db")); const target: ResolvedHttpTarget = { ...httpTarget, name: "stats-precision" }; statsStore.syncTargets([target]); @@ -502,16 +514,71 @@ describe("ProbeStore", () => { }); } - const targetStats = statsStore.getTargetStats(targetId); - const allStats = statsStore.getAllTargetStats().get(targetId)!; + const targetStats = statsStore.getTargetWindowStats( + targetId, + "2025-01-01T00:00:00.000Z", + "2025-01-01T00:02:00.000Z", + ); + const allStats = statsStore + .getAllTargetWindowStats("2025-01-01T00:00:00.000Z", "2025-01-01T00:02:00.000Z") + .get(targetId)!; expect(targetStats.availability).toBe(66.67); + expect(targetStats.upChecks).toBe(2); + expect(targetStats.downChecks).toBe(1); expect(allStats.availability).toBe(66.67); expect(allStats.availability).toBe(targetStats.availability); statsStore.close(); }); + test("getDashboardIncidentStates 返回按 target 和 timestamp 升序排列的状态序列", () => { + const incidentStore = new ProbeStore(join(tempDir, "dashboard-incidents.db")); + const httpA: ResolvedHttpTarget = { ...httpTarget, name: "incident-http-a" }; + const httpB: ResolvedHttpTarget = { + ...httpTarget, + http: { ...httpTarget.http, url: "https://example.com/incident-b" }, + name: "incident-http-b", + }; + incidentStore.syncTargets([httpA, httpB]); + const targets = incidentStore.getTargets(); + const targetAId = targets.find((target) => target.name === "incident-http-a")!.id; + const targetBId = targets.find((target) => target.name === "incident-http-b")!.id; + + incidentStore.insertCheckResult({ + durationMs: 100, + failure: null, + matched: false, + statusDetail: null, + targetId: targetBId, + timestamp: "2025-01-01T00:03:00.000Z", + }); + incidentStore.insertCheckResult({ + durationMs: 100, + failure: null, + matched: true, + statusDetail: "200 OK", + targetId: targetAId, + timestamp: "2025-01-01T00:02:00.000Z", + }); + incidentStore.insertCheckResult({ + durationMs: 100, + failure: null, + matched: false, + statusDetail: null, + targetId: targetAId, + timestamp: "2025-01-01T00:01:00.000Z", + }); + + expect(incidentStore.getDashboardIncidentStates("2025-01-01T00:00:00.000Z", "2025-01-01T00:03:00.000Z")).toEqual([ + { matched: 0, target_id: targetAId, timestamp: "2025-01-01T00:01:00.000Z" }, + { matched: 1, target_id: targetAId, timestamp: "2025-01-01T00:02:00.000Z" }, + { matched: 0, target_id: targetBId, timestamp: "2025-01-01T00:03:00.000Z" }, + ]); + + incidentStore.close(); + }); + test("prune 删除过期数据", () => { const pruneStore = new ProbeStore(join(tempDir, "prune.db")); pruneStore.syncTargets([httpTarget]); diff --git a/tests/server/metrics.test.ts b/tests/server/metrics.test.ts new file mode 100644 index 0000000..b983909 --- /dev/null +++ b/tests/server/metrics.test.ts @@ -0,0 +1,126 @@ +import { describe, expect, test } from "bun:test"; + +import { + analyzeIncidentSequence, + buildHourlyTrend, + calculateAvailability, + calculateCurrentStreak, + calculatePercentile, + type MetricCheckpoint, +} from "../../src/server/metrics"; + +describe("后端指标计算", () => { + test("可用率无数据返回 0，并保留两位精度", () => { + expect(calculateAvailability(0, 0)).toBe(0); + expect(calculateAvailability(2, 3)).toBe(66.67); + }); + + test("百分位按 ceil(count * N / 100) - 1 取值", () => { + const durations = Array.from({ length: 100 }, (_, index) => index + 1); + + expect(calculatePercentile([], 95)).toBeNull(); + expect(calculatePercentile([40, 10, 30, 20], 95)).toBe(40); + expect(calculatePercentile(durations, 95)).toBe(95); + expect(calculatePercentile(durations, 99)).toBe(99); + }); + + test("无检查数据时故障分析返回空口径", () => { + const result = analyzeIncidentSequence([], "2025-01-01T00:00:00.000Z", "2025-01-01T01:00:00.000Z"); + + expect(result).toEqual({ incidentCount: 0, longestOutage: null, mttr: null }); + expect(calculateCurrentStreak([])).toBeNull(); + }); + + test("窗口起始即故障计入 incident 和最长故障，但不计入 MTTR", () => { + const result = analyzeIncidentSequence( + [ + checkpoint("2025-01-01T00:05:00.000Z", false), + checkpoint("2025-01-01T00:10:00.000Z", false), + checkpoint("2025-01-01T00:20:00.000Z", true), + ], + "2025-01-01T00:00:00.000Z", + "2025-01-01T01:00:00.000Z", + ); + + expect(result.incidentCount).toBe(1); + expect(result.longestOutage).toBe(20 * 60 * 1000); + expect(result.mttr).toBeNull(); + }); + + test("未恢复故障计算到窗口结束且不计入 MTTR", () => { + const result = analyzeIncidentSequence( + [checkpoint("2025-01-01T00:05:00.000Z", true), checkpoint("2025-01-01T00:20:00.000Z", false)], + "2025-01-01T00:00:00.000Z", + "2025-01-01T01:00:00.000Z", + ); + + expect(result.incidentCount).toBe(1); + expect(result.longestOutage).toBe(40 * 60 * 1000); + expect(result.mttr).toBeNull(); + }); + + test("连续异常只计一次 incident，恢复后纳入 MTTR", () => { + const result = analyzeIncidentSequence( + [ + checkpoint("2025-01-01T00:00:00.000Z", true), + checkpoint("2025-01-01T00:05:00.000Z", false), + checkpoint("2025-01-01T00:10:00.000Z", false), + checkpoint("2025-01-01T00:20:00.000Z", true), + ], + "2025-01-01T00:00:00.000Z", + "2025-01-01T01:00:00.000Z", + ); + + expect(result.incidentCount).toBe(1); + expect(result.longestOutage).toBe(15 * 60 * 1000); + expect(result.mttr).toBe(15 * 60 * 1000); + }); + + test("连续状态支持 capped 标记", () => { + expect( + calculateCurrentStreak( + [ + checkpoint("2025-01-01T00:00:00.000Z", true), + checkpoint("2025-01-01T00:01:00.000Z", false), + checkpoint("2025-01-01T00:02:00.000Z", false), + ], + 2, + ), + ).toEqual({ capped: true, count: 2, up: false }); + }); + + test("UTC 小时趋势分桶返回 up/down 和延迟范围", () => { + const trend = buildHourlyTrend([ + checkpoint("2025-01-01T00:10:00.000Z", true, 100), + checkpoint("2025-01-01T00:40:00.000Z", false, null), + checkpoint("2025-01-01T01:05:00.000Z", true, 300), + ]); + + expect(trend).toEqual([ + { + availability: 50, + avgDurationMs: 100, + bucketStart: "2025-01-01T00:00:00.000Z", + downChecks: 1, + maxDurationMs: 100, + minDurationMs: 100, + totalChecks: 2, + upChecks: 1, + }, + { + availability: 100, + avgDurationMs: 300, + bucketStart: "2025-01-01T01:00:00.000Z", + downChecks: 0, + maxDurationMs: 300, + minDurationMs: 300, + totalChecks: 1, + upChecks: 1, + }, + ]); + }); +}); + +function checkpoint(timestamp: string, matched: boolean, durationMs: null | number = null): MetricCheckpoint { + return { durationMs, matched, timestamp }; +} diff --git a/tests/web/constants/target-table-columns.test.ts b/tests/web/constants/target-table-columns.test.ts index d2ee222..2eda58d 100644 --- a/tests/web/constants/target-table-columns.test.ts +++ b/tests/web/constants/target-table-columns.test.ts @@ -19,13 +19,14 @@ function getColumn(columns: Array>, colKey: string function makeTarget(overrides: Partial = {}): TargetStatus { return { + currentStreak: null, group: "default", id: 1, interval: "5s", latestCheck: null, name: "test", recentSamples: [], - stats: { availability: 100, totalChecks: 0 }, + stats: { availability: 100, downChecks: 0, totalChecks: 0, upChecks: 0 }, target: "https://example.com", type: "http", ...overrides, @@ -33,7 +34,7 @@ function makeTarget(overrides: Partial = {}): TargetStatus { } describe("createTargetTableColumns", () => { - test("生成 7 个目标表格列", () => { + test("生成 8 个目标表格列", () => { const columns = createTargetTableColumns(["http", "cmd"]); expect(columns.map((column) => column.colKey)).toEqual([ @@ -42,6 +43,7 @@ describe("createTargetTableColumns", () => { "type", "stats.availability", "recentSamples", + "currentStreak", "latestCheck.durationMs", "interval", ]); @@ -81,4 +83,19 @@ describe("createTargetTableColumns", () => { expect(element.props.children).toBe("tcp"); }); + + test("连续状态列渲染 capped 标记", () => { + const streakColumn = getColumn(createTargetTableColumns(["http"]), "currentStreak"); + const renderCell = streakColumn.cell as (params: PrimaryTableCellParams) => { + props: { children: unknown[] }; + }; + const element = renderCell({ + col: streakColumn, + colIndex: 5, + row: makeTarget({ currentStreak: { capped: true, count: 30, up: false } }), + rowIndex: 0, + }); + + expect(element.props.children.join("")).toBe("▼ 30+"); + }); }); diff --git a/tests/web/constants/target-table-sorters.test.ts b/tests/web/constants/target-table-sorters.test.ts index 13c98c3..02cdd04 100644 --- a/tests/web/constants/target-table-sorters.test.ts +++ b/tests/web/constants/target-table-sorters.test.ts @@ -11,13 +11,14 @@ import { function makeTarget(overrides: Partial = {}): TargetStatus { return { + currentStreak: null, group: "default", id: 1, interval: "5s", latestCheck: null, name: "test", recentSamples: [], - stats: { availability: 100, totalChecks: 0 }, + stats: { availability: 100, downChecks: 0, totalChecks: 0, upChecks: 0 }, target: "https://example.com", type: "http", ...overrides, @@ -57,20 +58,20 @@ describe("statusSorter", () => { describe("availabilitySorter", () => { test("低可用率排前面", () => { - const low = makeTarget({ stats: { availability: 95, totalChecks: 100 } }); - const high = makeTarget({ stats: { availability: 99.9, totalChecks: 100 } }); + const low = makeTarget({ stats: { availability: 95, downChecks: 5, totalChecks: 100, upChecks: 95 } }); + const high = makeTarget({ stats: { availability: 99.9, downChecks: 1, totalChecks: 100, upChecks: 99 } }); expect(availabilitySorter(low, high)).toBeLessThan(0); }); test("相同可用率返回 0", () => { - const a = makeTarget({ stats: { availability: 99.9, totalChecks: 100 } }); - const b = makeTarget({ stats: { availability: 99.9, totalChecks: 50 } }); + const a = makeTarget({ stats: { availability: 99.9, downChecks: 1, totalChecks: 100, upChecks: 99 } }); + const b = makeTarget({ stats: { availability: 99.9, downChecks: 1, totalChecks: 50, upChecks: 49 } }); expect(availabilitySorter(a, b)).toBe(0); }); test("无 stats 按 0 处理", () => { const noStats = makeTarget({ stats: undefined as unknown as TargetStatus["stats"] }); - const high = makeTarget({ stats: { availability: 99.9, totalChecks: 100 } }); + const high = makeTarget({ stats: { availability: 99.9, downChecks: 1, totalChecks: 100, upChecks: 99 } }); expect(availabilitySorter(noStats, high)).toBeLessThan(0); }); }); diff --git a/tests/web/utils/stats.test.ts b/tests/web/utils/stats.test.ts deleted file mode 100644 index cf6a8a8..0000000 --- a/tests/web/utils/stats.test.ts +++ /dev/null @@ -1,29 +0,0 @@ -import { describe, expect, test } from "bun:test"; - -import type { TrendPoint } from "../../../src/shared/api"; - -import { computeTrendStats } from "../../../src/web/utils/stats"; - -describe("computeTrendStats", () => { - test("空趋势返回 0 统计", () => { - expect(computeTrendStats([])).toEqual({ downChecks: 0, totalChecks: 0, upChecks: 0 }); - }); - - test("汇总总检查、正常和异常数量", () => { - const points: TrendPoint[] = [ - { availability: 80, avgDurationMs: 100, hour: "2025-01-01T00:00:00.000Z", totalChecks: 10 }, - { availability: 40, avgDurationMs: 200, hour: "2025-01-01T01:00:00.000Z", totalChecks: 5 }, - ]; - - expect(computeTrendStats(points)).toEqual({ downChecks: 5, totalChecks: 15, upChecks: 10 }); - }); - - test("按每个趋势点四舍五入正常数量", () => { - const points: TrendPoint[] = [ - { availability: 33.3, avgDurationMs: null, hour: "2025-01-01T00:00:00.000Z", totalChecks: 3 }, - { availability: 66.7, avgDurationMs: null, hour: "2025-01-01T01:00:00.000Z", totalChecks: 3 }, - ]; - - expect(computeTrendStats(points)).toEqual({ downChecks: 3, totalChecks: 6, upChecks: 3 }); - }); -}); diff --git a/tests/web/utils/time.test.ts b/tests/web/utils/time.test.ts index 894c56d..123ddef 100644 --- a/tests/web/utils/time.test.ts +++ b/tests/web/utils/time.test.ts @@ -1,6 +1,6 @@ import { describe, expect, test } from "bun:test"; -import { subtractHours } from "../../../src/web/utils/time"; +import { formatDurationUnit, formatRelativeTime, isOlderThan, subtractHours } from "../../../src/web/utils/time"; describe("subtractHours", () => { test("正常扣减小时", () => { @@ -27,3 +27,38 @@ describe("subtractHours", () => { expect(result.toISOString()).toBe("2025-01-15T12:00:00.000Z"); }); }); + +describe("formatRelativeTime", () => { + const now = new Date("2025-01-01T00:02:00.000Z"); + + test("格式化秒和分钟", () => { + expect(formatRelativeTime("2025-01-01T00:01:45.000Z", now)).toBe("15秒前"); + expect(formatRelativeTime("2025-01-01T00:00:00.000Z", now)).toBe("2分钟前"); + }); + + test("无时间返回占位", () => { + expect(formatRelativeTime(null, now)).toBe("尚无检查数据"); + expect(formatRelativeTime("invalid", now)).toBe("尚无检查数据"); + }); +}); + +describe("formatDurationUnit", () => { + test("按秒、分钟、小时动态格式化", () => { + expect(formatDurationUnit(1500)).toEqual({ suffix: "秒", value: 1.5 }); + expect(formatDurationUnit(120000)).toEqual({ suffix: "分钟", value: 2 }); + expect(formatDurationUnit(5400000)).toEqual({ suffix: "小时", value: 1.5 }); + }); + + test("空时长返回占位", () => { + expect(formatDurationUnit(null)).toEqual({ suffix: "", value: 0 }); + }); +}); + +describe("isOlderThan", () => { + test("判断时间是否超过阈值", () => { + const now = new Date("2025-01-01T00:02:00.000Z"); + + expect(isOlderThan("2025-01-01T00:00:59.000Z", 60000, now)).toBe(true); + expect(isOlderThan("2025-01-01T00:01:30.000Z", 60000, now)).toBe(false); + }); +});