## Purpose

定义拨测调度引擎的行为：按 interval 分组定时、组内并发拨测、expect 结果校验和结果持久化。

## Requirements

### Requirement: 按 interval 分组调度
系统 SHALL 将拨测目标按 interval 值分组，每组使用独立的定时器进行调度。

#### Scenario: 相同 interval 的目标共享定时器
- **WHEN** 多个 target 配置了相同的 interval（如 30s）
- **THEN** 系统 SHALL 使用同一个 `setInterval` 定时器，每次 tick 并发拨测所有该组目标

#### Scenario: 不同 interval 的目标各自调度
- **WHEN** target A 配置 15s interval，target B 配置 30s interval
- **THEN** 系统 SHALL 创建两个独立定时器，分别按各自频率调度

### Requirement: 组内并发拨测
系统 SHALL 在每次调度 tick 时并发执行同组内目标的检查，但实际同时运行的检查数 MUST 受全局 `probes.execution.maxConcurrentChecks` 限制。当某个目标的 checker 执行 rejected（非正常 CheckResult 返回，而是 Promise reject）时，系统 SHALL 将该异常记录为 `matched: false` 的 check_result，而非仅 console.warn。

#### Scenario: 同组目标并发执行
- **WHEN** 调度器触发一次 tick，该组有 3 个目标，且全局并发余量至少为 3
- **THEN** 系统 SHALL 同时执行 3 个 checker，而非顺序执行

#### Scenario: 单个目标失败不影响同组其他目标
- **WHEN** 同组中某个目标的检查请求超时或失败（checker 正常返回 CheckResult）
- **THEN** 其他目标的检查 SHALL 正常完成并记录结果

#### Scenario: 同组中某个目标的 checker 执行 rejected
- **WHEN** 同组中某个目标的 checker 执行抛出未捕获异常（Promise rejected）
- **THEN** 系统 SHALL 为该目标写入一条 `matched: false` 的 check_result，failure 为 `{ kind: "error", phase: "internal", path: "engine", message: <rejected reason> }`，其他目标的检查 SHALL 不受影响

#### Scenario: rejected 结果通过索引关联 targetName
- **WHEN** checker 执行 rejected
- **THEN** 系统 SHALL 通过 Promise.allSettled 的索引关联回 target 数组，获取对应的 targetName 用于写入 check_result

#### Scenario: 全局并发限制生效
- **WHEN** 调度器同时触发 10 个目标且 probes.execution.maxConcurrentChecks 为 3
- **THEN** 系统 MUST 同时最多运行 3 个检查，其余检查等待并发槽位释放

### Requirement: HTTP 拨测执行
系统 SHALL 对 `type: http` 的目标执行 HTTP 请求，支持 GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 方法，并携带 `http.headers` 和 `http.body`。系统 SHALL 支持 `http.ignoreSSL` 配置跳过 SSL 证书校验，支持 `http.maxRedirects` 配置控制重定向行为。HTTP response body 读取 SHALL 受 `http.maxBodyBytes` 流式限制，重定向跟随 SHALL 释放被跟随响应的 body。

#### Scenario: 执行 GET 请求
- **WHEN** 目标配置 method 为 GET
- **THEN** 系统 SHALL 发送 GET 请求到目标 URL

#### Scenario: 执行 POST 请求带 body
- **WHEN** 目标配置 method 为 POST 且指定了 body 和 Content-Type header
- **THEN** 系统 SHALL 发送带指定 body 的 POST 请求

#### Scenario: 携带自定义 headers
- **WHEN** 目标配置了 headers（如 Authorization）
- **THEN** 系统 SHALL 在请求中包含所有配置的 headers

#### Scenario: HTTP body 读取上限
- **WHEN** HTTP response body 超过该 target 的 maxBodyBytes
- **THEN** 系统 MUST 停止继续读取 response body，并记录 `matched=false`、`failure.kind="error"`、`failure.phase="body"` 的结构化输出超限错误

#### Scenario: HTTP body 大小等于上限
- **WHEN** HTTP response body 的字节数等于该 target 的 maxBodyBytes
- **THEN** 系统 SHALL 允许该 body 进入后续解码和 expect 校验

#### Scenario: HTTP body 上限为 0
- **WHEN** HTTP target 配置 maxBodyBytes 为 0 且响应体非空
- **THEN** 系统 SHALL 停止读取并记录 body 超限错误

