更新文档

2026-03-25 10:32:50 +08:00
parent 67370657db
commit 4b81b83fd8
5 changed files with 208 additions and 29 deletions
@@ -0,0 +1,128 @@
+# 快速上手
+
+这份文档只服务第一次接手 `ecm_sync_system` 的开发者。目标不是完整讲架构，而是让你先跑起来、知道从哪里入手，再去看更细的说明。
+
+## 1. 先做什么
+
+第一次进入仓库时，建议按下面顺序执行：
+
+1. 准备 Python 3.9+。
+2. 在仓库根目录创建并激活虚拟环境。
+3. 执行 `pip install -e .` 安装当前项目。
+4. 跑状态机配置校验，确认基础工具链正常。
+5. 跑一条轻量测试，确认测试与渲染工具链可用。
+6. 再去看架构文档和状态机文档。
+
+推荐命令：
+
+```bash
+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`
+- 想接新 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` 不一定可用。
+
+首次调试建议优先用：
+
+```bash
+python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
+```
+
+安装完成后，再切换到：
+
+```bash
+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`
+
+改完建议至少执行：
+
+```bash
+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 或状态机校验。