strepsiades
67 lines
3.4 KiB
Markdown
67 lines
3.4 KiB
Markdown
# 同步系统整体框架
|
||
|
||
## 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`
|