refactor: 后端架构加固 — 泛型化、批量查询、bootstrap 统一、路径修复与 pageSize 上限

- CheckerDefinition 泛型化，HTTP/Command checker 移除 resolved target 断言 - 新增 ProbeStore.getAllRecentSamples 消除 targets 路由 N+1 查询 - 统一 getAllTargetStats 与 getTargetStats 的 availability 精度 - Engine rejected 结果写入 internal error 记录，提升可观测性 - 新增 bootstrap.ts 统一 dev/production 启动序列 - dataDir 相对路径改为基于配置文件目录解析 - validatePagination 增加 pageSize 上限 200 校验 - 修复 ErrorBoundary override 标记 - 更新 README/DEVELOPMENT 文档，新增完整测试覆盖
2026-05-13 18:15:46 +08:00
parent 6ea185315f
commit 147a2559ae
30 changed files with 930 additions and 129 deletions
--- a/openspec/changes/backend-architecture-hardening/specs/batch-data-queries/spec.md
+++ b/openspec/changes/backend-architecture-hardening/specs/batch-data-queries/spec.md
@@ -0,0 +1,44 @@
+## ADDED Requirements
+
+### Requirement: 批量查询所有目标的最近采样数据
+系统 SHALL 提供 `getAllRecentSamples(limit: number)` 方法，通过单次 SQL 查询获取所有 target 的最近 N 条采样数据，返回 `Map<number, Array<{ timestamp: string; duration_ms: number | null; matched: number }>>` 结构。
+
+#### Scenario: 获取所有目标的最近采样
+- **WHEN** 调用 `getAllRecentSamples(30)`
+- **THEN** 系统 SHALL 通过单次 SQL 查询获取每个 target 最近 30 条记录，返回按 target_id 索引的 Map
+
+#### Scenario: 目标无历史记录
+- **WHEN** 某 target 在 check_results 表中无任何记录
+- **THEN** 该 target_id 在返回的 Map 中 SHALL 不存在对应的 key
+
+#### Scenario: 采样数据排序
+- **WHEN** 获取采样数据
+- **THEN** 每个 target 的记录 SHALL 按 timestamp 降序排列（最新在前）
+
+## MODIFIED Requirements
+
+### Requirement: targets 列表使用批量方法
+`handleTargets`（routes/targets.ts 中生成 TargetStatus[] 的逻辑）SHALL 使用 `getLatestChecksMap`、`getAllTargetStats` 和 `getAllRecentSamples` 替代逐目标查询，消除 N+1 查询。
+
+#### Scenario: 目标列表使用批量查询
+- **WHEN** 处理 `GET /api/targets` 请求
+- **THEN** 系统 SHALL 分别调用 `getLatestChecksMap()`、`getAllTargetStats()`、`getAllRecentSamples(30)` 批量获取数据，在内存中组装 TargetStatus 数组，而非对每个 target 逐条查询数据库
+
+#### Scenario: 目标无采样数据
+- **WHEN** 某 target 在 getAllRecentSamples 返回的 Map 中不存在
+- **THEN** 该 target 的 recentSamples SHALL 为空数组
+
+### Requirement: 批量查询目标统计
+系统 SHALL 提供 `getAllTargetStats` 方法，通过单次 SQL GROUP BY 聚合查询获取所有 target 的拨测统计（totalChecks 和 availability）。availability 计算精度 SHALL 与 `getTargetStats` 一致，统一使用 `Math.round(value * 100) / 100` 保留两位小数。
+
+#### Scenario: 获取所有目标的聚合统计
+- **WHEN** 调用 `getAllTargetStats()`
+- **THEN** 系统 SHALL 执行单次 GROUP BY 聚合查询，在内存中计算 availability 并返回 `Map<number, { totalChecks, availability }>`
+
+#### Scenario: availability 精度
+- **WHEN** 计算 availability（upCount / totalChecks * 100）
+- **THEN** 结果 SHALL 使用 `Math.round(value * 100) / 100` 四舍五入保留两位小数，与 `getTargetStats` 方法一致
+
+#### Scenario: 目标无历史记录
+- **WHEN** 某 target 在 check_results 表中无任何记录
+- **THEN** 该 target_id 在返回的 Map 中 SHALL 不存在对应的 key
--- a/openspec/changes/backend-architecture-hardening/specs/checker-runner-abstraction/spec.md
+++ b/openspec/changes/backend-architecture-hardening/specs/checker-runner-abstraction/spec.md
@@ -0,0 +1,47 @@
+## MODIFIED Requirements
+
+### Requirement: Checker 接口定义
+系统 SHALL 在 `src/server/checker/runner/types.ts` 中定义面向扩展的泛型 `CheckerDefinition<TResolved extends ResolvedTargetBase = ResolvedTargetBase>`，包含 `type`、`configKey`、TypeBox 配置契约、启动期语义校验、`resolve`、`execute`、`serialize` 成员。泛型参数 SHALL 约束 `execute` 和 `serialize` 方法的 target 参数类型，使 checker 实现内部获得编译期类型安全。默认泛型参数 `= ResolvedTargetBase` 保证中间层（registry、engine、config-loader）无需指定泛型。
+
+#### Scenario: Checker 接口包含必要方法
+- **WHEN** 开发者实现一个新的 Checker
+- **THEN** 该实现 MUST 提供 `type`（字符串标识）、`configKey`（配置分组名）、TypeBox 配置契约、启动期语义校验、`resolve(target, context): TResolved`（解析配置并填充默认值）、`execute(target: TResolved, ctx)`（执行探测返回 CheckResult）和 `serialize(target: TResolved)`（返回 target 展示文本和 config JSON）
+
+#### Scenario: CheckerContext 注入 signal
+- **WHEN** 引擎调用 `checker.execute(target, ctx)`
+- **THEN** `ctx.signal` SHALL 是一个由引擎创建的 `AbortSignal`，在超时或引擎关闭时 abort
+
+#### Scenario: resolve 不承担通用契约校验
+- **WHEN** config-loader 调用 checker.resolve()
+- **THEN** checker.resolve() SHALL 假定配置已经通过 TypeBox/Ajv 契约校验和启动期语义校验，只负责默认值填充、路径解析和领域配置转换
+
+#### Scenario: 接口方法使用泛型约束
+- **WHEN** 开发者查看 `CheckerDefinition<TResolved>` 接口签名
+- **THEN** `resolve` 的返回值 SHALL 为 `TResolved`；`execute` 的参数 SHALL 为 `TResolved`；`serialize` 的参数 SHALL 为 `TResolved`
+
+#### Scenario: checker 实现无需手动断言
+- **WHEN** HttpChecker 实现 `CheckerDefinition<ResolvedHttpTarget>`
+- **THEN** `execute` 方法的 target 参数类型 SHALL 直接为 `ResolvedHttpTarget`，无需在方法内部使用 `as` 类型断言
+
+#### Scenario: registry 使用默认泛型参数
+- **WHEN** CheckerRegistry 存储和返回 checker 实例
+- **THEN** registry 内部 SHALL 使用 `CheckerDefinition`（等价于 `CheckerDefinition<ResolvedTargetBase>`），实现类型擦除
+
+### Requirement: CheckerRegistry 注册中心
+系统 SHALL 在 `src/server/checker/runner/registry.ts` 中提供 `CheckerRegistry` 类，支持 `register(checker)`、`get(type)` 和 `supportedTypes`。重复注册同一 type SHALL 抛出错误。registry 内部 SHALL 存储 `CheckerDefinition`（使用默认泛型参数），对外提供类型擦除后的接口。
+
+#### Scenario: 注册并获取 Checker
+- **WHEN** 调用 `registry.register(new HttpChecker())` 后再调用 `registry.get("http")`
+- **THEN** 返回的 SHALL 是之前注册的 HttpChecker 实例（类型为 `CheckerDefinition`）
+
+#### Scenario: 获取未注册的 type
+- **WHEN** 调用 `registry.get("unknown")` 且未注册对应 type 的 checker
+- **THEN** 系统 SHALL 抛出错误，提示不支持的 probe type
+
+#### Scenario: 重复注册
+- **WHEN** 同一 type 值被重复 `register()`
+- **THEN** 系统 SHALL 抛出错误，提示该 type 已注册
+
+#### Scenario: 查询支持的 type 列表
+- **WHEN** 注册了 "http" 和 "command" 两个 checker 后查询 `registry.supportedTypes`
+- **THEN** 返回的数组 SHALL 包含 `["http", "command"]`（按注册顺序）
--- a/openspec/changes/backend-architecture-hardening/specs/probe-api/spec.md
+++ b/openspec/changes/backend-architecture-hardening/specs/probe-api/spec.md
@@ -0,0 +1,32 @@
+## MODIFIED Requirements
+
+### Requirement: API 错误处理
+系统 SHALL 对不存在的目标 ID、无效参数和超出范围的分页参数返回适当的 HTTP 错误响应。
+
+#### Scenario: 查询不存在的目标
+- **WHEN** 客户端请求 `GET /api/targets/999/history`
+- **THEN** 系统 SHALL 返回 404 状态码和错误信息
+
+#### Scenario: 无效的 from/to 参数
+- **WHEN** 客户端请求 `GET /api/targets/1/history?from=invalid`
+- **THEN** 系统 SHALL 返回 400 状态码和错误信息
+
+#### Scenario: 无效的分页参数
+- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&page=abc`
+- **THEN** 系统 SHALL 返回 400 状态码和错误信息
+
+#### Scenario: pageSize 超过上限
+- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&pageSize=201`
+- **THEN** 系统 SHALL 返回 400 状态码和错误信息，提示 pageSize 不能超过 200
+
+#### Scenario: pageSize 等于上限
+- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&pageSize=200`
+- **THEN** 系统 SHALL 正常返回数据
+
+#### Scenario: from 或 to 参数缺失
+- **WHEN** 客户端请求 `GET /api/targets/1/trend` 未提供 from 或 to 参数
+- **THEN** 系统 SHALL 返回 400 状态码和错误信息
+
+#### Scenario: 无效的目标 ID
+- **WHEN** 客户端请求 `GET /api/targets/abc/history`
+- **THEN** 系统 SHALL 返回 400 状态码和错误信息
--- a/openspec/changes/backend-architecture-hardening/specs/probe-config/spec.md
+++ b/openspec/changes/backend-architecture-hardening/specs/probe-config/spec.md
@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: 数据目录路径解析
+配置加载流程 SHALL 将 `server.dataDir` 相对路径基于配置文件所在目录（configDir）解析为绝对路径。绝对路径 SHALL 保持不变。
+
+#### Scenario: dataDir 为相对路径
+- **WHEN** 配置文件位于 `/opt/dial/probes.yaml`，且 `server.dataDir` 配置为 `./data`
+- **THEN** 系统 SHALL 将 dataDir 解析为 `/opt/dial/data`，而非依赖进程 cwd
+
+#### Scenario: dataDir 为绝对路径
+- **WHEN** `server.dataDir` 配置为 `/var/lib/dial/data`
+- **THEN** 系统 SHALL 直接使用该绝对路径，不做额外解析
+
+#### Scenario: dataDir 使用默认值
+- **WHEN** 未配置 `server.dataDir`（使用默认值 `./data`）
+- **THEN** 系统 SHALL 将默认值 `./data` 基于 configDir 解析为绝对路径
--- a/openspec/changes/backend-architecture-hardening/specs/probe-engine/spec.md
+++ b/openspec/changes/backend-architecture-hardening/specs/probe-engine/spec.md
@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: 组内并发拨测
+系统 SHALL 在每次调度 tick 时并发执行同组内目标的检查，但实际同时运行的检查数 MUST 受全局 `runtime.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 个目标且 runtime.maxConcurrentChecks 为 3
+- **THEN** 系统 MUST 同时最多运行 3 个检查，其余检查等待并发槽位释放
--- a/openspec/changes/backend-architecture-hardening/specs/server-bootstrap/spec.md
+++ b/openspec/changes/backend-architecture-hardening/specs/server-bootstrap/spec.md
@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: 统一启动引导函数
+系统 SHALL 提供 `src/server/bootstrap.ts` 导出 `bootstrap(options: BootstrapOptions)` 函数，封装完整的服务启动序列：加载配置、创建 store、同步 targets、创建并启动 engine、启动 HTTP server、注册 shutdown handler。
+
+#### Scenario: 开发模式启动
+- **WHEN** `dev.ts` 调用 `bootstrap({ configPath, mode: "development" })`
+- **THEN** 系统 SHALL 完成完整启动序列，不传入 staticAssets
+
+#### Scenario: 生产模式启动
+- **WHEN** build entry 调用 `bootstrap({ configPath, mode: "production", staticAssets })`
+- **THEN** 系统 SHALL 完成完整启动序列，并将 staticAssets 传递给 startServer
+
+#### Scenario: 启动失败处理
+- **WHEN** 启动过程中任何步骤抛出异常
+- **THEN** 系统 SHALL 输出错误信息并以非零退出码退出进程
+
+#### Scenario: 优雅关机
+- **WHEN** 进程收到 SIGINT 或 SIGTERM 信号
+- **THEN** bootstrap 注册的 shutdown handler SHALL 调用 engine.stop() 和 store.close() 后退出
+
+### Requirement: BootstrapOptions 接口
+`bootstrap` 函数 SHALL 接受 `BootstrapOptions` 参数，包含 `configPath: string`、`mode: RuntimeMode`、`staticAssets?: StaticAssets`。
+
+#### Scenario: 最小配置
+- **WHEN** 仅传入 configPath 和 mode
+- **THEN** 系统 SHALL 正常启动，staticAssets 为 undefined
+
+### Requirement: dev.ts 和 build entry 使用 bootstrap
+`dev.ts` 和 `scripts/build.ts` 生成的 server entry SHALL 调用 `bootstrap()` 而非各自维护启动序列。
+
+#### Scenario: dev.ts 调用 bootstrap
+- **WHEN** 开发者运行 `bun run dev:server`
+- **THEN** `dev.ts` SHALL 调用 `bootstrap` 完成启动
+
+#### Scenario: build entry 调用 bootstrap
+- **WHEN** 生产可执行文件启动
+- **THEN** 生成的 entry SHALL 调用 `bootstrap` 完成启动