#### Scenario: 忽略 SSL 证书校验
- **WHEN** 目标配置 `http.ignoreSSL: true` 且目标 URL 为 HTTPS
- **THEN** 系统 SHALL 跳过 SSL 证书校验，即使证书无效也正常完成请求

#### Scenario: 不忽略 SSL 证书校验
- **WHEN** 目标未配置 `http.ignoreSSL` 或配置为 `false`，且目标 URL 使用自签名证书
- **THEN** 系统 SHALL 因 SSL 证书校验失败而记录请求错误

#### Scenario: 默认不跟随重定向
- **WHEN** 目标未配置 `http.maxRedirects` 或配置为 0，且服务端返回 301/302
- **THEN** 系统 SHALL 不跟随重定向，直接返回 301/302 的响应状态码和响应头

#### Scenario: 配置跟随重定向
- **WHEN** 目标配置 `http.maxRedirects: 5` 且服务端返回重定向
- **THEN** 系统 SHALL 跟随重定向，最多跟随 5 次，并在跟随前释放当前重定向响应的 body

#### Scenario: 超过最大重定向次数
- **WHEN** 目标配置 `http.maxRedirects: 1` 且服务端连续返回两次重定向
- **THEN** 系统 SHALL 只跟随第一次重定向，并返回第二次重定向响应的状态码和响应头

#### Scenario: POST 重定向改 GET
- **WHEN** POST 请求遇到 301/302 或任意方法请求遇到 303，且系统决定按 GET 跟随重定向
- **THEN** 系统 SHALL 移除请求 body，并清理 content-type、content-length 等 body 相关 headers 后发起后续 GET 请求

#### Scenario: 跨 origin 重定向敏感 header
- **WHEN** HTTP 请求跟随重定向到不同 origin
- **THEN** 系统 SHALL NOT 将 authorization、cookie 等敏感 headers 转发到新的 origin

#### Scenario: 响应体编码自动检测
- **WHEN** HTTP 响应的 `Content-Type` header 包含 `charset=gbk` 或 `charset="gbk"`
- **THEN** 系统 SHALL 使用 GBK 编码解码响应体，而非硬编码 UTF-8

#### Scenario: 响应体编码回退 UTF-8
- **WHEN** HTTP 响应的 `Content-Type` header 未指定 charset
- **THEN** 系统 SHALL 使用 UTF-8 编码解码响应体

#### Scenario: 响应体编码不支持
- **WHEN** HTTP 响应的 `Content-Type` header 指定了当前运行时不支持的 charset
- **THEN** 系统 SHALL 记录 `matched=false`、`failure.kind="error"`、`failure.phase="body"` 的解码失败结果

### Requirement: 请求超时控制
系统 SHALL 对每次 checker 执行实施超时控制，超时时间使用目标配置的 timeout 值。

#### Scenario: HTTP 请求超时
- **WHEN** HTTP 请求在 timeout 时间内未收到响应
- **THEN** 系统 SHALL 中止该请求，记录为失败并标注超时错误

#### Scenario: cmd 执行超时
- **WHEN** cmd 进程在 timeout 时间内未退出
- **THEN** 系统 MUST 终止该子进程，记录为失败并标注超时错误

#### Scenario: 请求在超时前完成
- **WHEN** checker 在超时前完成执行
- **THEN** 系统 SHALL 正常记录执行结果并进入 expect 校验

### Requirement: expect 校验
系统 SHALL 在 checker 执行完成后根据目标类型的 Resolved expect 执行计划校验观测结果，校验结果和首个失败原因记入 check result。HTTP checker 的 `durationMs` SHALL 表示完整 checker 执行耗时，包括重定向、响应体读取、响应体解码和 expect 校验。HTTP `expect.durationMs` SHALL 使用 `RawValueExpectation` 输入并在 resolve 阶段转换为运行期 `ValueExpectation`；旧 `expect.maxDurationMs` MUST NOT 再作为运行期耗时阈值使用。

#### Scenario: HTTP 默认状态码
- **WHEN** HTTP target 未配置 `expect.status`
- **THEN** 系统 SHALL 在 Resolved HTTP expect 中物化默认 `status: [200]` 并按该语义校验响应状态码

