refactor: 移除 success 字段，简化为 matched 单层判定模型

openspec/changes/archive/2026-05-10-abstract-target-expect-checkers/specs/probe-api/spec.md

@@ -0,0 +1,54 @@
+## MODIFIED Requirements
+
+### Requirement: 总览统计 API
+系统 SHALL 提供 `GET /api/summary` 端点，返回所有目标的总体统计信息。
+
+#### Scenario: 获取总览统计
+- **WHEN** 客户端请求 `GET /api/summary`
+- **THEN** 系统 SHALL 返回 JSON 包含 total（总目标数）、up（正常数）、down（异常数）、avgDurationMs（所有目标平均耗时）、lastCheckTime（最近一次检查时间）
+
+### Requirement: 目标列表 API
+系统 SHALL 提供 `GET /api/targets` 端点，返回所有 typed target 及其最新状态和统计摘要。
+
+#### Scenario: 获取目标列表
+- **WHEN** 客户端请求 `GET /api/targets`
+- **THEN** 系统 SHALL 返回 JSON 数组，每个元素包含目标基本信息（id、name、type、target、interval）、最近一次检查结果（timestamp、success、matched、durationMs、statusDetail、failure）和统计摘要（totalChecks、availability、avgDurationMs、p99DurationMs）
+
+#### 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 条检查记录，按时间倒序排列，且每条包含 success、matched、durationMs、statusDetail 和 failure
+
+#### 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、avgDurationMs、availability、totalChecks
+
+#### Scenario: 使用默认时间范围
+- **WHEN** 客户端请求 `GET /api/targets/1/trend`（未指定 hours）
+- **THEN** 系统 SHALL 默认返回最近 24 小时的趋势数据
+
+## ADDED Requirements
+
+### Requirement: 失败信息 API 契约
+系统 SHALL 通过 API 返回结构化 failure 信息，供 Dashboard 展示和后续排查。
+
+#### Scenario: 返回 expect 不匹配信息
+- **WHEN** 最近一次检查结果包含 failure.kind=`mismatch`
+- **THEN** `/api/targets` 和 `/api/targets/:id/history` SHALL 返回该 failure 的 kind、phase、path、expected、actual、message 字段
+
+#### Scenario: 无失败信息
+- **WHEN** 检查结果 success=true 且 matched=true
+- **THEN** API SHALL 返回 failure 为 null