ecm_sync_system/docs/sync_flow.md

同步流程（pipeline -> strategy -> datasource）

1. 全流程主线

1. pipeline 装配组件并加载持久化。
2. pipeline 为 datasource 绑定 collection，但不在 bootstrap 阶段全量拉取业务数据。
3. pipeline 在每个 node_type 开始执行前，单独加载该 node_type 的最新数据。
4. pipeline 调用 strategy.bind()。
5. pipeline 调用 strategy.create() / strategy.update() 生成动作节点。
6. pipeline 调用 datasource.sync_all() 执行动作并回写执行状态。
7. pipeline 输出统计并持久化。

2. reset 时序

2.1 加载时恢复

• 在 sync_state_machine/common/collection.py::load_from_persistence() 执行。
• 语义：仅恢复持久化状态，并记录本轮 sync_log 的 persistence 恢复来源；不在此阶段做状态归并。
• 恢复后保留 data/origin_data，等待 bootstrap 阶段的 datasource 刷新覆盖最新数据。

2.2 bootstrap datasource refresh

• pipeline 在持久化恢复后、E01 之前，按已恢复到内存的 node_type 做一次 datasource 刷新。
• 实际实现：sync_state_machine/pipeline/full_sync_pipeline.py::_bootstrap_refresh_latest_data()。
• 语义：
  • 如果 datasource 命中节点，则用最新数据覆盖持久化快照，并清除 _loaded_from_persistence 标记。
  • 如果 datasource 未命中节点，则节点保留持久化快照，供 E01 判断它是 stale zombie 还是 bootstrap 异常隔离对象。

2.3 加载后 cleanup

• pipeline 在 datasource refresh 完成后调用 run_phase2_cleanup()。
• 实际实现：sync_state_machine/sync_system/strategy_ops/reset_ops.py::run_phase2_cleanup()。
• 核心事件：E01（S16 -> S00/S15）。
• S16 表示“bootstrap 输入态”：持久化恢复出的节点，叠加 datasource refresh 后仍待 E01 判定的节点集合。
• 判定：
  • is_create_zombie=true -> S15，节点删除（并尝试解绑）；
  • bootstrap_source_present=false && has_binding_record=false -> S15，说明该节点仅残留在 persistence 中且未绑定，按 stale zombie 清理；
  • bootstrap_source_present=false && has_binding_record=true -> S17，说明该节点存在绑定，但 datasource refresh 未返回，进入 bootstrap 加载异常隔离；
  • 其余情况 -> S00，节点归并为 UNCHECKED/NONE/PENDING 并清空 error。

2.2.1 enable_persistence 与 bootstrap 关系

• enable_persistence=true：先 load_from_persistence()，再做 bootstrap datasource refresh，最后对输入节点执行 E01（S16 域内处理）。
• enable_persistence=false：本轮没有持久化输入，S16/E01 不参与；随后 Stage1 新加载节点直接进入本轮 bind/create/update/sync 主流程。

2.4 加载异常隔离（S17）

• 持久化中若出现非法枚举值（action/status/binding_status），节点标记为 bootstrap_blocked（S17 语义）。
• 持久化恢复后若节点存在绑定，但 bootstrap datasource refresh 未返回该节点，也会进入 S17 语义并隔离。
• 这类节点保留 error，用于人工排查。
• 这类节点不会进入 E01，也不会参与 bind/create/update/sync 自动流程。

3. bind 流程（strategy_ops）

• 入口：sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.bind()
• 入口状态：S00

bind 编排步骤

• strategy 先通过 bind_ops.collect_bind_entry_nodes() 收集两侧 S00 节点，作为 bind 入口工作集。
• phase_core_state() 对入口工作集触发 E10，把“已有绑定记录”和“无绑定记录”的节点分流到 S01/S03/S04/S02。
• phase_dependency_check() 对仍需继续处理的缺绑节点触发 E15，把缺数据、依赖不满足、语义错误的节点拦到 S03/S05/S04。
• strategy 再通过 bind_ops.collect_auto_bind_ready_nodes() 收窄工作集，只保留当前 S02 + binding_status=MISSING 的节点进入自动绑定判定。
• strategy 在顶层显式构造 orphan create 控制参数，并传给 bind_ops.plan_auto_bind_updates() 生成自动绑定/自动创建决策。
• apply_auto_bind_updates() 对这些决策逐个触发 E16，把节点迁移到 S01/S04/S05/S13。
• refresh_bind_data_id() 最后按绑定关系回填两侧节点的 context.bind_data_id。

核心绑定判定

