chore: 归档 backend-architecture-hardening 变更并同步 delta spec 到主 spec

openspec/specs/checker-runner-abstraction/spec.md

@@ -50,7 +50,7 @@
 - **THEN** checker SHALL 返回 `ConfigValidationIssue`，而不是直接抛出最终用户错误字符串
 
 ### Requirement: Checker 接口定义
-系统 SHALL 在 `src/server/checker/runner/types.ts` 中定义面向扩展的 `CheckerDefinition`，包含 `type`、`configKey`、TypeBox 配置契约、启动期语义校验、`resolve`、`execute`、`serialize` 成员。`CheckerContext` SHALL 包含引擎注入的 `AbortSignal`。接口方法的参数和返回值 SHALL 使用 base interface 类型（`RawTargetConfig`、`ResolvedTargetBase`），各 checker 实现内部自行 narrow 到具体类型。
+系统 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
@@ -68,20 +68,24 @@
 - **WHEN** checker 定义 `type: "tcp"`
 - **THEN** checker 的 `configKey` SHALL 默认使用 `"tcp"`，对应 target 的 `tcp` 分组和 defaults.tcp 分组
 
-#### Scenario: 接口方法使用 base 类型
-- **WHEN** 开发者查看 `CheckerDefinition` 接口签名
-- **THEN** `resolve` 的参数 SHALL 为 `RawTargetConfig`，返回值 SHALL 为 `ResolvedTargetBase`；`execute` 的参数 SHALL 为 `ResolvedTargetBase`；`serialize` 的参数 SHALL 为 `ResolvedTargetBase`
+#### Scenario: 接口方法使用泛型约束
+- **WHEN** 开发者查看 `CheckerDefinition<TResolved>` 接口签名
+- **THEN** `resolve` 的返回值 SHALL 为 `TResolved`；`execute` 的参数 SHALL 为 `TResolved`；`serialize` 的参数 SHALL 为 `TResolved`
 
-#### Scenario: checker 实现内部 narrow
-- **WHEN** HttpChecker 的 execute 方法接收 `ResolvedTargetBase` 参数
-- **THEN** 方法内部 SHALL 将参数 narrow 为 `ResolvedHttpTarget`（通过 type assertion），然后使用具体类型的字段
+#### 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 抛出错误。
+系统 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 实例
+- **THEN** 返回的 SHALL 是之前注册的 HttpChecker 实例（类型为 `CheckerDefinition`）
 
 #### Scenario: 获取未注册的 type
 - **WHEN** 调用 `registry.get("unknown")` 且未注册对应 type 的 checker