first commit

docs/architecture.md

@@ -0,0 +1,66 @@
+# 同步系统整体框架
+
+## 1. 分层职责（pipeline + strategy + datasource + domain）
+
+### pipeline（编排层）
+- 入口：`pipeline/full_sync_pipeline.py`
+- 负责组装并驱动整条流程：加载持久化、执行 bind/create/update、调用 datasource 同步、持久化结果。
+- reset 语义：
+	- 加载阶段仅恢复持久化状态（不做状态重置）；
+	- 加载后通过 `BaseSyncStrategy.run_reset()` 触发 `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_system/strategy.py`
+- 具体实现下沉：`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`: `get_phase1_reset_defaults()/run_phase2_cleanup()`
+- strategy 负责收集上下文并调用状态机事件函数，不直接硬编码状态值。
+
+### datasource（执行与回写层）
+- 入口：`datasource/datasource.py`
+- 执行 handler（create/update/delete），并结合 `E40` 将执行结果落地到节点状态。
+
+### domain（业务适配层）
+- 目录：`domain/*`
+- 负责业务字段映射、handler 细节与 schema 约束，不承担状态迁移判定。
+
+## 2. 运行时契约（Runtime Contract）
+
+### 真源
+- 状态机配置真源：`config/node_state_machine.yaml`
+- 事件执行入口：`engine/events.py`
+- 状态落地入口：`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`