DiAL/openspec/changes/backend-architecture-hardening/design.md

Context

DiAL 后端是基于 Bun 的拨测服务，当前有 2 个 checker 类型（http、command），target 规模预计增长到 100，checker 类型预计超过 5 种。

现状问题：

1. GET /api/targets 对每个 target 单独查询 getRecentSamples，产生 N+3 次 SQL 查询
2. ProbeEngine.probeGroup 中 rejected 结果仅 console.warn，前端无法感知异常
3. dev.ts 和 scripts/build.ts 生成的 entry 各自维护相同的启动序列
4. config-loader.ts 中 dataDir 未基于 configDir 解析，相对路径依赖进程 cwd
5. validatePagination 无 pageSize 上限，可被滥用
6. CheckerDefinition 接口方法参数为 ResolvedTargetBase，checker 内部需手动 as 断言

Goals / Non-Goals

Goals:

• 消除 targets 路由的 N+1 查询，支撑 100 target 规模
• Engine 异常可观测：rejected 结果写入数据库，前端可见
• 启动逻辑单一来源，降低维护成本
• 修复 dataDir 路径解析 bug
• API 防御性：pageSize 上限
• CheckerDefinition 泛型化，checker 开发者获得编译期类型安全

Non-Goals:

• 不做配置热更新
• 不做 API 认证/鉴权
• 不做通知/告警系统
• 不改变 ResolvedTargetBase 的 index signature（registry 层仍用类型擦除）
• 不改变前端行为

Decisions

Decision 1: 批量查询 recentSamples 使用 window function

选择：在 ProbeStore 中新增 getAllRecentSamples(limit: number) 方法，使用 SQLite window function ROW_NUMBER() OVER (PARTITION BY target_id ORDER BY timestamp DESC) 一次查询所有 target 的最近 N 条采样。

替代方案：

• UNION ALL 拼接每个 target 的子查询 → SQL 长度随 target 数线性增长，不可控
• 应用层批量（一次查全部再内存分组）→ 数据量大时内存开销高

理由：window function 是 SQLite 3.25+ 原生支持的特性，Bun 内置的 SQLite 版本满足要求。单次查询，SQL 固定长度，性能最优。

Decision 2: Engine rejected 写入 internal error 记录

选择：在 probeGroup 中，对 rejected 的结果构造一条 matched: false、failure: { kind: "error", phase: "internal", path: "engine", message: reason } 的 check_result 写入 store。

替代方案：

• 单独的错误日志表 → 增加 schema 复杂度，前端需要额外查询
• 仅保留 console.warn → 现状，不可观测

理由：复用现有 check_results 表和 failure 结构，前端无需改动即可展示异常状态。phase: "internal" 区分于正常的 checker 执行失败。通过 Promise.allSettled 的索引关联回 target 数组，确保能获取 targetName。

Decision 3: 抽取 bootstrap.ts

选择：新增 src/server/bootstrap.ts，导出 bootstrap(options: BootstrapOptions) 函数，封装完整启动序列：loadConfig → ProbeStore → syncTargets → ProbeEngine → startServer → 注册 shutdown handler。

接口设计：

interface BootstrapOptions {
  configPath: string;
  mode: RuntimeMode;
  staticAssets?: StaticAssets;
}

dev.ts 调用 bootstrap({ configPath, mode: "development" })。 build.ts 生成的 entry 调用 bootstrap({ configPath, mode: "production", staticAssets })。

替代方案：

• 保持两处重复 → 维护负担随启动逻辑复杂化线性增长

Decision 4: dataDir 基于 configDir 解析

选择：在 config-loader.ts 的 loadConfig 中，对 dataDir 使用 resolve(configDir, dataDir) 处理。如果 dataDir 是绝对路径，resolve 会直接返回绝对路径，不影响绝对路径用户。

影响：行为变更——之前相对路径基于 cwd，现在基于配置文件目录。由于项目未上线，无需向前兼容。

Decision 5: pageSize 上限 200

选择：在 middleware.ts 的 validatePagination 中增加 pageSize > 200 的校验，返回 400。

常量定义：MAX_PAGE_SIZE = 200，定义在 middleware.ts 中。

理由：200 条/页对于拨测历史记录的展示场景足够。前端当前使用 20，不受影响。

Decision 6: CheckerDefinition 泛型化

选择：

interface CheckerDefinition<TResolved extends ResolvedTargetBase = ResolvedTargetBase> {
  execute(target: TResolved, ctx: CheckerContext): Promise<CheckResult>;
  resolve(target: RawTargetConfig, context: ResolveContext): TResolved;
  serialize(target: TResolved): { config: string; target: string };
  validate(input: CheckerValidationInput): ConfigValidationIssue[];
  readonly configKey: string;
  readonly schemas: CheckerSchemas;
  readonly type: string;
}

• 默认泛型参数 = ResolvedTargetBase 保证 registry 等中间层无需指定泛型
• CheckerRegistry 内部存储 CheckerDefinition<ResolvedTargetBase>（类型擦除）
• 各 checker 实现 implements CheckerDefinition<ResolvedHttpTarget> 等具体类型
• checker 内部 execute、serialize 方法直接接收具体类型，无需 as 断言

替代方案：

• Discriminated union → 每加 checker 改 union，违背插件化设计
• 维持现状 → 5+ checker 时 as 断言散落各处

影响范围：

• runner/types.ts：接口加泛型参数
• runner/registry.ts：内部 Map 类型为 CheckerDefinition（使用默认参数）
• http/execute.ts、command/execute.ts：implements CheckerDefinition<具体类型>，移除方法内的 as 断言
• engine.ts、config-loader.ts、store.ts：不变（依赖 base interface）

Risks / Trade-offs

• window function 兼容性 → Bun 内置 SQLite >= 3.25，已验证支持。如果未来需要外部 SQLite，需确认版本。
• Engine rejected 写入依赖索引关联 → 通过 Promise.allSettled 的索引关联回 target 数组获取 targetName。前提是 probeGroup 的 targets 数组与 Promise.allSettled 结果数组保持一一对应，当前实现满足此条件。
• bootstrap.ts 增加一层间接 → 启动流程从 2 处直接代码变为 1 处函数调用。复杂度不增加，只是位置移动。
• 泛型擦除在 registry 层 → registry.get() 返回 CheckerDefinition（base 类型），engine 调用时仍是 base 类型。这是设计意图：中间层不感知具体 checker 类型。