ecm_sync_system/docs/factory_registry_refactor_plan.md

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

目标

这次改造只做三件事：

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

当前问题

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

当前 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

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