• phase_core_state() 内触发 E10。
• 有绑定记录：根据本端/对端有效性进入 S01/S03/S04。
• 无绑定记录：进入 S02。

注意：如果节点在 bootstrap 阶段已被隔离为 S17 语义（bootstrap_blocked=true），默认不会进入 bind 工作集。

依赖检查

• phase_dependency_check() -> check_dependencies_for_nodes() 内触发 E15。
• data_present=true 且 dep_satisfied=true -> 不迁移，节点保持在 S02，继续进入自动绑定判定。
• data_present=false -> S03。
• dep_satisfied=false -> S05。
• depend_fields 为空本身不会触发阻断；若节点数据存在，则等价于“当前依赖满足”，继续留在 S02。

自动绑定

• phase_auto_binding() 内触发 E16。
• ONE_TO_ONE -> S01；AMBIGUOUS/KEY_MISSING/DATA_MISSING -> S04；KEY_ID_RESOLVE_FAIL -> S05。
• ZERO + create_enabled=true -> S13（PEER_CREATING/NONE/PENDING，待对侧创建中间态）；ZERO + create_enabled=false -> S04。
• auto_bind=false 时，E16 直接落 S04（自动绑定未启用），不会进入自动创建路径。

4. create/update 准备

create

• 入口：sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.create()
• 运行时事件：E20（E21/E22 为配置保留分支，当前 strategy 未接入自动执行）
• 运行时入口状态：S13
• 说明：E16 负责识别“需自动创建”并将源节点置为 S13；业务代码执行对侧 spawn+bind 后，再通过 E20 将 S13 提交到 S01（成功）；若 spawn 失败，E20 不迁移并保留在 S13 等待人工/重试。
• data_id 约束：
  • S13/S01 要求源节点 data_id 存在（data_id_exist=true）。
  • 新创建目标节点在 S06/S10C 阶段允许 data_id 为空；CREATE SUCCESS（S11C）必须携带非空 result_data_id，否则事件直接报错。

update

• 入口：sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.update()
• 事件：E30
• 入口状态（source 节点）：S01
• target_has_data_id=false 或 update_id_resolve_ok=false -> S08
• has_diff=true -> S07

post-create 归并

• 入口：sync_state_machine/pipeline/full_sync_pipeline.py::normalize_create_success_to_update_entry()
• 事件：E41
• 语义：CREATE 执行成功后，节点先落 S11C（SUCCESS），再归并 S11C -> S01，作为同轮 update 起点。

5. 执行回写（datasource）

• 入口：sync_state_machine/datasource/datasource.py
• 事件：E40C_START/E40C、E40U_START/E40U、E40D_START/E40D
• 当前约束：delete stage 尚未接入 strategy 主流程；若运行时检测到 S09/DELETE 节点，DataSource 会显式抛错阻断（避免散落删除执行）。
• 执行准备入口状态：
  • CREATE: S06
  • UPDATE: S07
  • DELETE: S09
• S10 为执行中状态（由本轮执行产生），执行流转固定为“入口 -> S10 -> 终态”，不再出现入口直接到成功/失败。
• 结果：
  • SUCCESS -> S11C | S11U | S11D（按动作）
  • FAILED -> S12C | S12U | S12D（按动作）
  • IN_PROGRESS -> S10C | S10U | S10D（按动作，支持异步 polling 闭环）
  • SKIPPED + action=UPDATE -> S14

6. 各阶段入口状态总表

阶段	入口状态	说明
Reset(E01)	S16	create_zombie -> S15；其余 -> S00
Bind(E10/E15/E16)	S00	bind 三段统一从 S00 进入
Create Prepare(E20/E21/E22)	S02 / S13	配置入口含 S02/S13；当前 strategy 运行时只处理 S13 的 E20 提交，S02 分支保留未接入
Post-create Ready(E41)	S11C	CREATE 成功节点归并到 S01，进入同轮 update
Update Prepare(E30)	S01	仅从 NORMAL 继续判定（create 成功先经 E41 归并）
Sync Execute(E40C/U/D)	S06 / S07 / S09 / S10C / S10U / S10D	执行与回写：按动作分事件；入口先进入 S10*，再由 S10* 进入 S11*/S12*；轮询返回 IN_PROGRESS 时只记录任务进度，不新增状态迁移；仅 UPDATE 可走 S14
隔离（人工）	S17	不参与自动阶段，仅人工处理

7. 不变量保障

• 每次事件落地后，sync_state_machine/engine/events.py::_apply_decision() 会执行 runtime.check_invariants()。
• 违反 invariant 直接抛错，终止当前路径。