54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
## 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` 字段（语义变更为基于时间窗口计算）
|