DiAL/openspec/specs/probe-api/spec.md at b8810f11829926e72be48a50b2c7b6f32583d8b8

Files

lanyuanxiaoyao b8810f1182 feat: 重构为多类型 checker 通用框架，支持 HTTP 与命令检查

- 引入 typed target 判别联合，支持 http 与 command 两种 checker
- expect 重构为有序规则数组，按配置顺序快速失败并生成结构化 failure
- 新增 command runner，支持 exec + args 本地命令执行
- 引入全局并发限制 maxConcurrentChecks 和 size 解析 (KB/MB/GB)
- HTTP/command 各自独立 expect pipeline，应用领域默认成功语义
- SQLite schema、API、Dashboard 全链路调整为 checker 通用契约
- 补充完整测试覆盖（192 tests），更新 README 与示例配置

2026-05-10 22:25:21 +08:00

3.5 KiB

Raw Blame History

Purpose

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

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 小时的趋势数据

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

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

3.5 KiB Raw Blame History Unescape Escape