#### Scenario: 校验 HTTP 状态码精确值
- **WHEN** HTTP target 配置了 `expect.status: [200, 201]`
- **THEN** 系统 SHALL 检查响应状态码是否在列表中，将匹配结果记录到 matched 字段

#### Scenario: 校验 HTTP 状态码范围模式
- **WHEN** HTTP target 配置了 `expect.status: ["2xx"]`
- **THEN** 系统 SHALL 检查响应状态码是否在 200-299 范围内

#### Scenario: 校验 HTTP 状态码混合模式
- **WHEN** HTTP target 配置了 `expect.status: ["2xx", 301]`，且响应状态码为 204
- **THEN** 系统 SHALL 判定状态码匹配（204 属于 2xx 范围）

#### Scenario: 校验 HTTP 响应头
- **WHEN** HTTP target 配置了 `expect.headers: {"Content-Type": {contains: "application/json"}}`
- **THEN** 系统 SHALL 检查响应头是否符合指定规则，全部匹配时继续后续阶段

#### Scenario: 校验 HTTP 响应体
- **WHEN** HTTP target 配置了有序 `expect.body` ContentExpectations 数组
- **THEN** 系统 SHALL 按数组顺序执行 body expectations，任一失败立即记录 failure 并停止后续 expectation

#### Scenario: 校验 HTTP 完整耗时阈值
- **WHEN** 目标配置了 `expect.durationMs: {lte: 1000}`，且 HTTP checker 完整执行（含重定向、body 读取、解码和 expect）后的 durationMs 超过阈值
- **THEN** 系统 SHALL 判定 duration 不匹配，记录完整 durationMs 和 duration failure

#### Scenario: HTTP body 前耗时已不可能满足 durationMs 上界
- **WHEN** HTTP target 配置了 body 校验和 `expect.durationMs` 上界 matcher（如 `{lte: 1000}`），且进入 body 读取前的已耗时已使该 matcher 不可能通过
- **THEN** 系统 SHALL 直接返回 duration failure，且 MUST NOT 读取 response body

#### Scenario: HTTP body 失败优先于后续 duration 检查
- **WHEN** HTTP target 配置了 body 校验和 `expect.durationMs: {lte: 1000}`，body 阶段存在失败，且完整执行后 duration 也超过阈值
- **THEN** 系统 SHALL 返回 body 阶段的失败（首个失败为准），durationMs SHALL 记录完整耗时

#### Scenario: HTTP 慢响应体计入耗时
- **WHEN** HTTP target 配置了 body 校验和 `expect.durationMs: {lte: 1000}`，且响应头很快返回但响应体读取导致完整执行耗时超过阈值
- **THEN** 系统 SHALL 判定 duration 不匹配并记录完整 durationMs

#### Scenario: 多条 expect 规则
- **WHEN** 目标同时配置状态、duration、元数据和内容 expectations
- **THEN** 系统 SHALL 所有 expectations 全部通过时 matched 为 true，任一不通过则为 false 并记录首个失败原因

#### Scenario: cmd 默认 exitCode
- **WHEN** cmd target 未配置 `expect.exitCode`
- **THEN** 系统 SHALL 在 Resolved cmd expect 中物化默认 `exitCode: [0]` 并按该语义校验命令退出码

#### Scenario: 校验 cmd stdout
- **WHEN** cmd target 配置了有序 `expect.stdout` ContentExpectations 数组
- **THEN** 系统 SHALL 按数组顺序执行 stdout expectations，任一失败立即记录 failure 并停止后续 expectation

### Requirement: Body 校验按需解析
系统 SHALL 仅在 HTTP target 配置了 body 校验，且 status、headers 阶段均通过，并且进入 body 前未确定 `expect.durationMs` 已失败时才读取并解析响应体，避免不必要的读取和解析开销。HTTP target 未配置 body 校验时，系统 SHALL NOT 读取 response body。仅当 Resolved `durationMs` 包含上界 matcher 且当前已耗时已经使其不可能通过时，系统 MAY 在读取 body 前返回 duration failure；其他 duration matcher SHALL 在完整执行耗时可用后校验。

#### Scenario: status 失败时不读取 body
- **WHEN** HTTP target 的 status 阶段不匹配
- **THEN** 系统 SHALL 立即返回 matched=false，且 MUST NOT 读取 response body

#### Scenario: headers 失败时不读取 body
- **WHEN** HTTP target 的 status 阶段匹配但 headers 阶段不匹配
- **THEN** 系统 SHALL 立即返回 matched=false，且 MUST NOT 读取 response body

