3.0 KiB
3.0 KiB
MODIFIED Requirements
Requirement: Checker 接口定义
系统 SHALL 在 src/server/checker/runner/types.ts 中定义面向扩展的泛型 CheckerDefinition<TResolved extends ResolvedTargetBase = ResolvedTargetBase>，包含 type、configKey、TypeBox 配置契约、启动期语义校验、resolve、execute、serialize、buildDetail 成员。泛型参数 SHALL 约束 execute 和 serialize 方法的 target 参数类型，使 checker 实现内部获得编译期类型安全。默认泛型参数 = ResolvedTargetBase 保证中间层（registry、engine、config-loader）无需指定泛型。
Scenario: Checker 接口包含必要方法
- WHEN 开发者实现一个新的 Checker
- THEN 该实现 MUST 提供
type（字符串标识）、configKey（配置分组名）、TypeBox 配置契约、启动期语义校验、resolve(target, context)（解析配置并填充默认值）、execute(target, ctx)（执行探测返回 CheckResult）、serialize(target)（返回 target 展示文本和 config JSON）和buildDetail(observation)（从 observation 构造人可读摘要）
Scenario: CheckerContext 注入 signal
- WHEN 引擎调用
checker.execute(target, ctx) - THEN
ctx.signalSHALL 是一个由引擎创建的AbortSignal，在超时或引擎关闭时 abort
Scenario: resolve 不承担通用契约校验
- WHEN config-loader 调用 checker.resolve()
- THEN checker.resolve() SHALL 假定配置已经通过 TypeBox/Ajv 契约校验和启动期语义校验，只负责默认值填充、路径解析和领域配置转换
Scenario: type 与 configKey 默认一致
- WHEN checker 定义
type: "tcp" - THEN checker 的
configKeySHALL 默认使用"tcp"，对应 target 的tcp分组和 defaults.tcp 分组
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>），实现类型擦除
Scenario: buildDetail 方法签名
- WHEN 开发者实现 buildDetail 方法
- THEN 方法签名 SHALL 为
buildDetail(observation: Record<string, unknown>): string | null，接收 observation 对象并返回人可读摘要字符串或 null
Scenario: buildDetail 由 API 层调用
- WHEN API 序列化 CheckResult
- THEN API 层 SHALL 通过 registry 获取对应 checker 并调用 buildDetail，而非由 execute 方法直接生成 detail