# 同步系统整体框架

## 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`: bind 阶段静态函数与纯工具
	- `create_ops.py`: create 阶段静态函数与纯工具
	- `update_ops.py`: update 阶段静态函数与纯工具
	- `delete_ops.py`: `run_delete()`
	- `reset_ops.py`: `run_phase2_cleanup()`
- strategy 负责 bind/create/update 的相位内部编排，并调用状态机事件函数，不直接硬编码状态值。

### 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`