ecm_sync_system/sync_state_machine/datasource

DataSource 接入说明

本文档说明当前 sync_state_machine.datasource 层的职责边界，以及新增 datasource / handler 时应如何接入。

如需看完整库化接入方式，优先参考 docs/library_integration_guide.md。

1. 分层模型

当前 datasource 层分为两部分：

1. DataSource

   • 管理 handler 注册
   • 管理 collection 注入
   • 负责按 node_type 组织 load_all() / sync_all()
   • 汇总并回写 TaskResult

2. Handler

   • 负责某一个 node_type 的具体 I/O
   • 负责把原始数据转成 SyncNode
   • 负责执行 create / update / delete / poll

设计原则：

• datasource 不承载业务策略
• strategy 不直接做底层 I/O
• 节点类型差异下沉到 handler

---

2. 当前可直接复用的 datasource

2.1 JSONL

• JsonlDataSource
• BaseJsonlHandler

适合：

• fixture
• 本地回放
• 离线调试

2.2 API

• ApiDataSource
• ApiClient
• BaseApiHandler

适合：

• HTTP 推送
• 异步任务轮询
• 远端系统对接

---

3. 最推荐的扩展方式：只新增 handler

多数情况下，不需要新增新的 datasource 类。

推荐做法：

1. 复用现有 JsonlDataSource 或 ApiDataSource
2. 为你的 node_type 新增 handler
3. 在 handler 中完成字段映射、加载、写入和轮询
4. 将 handler 注册到 DomainRegistry

这样可以保持：

• pipeline 不变
• datasource 生命周期不变
• 策略层不感知底层来源

---

4. handler 需要实现什么

4.1 JSONL handler

通常继承 BaseJsonlHandler：

class DemoJsonlHandler(BaseJsonlHandler):
    def __init__(self, datasource):
        super().__init__(
            datasource=datasource,
            node_type="demo",
            node_class=DemoSyncNode,
            schema=DemoSchema,
        )

4.2 API handler

通常继承 BaseApiHandler，实现：

• load()
• create_all()
• update_all()
• delete_all()
• poll_tasks()

并按需要补充：

• extract_created_id()
• get_update_fields()
• 依赖节点 context 读取逻辑

---

5. 什么时候新增 DataSource 类

只有在现有 JSONL / API 模型都不匹配时，才建议新增 BaseDataSource 子类。

例如：

• 数据来自数据库快照
• 数据来自 MQ / Kafka
• 数据来自特殊 RPC 或 SDK

即便新增 datasource，也建议保留同样的职责边界：

• datasource 负责调度
• handler 负责节点类型差异

---

6. 注册方式

接入新 node_type 时，最终仍通过 DomainRegistry 暴露给 pipeline：

DomainRegistry.register(
    node_type="demo",
    schema=DemoSchema,
    node_class=DemoSyncNode,
    strategy_class=DemoStrategy,
    jsonl_handler_class=DemoJsonlHandler,
    api_handler_class=DemoApiHandler,
)

---

7. 推荐阅读顺序

1. docs/library_integration_guide.md
2. sync_state_machine/datasource/handler.py
3. sync_state_machine/datasource/api/handler.py
4. sync_state_machine/datasource/jsonl/handler.py
5. sync_state_machine/pipeline/factory.py

---

8. 结论

如果你在接入新系统，优先判断：

• 是否可以直接复用 JsonlDataSource / ApiDataSource
• 是否只需要新增 handler
• 是否需要在业务系统侧做 mapper / adapter

通常情况下，先写 handler，而不是先写新的 datasource。