# DataSource 接入说明

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

如需看完整库化接入方式，优先参考 [docs/library_integration_guide.md](../../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`：

```python
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：

```python
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](../../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**。