整理配置和代码入口，增加部分测试。

docs/factory_registry_refactor_plan.md

@@ -0,0 +1,147 @@
+# 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`
+  - `target_project_ids`
+  - 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
+
+这就是“适配极简”的基础。