strepsiades
94 lines
4.3 KiB
Markdown
94 lines
4.3 KiB
Markdown
# 状态机形式化说明（与代码一致）
|
||
|
||
## 1. 真源与执行入口
|
||
- 配置真源：`sync_state_machine/config/node_state_machine.yaml`
|
||
- 事件入口：`sync_state_machine/engine/events.py`
|
||
- 状态落地：`sync_state_machine/engine/state_apply.py`
|
||
- 不变量校验：`events._apply_decision()` 内调用 `runtime.check_invariants()`
|
||
|
||
## 2. 状态集合（Sxx）
|
||
- `S00`：bind 起点（`UNCHECKED/NONE/PENDING`）
|
||
- `S01`：NORMAL，待后续 create/update 判定
|
||
- `S02`：MISSING，待依赖检查/自动绑定/create
|
||
- `S03`：ABNORMAL，阻断
|
||
- `S04`：WARNING，阻断
|
||
- `S05`：DEPENDENCY_ERROR，阻断
|
||
- `S06`：CREATE 待执行（目标节点）
|
||
- `S07`：UPDATE 待执行（`action=UPDATE,status=PENDING`）
|
||
- `S08`：UPDATE 前置失败（`action=UPDATE,status=PRECONDITION_FAILED`）
|
||
- `S10C/S10U/S10D`：按动作拆分的执行中状态
|
||
- `S11C/S11U/S11D`：按动作拆分的执行成功状态
|
||
- `S12C/S12U/S12D`：按动作拆分的执行失败状态
|
||
- `S13`：对侧创建等待态（`PEER_CREATING/NONE/PENDING`）
|
||
- `S14`：UPDATE 运行时降级为 `NONE` 并跳过
|
||
|
||
## 3. 事件到代码映射
|
||
|
||
### bootstrap
|
||
- `E01`：`sync_state_machine/engine/events.py::e01_bootstrap()`
|
||
|
||
### bind
|
||
- `E10`：`sync_state_machine/engine/events.py::e10_bind_core()`
|
||
- `E15`：`sync_state_machine/engine/events.py::e15_bind_dependency()`
|
||
- `E16`：`sync_state_machine/engine/events.py::e16_bind_auto()`（自动绑定判定；`ZERO+create_enabled=true` 时进入 `S13`，等待创建副作用提交）
|
||
|
||
### create/update prepare
|
||
- `E20`：`sync_state_machine/engine/events.py::e20_create_prepare()`（spawn 成功从 `S13` 提交到 `S01`；失败保持 `S13`）
|
||
- `E21`：`sync_state_machine/engine/events.py::e21_create_prepare()`
|
||
- `E30`：`sync_state_machine/engine/events.py::e30_update_prepare()`
|
||
|
||
### sync execute
|
||
- `E40C_START/E40C`：CREATE 执行入口与结果回写
|
||
- `E40U_START/E40U`：UPDATE 执行入口与结果回写
|
||
- `E40D_START/E40D`：DELETE 执行入口与结果回写
|
||
|
||
## 4. strategy 调用链（当前）
|
||
- bind 主入口：`sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.bind()` -> `sync_state_machine/sync_system/strategy_ops/bind_ops.py::run_bind()`
|
||
- create 主入口：`sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.create()` -> `sync_state_machine/sync_system/strategy_ops/create_ops.py::run_create()`
|
||
- update 主入口：`sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.update()` -> `sync_state_machine/sync_system/strategy_ops/update_ops.py::run_update()`
|
||
- reset 主入口：`sync_state_machine/pipeline/full_sync_pipeline.py::_load_persistence_state()` -> `sync_state_machine/sync_system/strategy_ops/reset_ops.py::run_phase2_cleanup()`
|
||
|
||
## 5. context 字段（以 YAML 为准）
|
||
|
||
### bind 相关
|
||
- `has_binding_record`
|
||
- `core_binding_result` / `peer_core_binding_result` (`NORMAL|WARNING|ABNORMAL`)
|
||
- `data_present`
|
||
- `has_depend_fields`
|
||
- `dep_satisfied`
|
||
- `auto_bind_enabled`
|
||
- `auto_bind_outcome` (`ONE_TO_ONE|AMBIGUOUS|ZERO|KEY_MISSING|KEY_ID_RESOLVE_FAIL|DATA_MISSING`)
|
||
|
||
### create/update 相关
|
||
- `create_enabled`
|
||
- `create_id_resolve_ok`
|
||
- `spawn_success`
|
||
- `update_enabled`
|
||
- `target_has_data_id`
|
||
- `update_id_resolve_ok`
|
||
- `has_diff`
|
||
|
||
### execute 相关
|
||
- `handler_result` (`SUCCESS|FAILED|SKIPPED|IN_PROGRESS`)
|
||
- `poll_timeout`
|
||
|
||
## 6. 语义边界
|
||
- strategy 负责业务语义计算（如依赖是否满足、自动绑定结果、差异检测）。
|
||
- 状态机只负责迁移判定与不变量校验，不直接访问数据源。
|
||
|
||
## 7. 不变量
|
||
- `INV-1_UNCHECKED_ACTION_NONE`
|
||
- `INV-2_BLOCKING_NO_ACTION`
|
||
- `INV-3_PRECOND_IMPLIES_UPDATE`
|
||
|
||
当状态落地后违反 invariant，运行时会直接抛错。
|
||
|
||
## 8. 校验与出图
|
||
1. `python tools/validate_config.py --config sync_state_machine/config/node_state_machine.yaml`
|
||
2. `python tools/render_graph.py --config sync_state_machine/config/node_state_machine.yaml --format mermaid --out docs/state_machine.mmd`
|
||
|
||
## 9. 事件意图命名（图示层）
|
||
- 为了让流程意图更直观，图示可使用 `E01.reset.* / E10.core.* / E20.create.* / E30.update.* / E40<action>.* / E41.create.*` 这类别名。
|
||
- 别名仅用于图标签；运行时事件 ID 仍以 YAML 中 `E01/E10/E15/E16/E20/E21/E30/E40C_START/E40C/E40U_START/E40U/E40D_START/E40D/E41` 为准。
|
||
- `S10C/S10U/S10D` 与 `S11C/S11U/S11D` 现已是配置中的真实状态 ID（不再是图示别名）。
|