strepsiades
165 lines
7.4 KiB
Markdown
165 lines
7.4 KiB
Markdown
# ecm-sync-system
|
||
|
||
可作为命令行工具运行，也可作为 `pip install -e .` 的本地可编辑安装库接入其他项目。
|
||
|
||
## 0. 10 分钟上手
|
||
|
||
如果你是第一次进入这个仓库，先不要从所有文档开始读，先确认环境和最小工具链可用。
|
||
|
||
推荐顺序：
|
||
1. 准备 Python 3.9+ 环境（当前仓库已在 `pyproject.toml` 中声明 `requires-python >= 3.9`）。
|
||
2. 在仓库根目录创建并激活虚拟环境。
|
||
3. 以可编辑模式安装本项目。
|
||
4. 先跑配置校验，再跑一个轻量集成测试，确认本地环境可用。
|
||
5. 只在确认入口可运行后，再去看架构与状态机文档。
|
||
|
||
最小命令链：
|
||
|
||
```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
|
||
```
|
||
|
||
如果你只是想直接运行仓库内现成配置，优先用仓库入口：
|
||
|
||
```bash
|
||
python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
|
||
```
|
||
|
||
如果你已经完成 `pip install -e .`，也可以使用安装后的命令行入口：
|
||
|
||
```bash
|
||
ecm-sync-run --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
|
||
```
|
||
|
||
面向第一次接触仓库的更完整说明见：`docs/getting_started.md`
|
||
|
||
## 1. 项目简介
|
||
|
||
本项目用于实现异构系统之间的数据推送：将项目侧管理平台的十余种业务数据，稳定推送到集团侧管理平台。
|
||
|
||
核心复杂点包括：
|
||
- 数据接口复杂且会随业务变化。
|
||
- 业务之间依赖关系复杂（跨业务、跨阶段）。
|
||
- 同业务数据的双侧对应关系判定复杂（绑定/自动绑定）。
|
||
- 同步流程各步骤可能出错，系统需要自动处理，必要时允许人工介入。
|
||
- 字段多且杂，且可能由不同更新接口共同影响同一业务信息。
|
||
|
||
## 2. 项目架构
|
||
|
||
项目采用：`schema` 严格约束 + 状态机 + 节点模型 + 分层架构 + 注册式 `domain` + 数据源与同步系统解耦。
|
||
|
||
架构详见：
|
||
- `docs/getting_started.md`
|
||
- `docs/architecture.md`
|
||
- `docs/node_state_definition.md`
|
||
- `docs/state_machine.md`
|
||
|
||
## 3. 同步过程简述
|
||
|
||
整体流程可理解为：
|
||
1. Pipeline 读取配置并初始化数据源、策略、状态机运行时。
|
||
2. 加载本地与远端节点，进入绑定/依赖检查/自动绑定阶段。
|
||
3. 按状态机判定进入 create / update / delete 准备与执行阶段。
|
||
4. 执行结果回写节点状态并持久化，失败进入可观测、可重试或可人工处理状态。
|
||
|
||
状态机的作用：
|
||
- 把复杂业务规则收敛为可验证、可追踪的事件迁移。
|
||
- 保证不变量（invariant）在运行期可检查。
|
||
- 统一错误处理路径，避免“隐式分支”造成不一致。
|
||
|
||
示意图：
|
||
- `docs/state_machine.svg`
|
||
|
||
流程与时序详见：
|
||
- `docs/state_machine.md`
|
||
- `docs/sync_flow.md`
|
||
|
||
## 4. 后续开发（扩展新数据源）
|
||
|
||
建议路径：
|
||
1. 在 `sync_state_machine/domain/` 增加业务 `schema / node / strategy` 并注册到 DomainRegistry。
|
||
2. 在 `sync_state_machine/datasource/` 实现新数据源 handler（load/create/update/delete/poll）。
|
||
3. 参考 `run_profiles/preset/` 模板，在 `run_profiles/` 自建对应运行配置，先走 JSONL/Mock 集成测试，再接真实接口。
|
||
4. 根据业务特性补充状态机上下文字段与测试用例，确保状态迁移可验证。
|
||
|
||
可参考：
|
||
- `docs/library_integration_guide.md`（库化安装、datasource 引用方式、backend 适配方式）
|
||
- `sync_state_machine/datasource/README.md`（datasource/handler 分层说明）
|
||
- `docs/runtime_config_guide.md`
|
||
- `tests/README.md`
|
||
|
||
## 5. 使用方法
|
||
|
||
先区分两种常见使用方式：
|
||
- 仓库内开发与调试：优先使用 `python run.py ...`，因为它不依赖 shell 中已经存在 `ecm-sync-run`。
|
||
- 作为库或已安装命令使用：先执行 `pip install -e .`，再使用 `ecm-sync-run ...`。
|
||
|
||
运行配置遵循一个约定：
|
||
- 跟踪在仓库里的 `run_profiles/*.yaml` 与 `run_profiles/preset/*.default.yaml` 只写必要的覆盖项。
|
||
- pipeline 启动时会打印并写入一份 **Resolved Full Config**，把省略的默认值全部补齐，便于排障和审阅。
|
||
- 字段含义与全量示例见：`docs/runtime_config_guide.md`
|
||
|
||
### JSONL 同步
|
||
- 仓库内直接运行：`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`
|
||
- 多项目 JSONL 示例：`python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.multi_project.default.yaml`
|
||
- 当前已经支持多 project 运行；标准写法是直接使用多项目编排配置文件，或在支持 implicit multi-project 的 profile 中由配置本身决定运行模式。
|
||
- 自定义配置：从 `run_profiles/preset/` 复制一份到 `run_profiles/*.local.yaml`，只改有差异的字段即可。
|
||
|
||
### API 同步
|
||
- 仓库内直接运行：`python run.py --config_path=run_profiles/preset/jsonl_to_api.default.yaml`
|
||
- 已安装命令行入口：`ecm-sync-run --config_path=run_profiles/preset/jsonl_to_api.default.yaml`
|
||
- 如果是单项目联调，优先参考仓库内现成示例：`run_profiles/jsonl_to_api.yaml`
|
||
|
||
### 库模式使用
|
||
- 本地可编辑安装：`pip install -e .`
|
||
- 接入说明：`docs/library_integration_guide.md`
|
||
|
||
### 配置与校验
|
||
- 模板配置：`run_profiles/preset/*.default.yaml`
|
||
- 建议先跑 default，再在 `run_profiles/*.local.yaml` 做覆盖（该目录 YAML 已默认忽略）
|
||
- 跟踪中的模板与示例配置都采用“只写必要字段”的风格；启动日志里的 `Resolved Full Config` 才是最终生效配置。
|
||
- 状态机配置校验：`python tools/validate_config.py --config sync_state_machine/config/node_state_machine.yaml`
|
||
- 状态机图生成：`python tools/render_graph.py --format mermaid --out docs/state_machine.mmd`
|
||
|
||
### 测试
|
||
- 全量：`pytest tests -q`
|
||
- 说明：`tests/README.md`
|
||
- 远程环境初始化工具：`python tools/remote_env.py --config tools/remote_env.example.yaml init|run|stop|clear`
|
||
- 测试总览：`docs/testing_guide.md`
|
||
|
||
### 其他工具
|
||
- UI 调试：`python -m ui.main --host 127.0.0.1 --port 8765`
|
||
- 运维与排障：`docs/operations.md`
|
||
- 远程测试环境：`tools/remote_env.py`
|
||
- 脚本化回归与数据集构建：`scripts/README.md`
|
||
|
||
## 文档导航
|
||
|
||
如果你是按任务查文档，建议按下面的顺序进入：
|
||
- 第一次接手仓库：`docs/getting_started.md`
|
||
- 想理解整体分层：`docs/architecture.md`
|
||
- 想理解状态与迁移：`docs/node_state_definition.md` + `docs/state_machine.md`
|
||
- 想调运行配置：`docs/runtime_config_guide.md` + `run_profiles/README.md`（包含多项目配置写法）
|
||
- 想接新数据源或改 handler：`sync_state_machine/datasource/README.md` + `docs/library_integration_guide.md`
|
||
- 想排障：`docs/operations.md`
|
||
- 想补测试或跑联调：`docs/testing_guide.md` + `tests/README.md`
|
||
|
||
- 新人上手：`docs/getting_started.md`
|
||
- 总体架构：`docs/architecture.md`
|
||
- 状态定义：`docs/node_state_definition.md`
|
||
- 状态机规则：`docs/state_machine.md`
|
||
- 同步流程：`docs/sync_flow.md`
|
||
- 运行配置：`docs/runtime_config_guide.md`
|
||
- 库化与接入：`docs/library_integration_guide.md`
|
||
- Collection 查询与升级：`docs/collection_query_and_upgrade_plan.md`
|
||
- 运维迭代：`docs/operations.md`
|
||
- 测试指南：`docs/testing_guide.md`
|
||
|
||
历史资料已归档到 `docs/archive/`。
|