#### Scenario: 进入 body 前 durationMs 上界已失败时不读取 body
- **WHEN** HTTP target 已配置 `expect.durationMs` 上界 matcher，且进入 body 读取前的已耗时已经使该 matcher 不可能通过
- **THEN** 系统 SHALL 返回 duration failure，且 MUST NOT 读取 response body

#### Scenario: 仅配置 contains 时不解析 JSON
- **WHEN** HTTP target 仅配置 body contains expectation 而未配置 json/css/xpath expectation
- **THEN** 系统 SHALL 不执行 JSON.parse 或 HTML/XML 解析

#### Scenario: 配置 json 时解析 JSON 失败
- **WHEN** HTTP target 配置了 body json expectation 但响应体不是合法 JSON
- **THEN** 系统 SHALL 判定 matched 为 false，并记录 json expectation 对应的 failure.path

### Requirement: HTTP 运行期错误归属
HTTP checker SHALL 将运行期失败归属到实际失败阶段。请求、网络、TLS 和 timeout 错误 SHALL 记录为 request 阶段错误；body 超限、响应体解码失败、响应内容解析失败 SHALL 记录为 body 阶段错误；expect 不匹配 SHALL 记录为对应 mismatch 阶段。

#### Scenario: 请求错误归属 request
- **WHEN** HTTP 请求因为网络、TLS 或 timeout 失败
- **THEN** 系统 SHALL 记录 `matched=false`、`failure.kind="error"`、`failure.phase="request"`

#### Scenario: body 超限归属 body
- **WHEN** HTTP response body 超过 maxBodyBytes
- **THEN** 系统 SHALL 记录 `failure.kind="error"`、`failure.phase="body"`、`failure.path="body"`

#### Scenario: body 解析错误归属 body
- **WHEN** HTTP response body 已读取，但解码、JSON 解析、CSS 解析或 XPath 解析失败
- **THEN** 系统 SHALL 记录 `failure.phase="body"`，且 SHALL NOT 将该失败记录为 request 错误

### Requirement: 拨测结果记录
系统 SHALL 在每次 checker 完成后，将结果写入 SQLite 数据存储，包含 target_id、timestamp、matched、duration_ms、observation、failure 字段。detail SHALL 为 API 层派生字段，不写入存储层；系统 SHALL NOT 写入 status_detail 字段。

#### Scenario: 成功检查结果记录
- **WHEN** checker 成功执行且 expect 全部匹配
- **THEN** 系统 SHALL 记录 matched=true、duration_ms、observation，failure 为 null

#### Scenario: 执行失败结果记录
- **WHEN** checker 执行失败（网络错误、超时、命令启动失败、输出超限等）
- **THEN** 系统 SHALL 记录 matched=false、failure.kind="error" 和具体错误信息，并在可收集领域观测数据时记录 observation

#### Scenario: expect 不匹配结果记录
- **WHEN** checker 执行成功但 expect 不匹配
- **THEN** 系统 SHALL 记录 matched=false、observation、failure.kind="mismatch" 和具体不匹配信息

### Requirement: runner 选择
系统 SHALL 根据 target.type 选择对应 runner 执行检查。

#### Scenario: 选择 HTTP runner
- **WHEN** target.type 为 `http`
- **THEN** 系统 SHALL 使用 HTTP runner 执行该目标

#### Scenario: 选择 cmd runner
- **WHEN** target.type 为 `cmd`
- **THEN** 系统 SHALL 使用 cmd runner 执行该目标

### Requirement: 定期数据清理
ProbeEngine SHALL 在启动时注册数据清理定时器，定期调用 ProbeStore.prune() 清理过期数据和空壳非活跃目标。

#### Scenario: 引擎启动注册清理
- **WHEN** ProbeEngine.start() 被调用且 retentionMs > 0
- **THEN** 系统 SHALL 立即执行一次 prune，然后每隔 1 小时再次执行

#### Scenario: 引擎停止清除定时器
- **WHEN** ProbeEngine.stop() 被调用
- **THEN** 系统 SHALL 清除清理定时器，不再执行后续清理

#### Scenario: retentionMs 为 0 不注册清理
- **WHEN** ProbeEngine 构造时 retentionMs 为 0
- **THEN** 系统 SHALL 不注册清理定时器