test_push_system

1. 项目简介

本项目用于实现异构系统之间的数据推送：将项目侧管理平台的十余种业务数据，稳定推送到集团侧管理平台。

核心复杂点包括：

• 数据接口复杂且会随业务变化。
• 业务之间依赖关系复杂（跨业务、跨阶段）。
• 同业务数据的双侧对应关系判定复杂（绑定/自动绑定）。
• 同步流程各步骤可能出错，系统需要自动处理，必要时允许人工介入。
• 字段多且杂，且可能由不同更新接口共同影响同一业务信息。

2. 项目架构

项目采用：schema 严格约束 + 状态机 + 节点模型 + 分层架构 + 注册式 domain + 数据源与同步系统解耦。

架构详见：

• 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. 根据业务特性补充状态机上下文字段与测试用例，确保状态迁移可验证。

可参考：

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

5. 使用方法

JSONL 同步

• 基线配置（优先）：python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
• 使用自定义配置：先从 run_profiles/preset/jsonl_to_jsonl.default.yaml 复制到 run_profiles/jsonl_to_jsonl.local.yaml，按需修改后运行：python run.py --config_path=run_profiles/jsonl_to_jsonl.local.yaml

API 同步

• 基线配置：python run.py --config_path=run_profiles/preset/jsonl_to_api.default.yaml
• 使用自定义配置：先从 run_profiles/preset/jsonl_to_api.default.yaml 复制到 run_profiles/jsonl_to_api.local.yaml，按需修改后运行：python run.py --config_path=run_profiles/jsonl_to_api.local.yaml

配置与校验

• 模板配置：run_profiles/preset/*.default.yaml
• 建议先跑 default，再在 run_profiles/*.local.yaml 做覆盖（该目录 YAML 已默认忽略）
• 状态机配置校验：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

其他工具

• UI 调试：python -m ui.main --host 127.0.0.1 --port 8765
• 运维与排障：docs/operations.md

文档导航

• 总体架构：docs/architecture.md
• 状态定义：docs/node_state_definition.md
• 状态机规则：docs/state_machine.md
• 同步流程：docs/sync_flow.md
• 运行配置：docs/runtime_config_guide.md
• Collection 查询与升级：docs/collection_query_and_upgrade_plan.md
• 运维迭代：docs/operations.md

历史资料已归档到 docs/archive/。