# 节点状态定义（业务核心）

本文档定义 `SyncNode` 的状态字段语义，并说明状态机如何把这些语义形式化为可执行规则。

## 1. 节点状态字段

### `binding_status`
- 含义：绑定判定结果，决定节点是否允许进入 create/update。
- 取值：`UNCHECKED | NORMAL | MISSING | PEER_CREATING | WARNING | ABNORMAL | DEPENDENCY_ERROR`

### `action`
- 含义：本轮同步意图。
- 取值：`NONE | CREATE | UPDATE | DELETE`
- 说明：本项目当前主路径使用 `NONE/CREATE/UPDATE`。

### `status`
- 含义：执行状态。
- 取值：`PENDING | IN_PROGRESS | SUCCESS | FAILED | SKIPPED | PRECONDITION_FAILED`

### `data_id`
- 含义：目标系统业务主键是否就绪。
- 关键语义：`UPDATE` 路径要求目标节点具备 `data_id`，否则进入 `PRECONDITION_FAILED`。

### `error`
- 含义：阻断/失败原因。
- 说明：依赖错误与执行错误都在该字段记录可读原因。

## 2. 绑定状态业务语义

| binding_status | 业务语义 | 是否允许进入 create/update |
|---|---|---|
| `UNCHECKED` | 尚未执行 bind 判定 | 否 |
| `NORMAL` | 绑定链路健康，可做差异检测与同步 | 是 |
| `MISSING` | 无绑定记录，需做依赖检查与自动绑定/创建策略 | 有条件 |
| `PEER_CREATING` | 对侧创建进行中（等待创建提交） | 否（等待 E20 提交） |
| `WARNING` | 风险态（如自动绑定歧义/关闭） | 否 |
| `ABNORMAL` | 数据损坏或核心绑定异常 | 否 |
| `DEPENDENCY_ERROR` | 依赖不可满足 | 否 |

bootstrap 特殊语义：
- 如果节点在持久化恢复后存在绑定，但 bootstrap datasource refresh 未返回最新数据，则节点进入 `S17` 语义并被 `bootstrap_blocked` 隔离。
- 如果节点仅残留在 persistence 中、没有绑定，且 datasource refresh 也未返回，则节点按 stale zombie 清理，不再进入 bind。

## 3. create / update 语义

### create
- 来源：`MISSING` 节点在策略允许时生成目标 `CREATE` 节点。
- 形式化：`E20/E21` + `spawn_target_node_state: S06`。

### update
- 来源：`NORMAL` 节点差异检测后生成目标 `UPDATE`。
- 形式化：`E30`。
- 前置失败：目标缺 `data_id` 或依赖 ID 解析失败时进入 `S08`，且必须 `action=UPDATE`。

## 4. 执行状态语义（datasource）

- `SUCCESS`：执行成功，必要时回填 `data_id`。
- `FAILED`：执行失败，保留错误。
- `IN_PROGRESS`：异步任务进行中。
- `SKIPPED`：handler 决策跳过；若由 UPDATE 降级为 NONE，则进入 `S14`。
- `PRECONDITION_FAILED`：准备阶段失败，不进入实际 API 提交。

## 5. 状态机形式化映射

状态机把“业务语义”变成“可执行迁移”：
- 语义输入：strategy/datasource 提供 `context`。
- 迁移判断：`StateMachineRuntime.dispatch(current_state, event_id, context)`。
- 状态落地：`Decision.to_state` 对应 YAML `states[Sxx]`。
- 不变量：每次落地后执行 `runtime.check_invariants()`。

bootstrap 额外输入：
- `is_create_zombie`
- `bootstrap_source_present`
- `has_binding_record`

## 6. 关键一致性约束

- `UNCHECKED` 不允许带动作（`INV-1_UNCHECKED_ACTION_NONE`）。
- 阻断态（`ABNORMAL/WARNING/DEPENDENCY_ERROR`）不允许动作（`INV-2_BLOCKING_NO_ACTION`）。
- `PRECONDITION_FAILED` 必须 `action=UPDATE`（`INV-3_PRECOND_IMPLIES_UPDATE`）。

## 7. 当前默认依赖语义（业务取向）

以下是当前代码默认策略，不是单纯命名差异：
- 空依赖引用允许放行（`allow_empty_dependency_ref=True`）。
- 依赖节点缺失 `data_id` 默认允许放行（`allow_missing_dep_data_id=True`）。

这意味着：`DEPENDENCY_ERROR` 的触发更偏向“依赖节点不存在或状态异常”，而不是“依赖节点尚未回填 data_id”。如果要改为严格模式，需要在 strategy 语义层切换该策略并同步文档。