## Purpose

定义拨测系统的 REST API 端点：总览统计、目标列表含状态、历史记录和趋势聚合。

## 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 状态码和错误信息