2.8 KiB
2.8 KiB
ADDED Requirements
Requirement: 总览统计 API
系统 SHALL 提供 GET /api/summary 端点，返回所有目标的总体统计信息。
Scenario: 获取总览统计
- WHEN 客户端请求
GET /api/summary - THEN 系统 SHALL 返回 JSON 包含 total（总目标数）、up（正常数）、down（异常数）、avgLatencyMs（所有目标平均延迟）、lastCheckTime（最近一次拨测时间）
Requirement: 目标列表 API
系统 SHALL 提供 GET /api/targets 端点，返回所有目标及其最新状态和统计摘要。
Scenario: 获取目标列表
- WHEN 客户端请求
GET /api/targets - THEN 系统 SHALL 返回 JSON 数组，每个元素包含目标基本信息、最近一次拨测结果（timestamp、success、statusCode、latencyMs、error、matched）和统计摘要（totalChecks、availability、avgLatencyMs、p99LatencyMs）
Scenario: 目标无历史记录
- WHEN 某目标尚未执行过任何拨测
- THEN 其 latestCheck 为 null，stats 中 totalChecks 为 0
Requirement: 历史记录 API
系统 SHALL 提供 GET /api/targets/:id/history 端点，返回指定目标的最近 N 条拨测记录。
Scenario: 获取最近历史记录
- WHEN 客户端请求
GET /api/targets/1/history?limit=20 - THEN 系统 SHALL 返回最多 20 条拨测记录，按时间倒序排列
Scenario: 使用默认 limit
- WHEN 客户端请求
GET /api/targets/1/history（未指定 limit） - THEN 系统 SHALL 默认返回最近 20 条记录
Requirement: 趋势聚合 API
系统 SHALL 提供 GET /api/targets/:id/trend 端点，返回指定目标按小时聚合的趋势数据。
Scenario: 获取 24 小时趋势
- WHEN 客户端请求
GET /api/targets/1/trend?hours=24 - THEN 系统 SHALL 返回按小时分组的聚合数据，每个数据点包含 hour、avgLatencyMs、availability、totalChecks
Scenario: 使用默认时间范围
- WHEN 客户端请求
GET /api/targets/1/trend（未指定 hours） - THEN 系统 SHALL 默认返回最近 24 小时的趋势数据
Requirement: 保留健康检查端点
系统 SHALL 保留 GET /health 端点，不受拨测功能影响。
Scenario: 访问健康检查
- WHEN 客户端请求
GET /health - THEN 系统 SHALL 返回与之前格式一致的健康检查响应
Requirement: API 错误处理
系统 SHALL 对不存在的目标 ID 和无效参数返回适当的 HTTP 错误响应。
Scenario: 查询不存在的目标
- WHEN 客户端请求
GET /api/targets/999/history - THEN 系统 SHALL 返回 404 状态码和错误信息
Scenario: 无效的 limit 参数
- WHEN 客户端请求
GET /api/targets/1/history?limit=abc - THEN 系统 SHALL 返回 400 状态码和错误信息