# Factory / Registry / Adapter 初始化流程改造方案

## 目标

这次改造只做三件事：

1. 简化 `factory`，让它只负责编排，不再关心过多介质细节。
2. 统一 handler 初始化流程，让 `jsonl` / `db` / `api` 三类路径走同一套装配逻辑。
3. 让适配层尽量极简：适配层只补充少量 handler / datasource 实现，不再复制初始化流程。

## 当前问题

### 1. `factory` 里存在大量按类型分支的重复逻辑

当前 [sync_state_machine/pipeline/factory.py](sync_state_machine/pipeline/factory.py) 同时负责：

- 创建 local / remote datasource
- 判断 datasource 类型
- 选择不同 handler getter
- 注入一部分 handler 配置
- 注册 handler

这些逻辑对 local / remote 各写了一遍，重复明显。

### 2. `DomainRegistry` 暴露了过多介质细节

当前 registry 暴露：

- `get_jsonl_handler()`
- `get_db_handler()`
- `get_api_handler()`

这导致编排层必须知道 handler 是哪一类，从而在 `factory` 里出现大量 `if isinstance(...)`。

### 3. handler 配置注入不统一

目前只有 API handler 在 factory 里显式吃到了 `handler_configs`。

- `api`：支持 per-side 配置
- `db`：当前没有统一注入入口
- `jsonl`：当前也没有统一注入入口

这使得“同一类 datasource，两侧配置不同”只能在部分路径下工作。

### 4. 适配层初始化成本偏高

如果适配层要补充一种 handler，目前需要理解：

- factory 的类型分支
- registry 的不同 getter
- 某些配置为什么只在 API 生效

这和“适配层极简”的目标不一致。

## 本次改造范围

本次只做最小闭环改造，不碰更大的业务逻辑：

### Step 1. 统一 `DomainRegistry` 的 handler 查询接口

状态：已完成

新增统一接口：

- `get_handler(node_type, datasource_type)`

保留旧接口作为兼容壳，但 factory 新逻辑只使用统一接口。

### Step 2. 给所有 handler 基类增加统一配置注入入口

状态：已完成

新增统一入口：

- `set_handler_config(config)`

这样 `jsonl` / `db` / `api` 三类 handler 都可以在实例化后走同一套配置注入流程。

### Step 3. 重写 factory 的 datasource / handler 初始化流程

状态：已完成

把当前分散的：

- `_create_datasources()`
- `_register_handlers()`
- `_api_handler_kwargs()`

收敛成按 endpoint 的统一初始化流程：

- endpoint 创建 datasource
- endpoint 根据 datasource type 向 registry 查询 handler class
- endpoint 创建 handler
- endpoint 统一注入：
  - `handler_config`
  - datasource-specific runtime object（如 api client）

最终让 `factory` 只负责：

- persistence 初始化
- endpoint 初始化
- strategy 初始化
- pipeline 组装

## 不在本次范围内

以下内容先不动，只在文档中记为后续方向：

1. 显式 bootstrap 内建 domain 与适配层 domain 的注册时机
2. 用更强的 `EndpointConfig` / `DataSourceDriver` 抽象进一步收敛 factory
3. 清理 `NodeHandlerRegistry` 这类历史遗留接口

## 测试策略

每一步都补对应 pytest，并保证通过：

### Step 1 测试

- registry 可以通过统一接口拿到对应 handler class
- 旧接口仍可兼容使用

### Step 2 测试

- handler 可以收到统一的 `handler_config`
- 同一 datasource 类型在 local / remote 两侧可以拿到不同配置

### Step 3 测试

- factory 不再依赖 `get_jsonl_handler/get_db_handler/get_api_handler`
- 统一 endpoint 初始化路径可正常创建并注册 handler
- 原有 db handler 注册测试仍通过

## 预期结果

改造完成后：

1. `factory` 中关于 datasource / handler 初始化的重复逻辑显著减少。
2. `DomainRegistry` 对编排层只暴露统一 handler 查询方式。
3. handler 配置注入完全统一。
4. 适配层只需：
   - 提供 datasource（如需要）
   - 提供 handler
   - 注册 handler
   - 调用统一 runner

这就是“适配极简”的基础。