进一步清理代码和注册过程

docs/library_integration_guide.md

@@ -11,7 +11,7 @@
 推荐接入方式：
 
 - `sync_state_machine` 负责同步引擎、状态机、pipeline、datasource 抽象。
-- 业务系统负责提供自己的数据源适配层，不要反向让 `sync_state_machine` 依赖业务系统。
+- 业务系统负责提供自己的 datasource / handler 适配层，不要反向让 `sync_state_machine` 依赖业务系统。
 
 ---
 
@@ -46,13 +46,18 @@ ecm-sync-run --config_path=run_profiles/preset/jsonl_to_api.default.yaml
 
 - `sync_state_machine.build_config`
 - `sync_state_machine.build_default_config`
-- `sync_state_machine.run_pipeline_from_config`
 - `sync_state_machine.create_pipeline_from_config`
+- `sync_state_machine.build_config_from_file`
 - `sync_state_machine.PipelineRunConfig`
 - `sync_state_machine.JsonlDataSourceConfig`
 - `sync_state_machine.ApiDataSourceConfig`
 - `sync_state_machine.DomainRegistry`
 
+配置加载分两步：
+
+1. 先构造或读取 `PipelineRunConfig`
+2. 再交给 `create_pipeline_from_config()` 创建 pipeline
+
 内置 domain 注册会在导入包时自动完成。
 
 ---
@@ -200,7 +205,7 @@ class DemoJsonlHandler(BaseJsonlHandler):
 
 ---
 
-### 6.2 如果 backend 是数据库：建议写“数据库 handler / adapter”，不要让引擎直接依赖 ORM
+### 6.2 如果 backend 是数据库：建议写 handler / adapter，不要让引擎直接依赖 ORM
 
 推荐结构：
 
@@ -234,6 +239,7 @@ backend/
 
 - 不要在 `sync_state_machine` 包里 import backend 的 model/repository
 - 不要让 `DomainRegistry` 注册逻辑散落在 backend 业务层之外
+- 不要在 datasource 之外做额外的 project 过滤；`target_project_ids` 只应由 datasource 自己解释
 
 ---
 
@@ -268,6 +274,7 @@ backend/
 - `strategy_class`
 - `jsonl_handler_class`
 - `api_handler_class`
+- 以及任意通过 `register_handler()` 追加的 datasource handler
 
 示例：
 
@@ -282,9 +289,11 @@ DomainRegistry.register(
     jsonl_handler_class=DemoJsonlHandler,
     api_handler_class=DemoApiHandler,
 )
+
+DomainRegistry.register_handler("demo", "custom_remote", DemoCustomHandler)
 ```
 
-如果是 backend 接入，建议在 backend 的 integration 启动阶段集中注册，而不是分散在 controller / service 里。
+如果是 backend 接入，建议在启动入口集中注册，而不是分散在 controller / service 里。
 
 ---
 
@@ -320,7 +329,7 @@ async def run_demo_sync() -> None:
     await pipeline.run()
 ```
 
-如果 backend 自己提供本地数据库数据，不要把 backend model 直接灌进 pipeline；先经过 handler / mapper 转成 schema 再进入引擎。
+      如果 backend 自己提供本地数据库数据，不要把 backend model 直接灌进 pipeline；先经过 handler / mapper 转成 schema 再进入引擎。
 
 ---
 
@@ -353,8 +362,9 @@ async def run_demo_sync() -> None:
 ## 11. 相关文件
 
 - 包入口：[sync_state_machine/__init__.py](../sync_state_machine/__init__.py)
-- CLI：[sync_state_machine/cli.py](../sync_state_machine/cli.py)
+- CLI / 运行入口：[sync_state_machine/cli.py](../sync_state_machine/cli.py)
 - 配置工厂：[sync_state_machine/config](../sync_state_machine/config)
 - datasource 基础层：[sync_state_machine/datasource](../sync_state_machine/datasource)
 - pipeline 工厂：[sync_state_machine/pipeline/factory.py](../sync_state_machine/pipeline/factory.py)
-- domain 注册：[sync_state_machine/common/registry.py](../sync_state_machine/common/registry.py)
+- domain 注册：[sync_state_machine/common/registry.py](../sync_state_machine/common/registry.py)
+- backend 集成入口：[backend/app/thirdparty/ecm_sync/services/sync_runner.py](../backend/app/thirdparty/ecm_sync/services/sync_runner.py)