ecm_sync_system/docs/getting_started.md

快速上手

这份文档只服务第一次接手 ecm_sync_system 的开发者。目标不是完整讲架构，而是让你先跑起来、知道从哪里入手，再去看更细的说明。

1. 先做什么

第一次进入仓库时，建议按下面顺序执行：

1. 准备 Python 3.9+。
2. 在仓库根目录创建并激活虚拟环境。
3. 执行 pip install -e . 安装当前项目。
4. 跑状态机配置校验，确认基础工具链正常。
5. 跑一条轻量测试，确认测试与渲染工具链可用。
6. 再去看架构文档和状态机文档。

推荐命令：

python -m venv .venv
source .venv/bin/activate
pip install -e .
python run.py --help
python tools/validate_config.py --config sync_state_machine/config/node_state_machine.yaml
pytest tests/integration/test_toolchain_config_and_graph.py -q

2. 仓库里最重要的目录

• sync_state_machine/
  • 真正的引擎实现目录。大多数“核心代码入口”都在这里。
• run_profiles/
  • 运行配置与模板。
• tests/
  • 单元测试与集成测试。
• tools/
  • 状态机校验、图渲染、远程环境等工具。
• scripts/
  • 自动化测试编排和数据集相关脚本。
• docs/
  • 面向开发者的设计、运行和排障文档。

3. 先读哪几篇文档

按任务来看：

• 想知道系统整体怎么分层：docs/architecture.md
• 想知道状态机怎么工作：docs/node_state_definition.md 和 docs/state_machine.md
• 想知道一次同步是怎么跑的：docs/sync_flow.md
• 想调运行配置：docs/runtime_config_guide.md（包含单项目、多项目、persist.url、sqlalchemy、业务侧注册 datasource 的当前写法）
• 想接新 datasource 或 handler：sync_state_machine/datasource/README.md 和 docs/library_integration_guide.md
• 想看测试体系：docs/testing_guide.md 和 tests/README.md
• 想做排障：docs/operations.md

4. 新人最容易踩的坑

4.1 先用仓库入口，不要默认 shell 里已经有命令

如果你还没执行过 pip install -e .，那么 ecm-sync-run 不一定可用。

首次调试建议优先用：

python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml

安装完成后，再切换到：

ecm-sync-run --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml

4.2 核心实现路径以 sync_state_machine/ 为准

阅读历史文档时，如果看到类似下面的写法：

• pipeline/full_sync_pipeline.py
• sync_system/strategy.py
• datasource/datasource.py
• engine/events.py

请优先理解为它们在当前仓库中的真实位置分别是：

• sync_state_machine/pipeline/full_sync_pipeline.py
• sync_state_machine/sync_system/strategy.py
• sync_state_machine/datasource/datasource.py
• sync_state_machine/engine/events.py

5. 如果你要开始改代码

5.1 改 domain 行为

优先查看：

• sync_state_machine/domain/<node_type>/
• sync_state_machine/sync_system/strategy_ops/
• tests/unit/ 中对应测试

5.2 改状态机语义

优先查看：

• sync_state_machine/config/node_state_machine.yaml
• sync_state_machine/engine/events.py
• sync_state_machine/engine/state_apply.py

改完建议至少执行：

python tools/validate_config.py --config sync_state_machine/config/node_state_machine.yaml
pytest tests/integration/test_toolchain_config_and_graph.py -q

5.3 改运行配置或 datasource

优先查看：

• docs/runtime_config_guide.md
• run_profiles/README.md
• sync_state_machine/datasource/README.md

6. 出错先看哪里

推荐排查顺序：

1. 先看运行日志中的 Resolved Full Config。
2. 再看节点 sync_log / status / error。
3. 再对照 docs/operations.md 和 docs/state_machine.md。
4. 如果是配置问题，先让校验报错，不要绕过 schema 或状态机校验。