ecm_sync_system/docs/architecture.md

同步系统整体框架

1. 分层职责（pipeline + strategy + datasource + domain）

pipeline（编排层）

• 入口：sync_state_machine/pipeline/full_sync_pipeline.py
• 负责组装并驱动整条流程：加载持久化、执行 bind/create/update、调用 datasource 同步、持久化结果。
• reset 语义：
  • 加载阶段仅恢复持久化状态（不做状态重置）；
  • 加载后通过 run_phase2_cleanup() 触发 E01：
    • create_zombie=true -> S15（随后删除）；
    • create_zombie=false -> S00（归并为 UNCHECKED/NONE/PENDING，并清空 error）。
  • 若持久化核心枚举非法（action/status/binding_status），节点进入加载异常隔离态 S17：
    • 保留错误信息供人工介入；
    • 不参与 E01 与后续 bind/create/update/sync 自动流程。

pipeline 运行语境（人工介入 + 可变配置）

• 运行前可按批次调整策略配置（例如“首轮先拉取、后续只推送”），属于 pipeline 的一次性运行参数。
• 人工介入分两段：
  • 运行前：可手工修复数据、手工绑定、调整策略参数；
  • 运行后：根据节点 status/error/sync_log 处理异常（为未来 GUI 介入提供依据）。
• 若上轮异常未人工处理，本轮在 E01 先做归并/清理：
  • CREATE 僵尸节点自动删除并解除绑定残留；
  • 非僵尸节点统一进入 S00，再进入本轮 bind/create/update 判定。

strategy（决策组织层）

• 外部入口：sync_state_machine/sync_system/strategy.py
• 具体实现下沉：sync_state_machine/sync_system/strategy_ops/
  • bind_ops.py: run_bind() + phase_core_state()/phase_dependency_check()/phase_auto_binding()
  • create_ops.py: run_create()
  • update_ops.py: run_update()
  • delete_ops.py: run_delete()
  • reset_ops.py: run_phase2_cleanup()
• strategy 负责收集上下文并调用状态机事件函数，不直接硬编码状态值。

datasource（执行与回写层）

• 入口：sync_state_machine/datasource/datasource.py
• 执行 handler（create/update/delete），并结合 E40 将执行结果落地到节点状态。

domain（业务适配层）

• 目录：sync_state_machine/domain/*
• 负责业务字段映射、handler 细节与 schema 约束，不承担状态迁移判定。

2. 运行时契约（Runtime Contract）

真源

• 状态机配置真源：sync_state_machine/config/node_state_machine.yaml
• 事件执行入口：sync_state_machine/engine/events.py
• 状态落地入口：sync_state_machine/engine/state_apply.py

执行规则

1. 业务层构造 context。
2. 调用 StateMachineRuntime.dispatch(current_state, event_id, context)。
3. 依据 Decision.to_state 从 YAML states[Sxx] 落地 binding_status/action/status。
4. Decision.emit 只用于状态外副作用（spawn、绑定、调用 handler 等）。
5. 每次事件落地后，events._apply_decision 调用 runtime.check_invariants()；违反直接抛错。

3. 边界与约束

• strategy/datasource 不应绕过状态机直接写最终状态。
• PRECONDITION_FAILED 必须满足 action=UPDATE（YAML invariant 强约束）。
• 依赖语义由 strategy 计算（如 dep_satisfied/dep_errors），状态机只消费语义结果并迁移。

4. 相关文档

• 框架与流程：docs/sync_flow.md
• 节点状态定义：docs/node_state_definition.md
• 状态机形式化说明：docs/state_machine.md