# 快速上手

这份文档只服务第一次接手 `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 或状态机校验。