strepsiadesecm-sync-system
可作为命令行工具运行，也可作为 pip install -e . 的本地可编辑安装库接入其他项目。
1. 项目简介
本项目用于实现异构系统之间的数据推送：将项目侧管理平台的十余种业务数据，稳定推送到集团侧管理平台。
核心复杂点包括：
- 数据接口复杂且会随业务变化。
- 业务之间依赖关系复杂（跨业务、跨阶段）。
- 同业务数据的双侧对应关系判定复杂（绑定/自动绑定）。
- 同步流程各步骤可能出错，系统需要自动处理，必要时允许人工介入。
- 字段多且杂，且可能由不同更新接口共同影响同一业务信息。
2. 项目架构
项目采用：schema 严格约束 + 状态机 + 节点模型 + 分层架构 + 注册式 domain + 数据源与同步系统解耦。
架构详见：
docs/architecture.mddocs/node_state_definition.mddocs/state_machine.md
3. 同步过程简述
整体流程可理解为：
- Pipeline 读取配置并初始化数据源、策略、状态机运行时。
- 加载本地与远端节点，进入绑定/依赖检查/自动绑定阶段。
- 按状态机判定进入 create / update / delete 准备与执行阶段。
- 执行结果回写节点状态并持久化，失败进入可观测、可重试或可人工处理状态。
状态机的作用：
- 把复杂业务规则收敛为可验证、可追踪的事件迁移。
- 保证不变量（invariant）在运行期可检查。
- 统一错误处理路径，避免“隐式分支”造成不一致。
示意图：
docs/state_machine.svg
流程与时序详见：
docs/state_machine.mddocs/sync_flow.md
4. 后续开发（扩展新数据源）
建议路径：
- 在
sync_state_machine/domain/增加业务schema / node / strategy并注册到 DomainRegistry。 - 在
sync_state_machine/datasource/实现新数据源 handler（load/create/update/delete/poll）。 - 参考
run_profiles/preset/模板，在run_profiles/自建对应运行配置，先走 JSONL/Mock 集成测试，再接真实接口。 - 根据业务特性补充状态机上下文字段与测试用例，确保状态迁移可验证。
可参考：
docs/library_integration_guide.md（库化安装、datasource 引用方式、backend 适配方式）sync_state_machine/datasource/README.md（datasource/handler 分层说明）docs/runtime_config_guide.mdtests/README.md
5. 使用方法
运行配置遵循一个约定：
- 跟踪在仓库里的
run_profiles/*.yaml与run_profiles/preset/*.default.yaml只写必要的覆盖项。 - pipeline 启动时会打印并写入一份 Resolved Full Config，把省略的默认值全部补齐，便于排障和审阅。
- 字段含义与全量示例见：
docs/runtime_config_guide.md
JSONL 同步
- 已安装命令行入口：
ecm-sync-run --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml - 仓库内直接运行：
python run.py --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 - 自定义配置：从
run_profiles/preset/复制一份到run_profiles/*.local.yaml，只改有差异的字段即可。
API 同步
- 已安装命令行入口：
ecm-sync-run --config_path=run_profiles/preset/jsonl_to_api.default.yaml - 仓库内直接运行：
python run.py --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/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/。