first commit

docs/archive/from_root_docs/状态机形式化规范.md

@@ -0,0 +1,498 @@
+# 状态机形式化规范
+
+本文档用 **Guard-Event-Action (GEA)** 形式严格定义节点状态机。  
+所有转换以代码实现为准，模糊之处在文档中显式标注。
+
+> **代码基线**
+> - 枚举: `sync_system_new/common/types.py`
+> - 决策引擎: `sync_system_new/sync_system/decision.py`
+> - 重置策略: `sync_system_new/common/state_reset.py`
+> - 同步策略: `sync_system_new/sync_system/strategy.py`
+> - 物理同步: `sync_system_new/datasource/datasource.py`
+
+> **配置基线（状态机真源）**
+> - `sync_system_new/state_machine/node_state_machine.yaml`
+
+### 2026-02 对齐说明（重构前必读）
+
+以下语义以 `node_state_machine.yaml` 为准，用于修正文档中易混淆点：
+
+1. **E12a 为什么从 S01 出发？**
+    - `S01` 只约束**源节点**是 NORMAL/NONE/PENDING 且有 `data_id`。
+    - `E12a` 的 guard 是 `target_has_data_id=false`，检查对象是**目标节点**。
+    - 所以“源节点在 S01”与“E12a 触发前置失败”并不冲突。
+
+2. **S01 会不会触发创建？**
+    - 当前配置中，create 的入口状态是 `S02(MISSING)`，不是 `S01`。
+    - `S01` 进入的是 update_prepare（E12/E13/E14）。
+
+3. **N:0 + create_enabled=true 的当前行为**
+    - 自动绑定分支 `E08f`：`S02 -> S01`，并 `emit spawn_target_node_state: S06`。
+    - create_prepare 分支 `E09b` 也可在检查成功后 `S02 -> S01 + spawn S06`。
+    - 即：源节点不会停在“等待创建结果”的专用状态；创建执行结果体现在目标创建节点链路 `S06 -> S10/S11/S12/S13`。
+
+4. **旧章节中的事件编号偏差**
+    - 本文后续仍有部分“E11a/E11b/…”旧编号描述，已与当前 YAML 不一致。
+    - 进行代码重构时，优先依据 YAML 的 `E08/E09/E10/E12/E13/E14/E15..E20`。
+
+---
+
+## §1 状态空间定义
+
+### §1.1 状态维度
+
+节点携带 **三个独立的状态字段** 和 **两个辅助字段**：
+
+| 字段 | 枚举 | 值域 | 语义 |
+|------|------|------|------|
+| **B** – `binding_status` | `BindingStatus` | `UNCHECKED` · `NORMAL` · `MISSING` · `ABNORMAL` · `WARNING` · `DEPENDENCY_ERROR` | 绑定健康度 |
+| **A** – `action` | `SyncAction` | `NONE` · `CREATE` · `UPDATE` · `DELETE` | 待执行动作 |
+| **S** – `status` | `SyncStatus` | `PENDING` · `IN_PROGRESS` · `SUCCESS` · `FAILED` · `SKIPPED` · `PRECONDITION_FAILED` | 执行结果 |
+
+辅助字段（影响 Guard 但不是状态维度）：
+
+| 字段 | 类型 | 语义 |
+|------|------|------|
+| `data_id` | `str` | 业务主键（空串 `""` = 尚未从远程获取） |
+| `error` | `str \| None` | 最近一次错误信息 |
+
+理论组合 = 6 × 4 × 6 = **144**，实际可达 ≈ **23** 种。
+
+### §1.2 可达状态枚举
+
+以下列出所有在正常流程中可以到达的 `(binding_status, action, status)` 三元组。
+
+| # | binding_status | action | status | 语义 | 产生阶段 |
+|---|---|---|---|------|---------|
+| R1 | UNCHECKED | NONE | PENDING | 首次加载 | 数据加载 |
+| R2 | UNCHECKED | NONE | SUCCESS | 从持久化恢复(上轮成功)后重置 | 阶段1/2重置 |
+| R3 | UNCHECKED | NONE | FAILED | 从持久化恢复(上轮失败)后重置 | 阶段1/2重置 |
+| R4 | UNCHECKED | NONE | SKIPPED | 从持久化恢复(上轮跳过)后重置 | 阶段1/2重置 |
+| R5 | UNCHECKED | NONE | PRECONDITION_FAILED | 从持久化恢复(上轮前置失败)后重置 | 阶段1/2重置 |
+| R6 | NORMAL | NONE | PENDING | 绑定正常，无需操作(首次) | bind.p1 |
+| R7 | NORMAL | NONE | SUCCESS | 绑定正常，无需操作(历史成功) | bind.p1 |
+| R8 | NORMAL | NONE | FAILED | 绑定正常但上次失败，被 FAILED 保护 | bind.p1 |
+| R9 | MISSING | NONE | PENDING | 孤儿，等待自动绑定或创建(首次) | bind.p1 |
+| R10 | MISSING | NONE | SUCCESS | 孤儿(历史成功但绑定丢失?) | bind.p1 |
+| R11 | ABNORMAL | NONE | * | 数据损坏，需人工 | bind.p1 |
+| R12 | WARNING | NONE | * | 多候选/对方损坏，需人工 | bind.p1/p3 |
+| R13 | DEPENDENCY_ERROR | NONE | PENDING | 依赖不满足 | bind.p2/p3/create |
+| R14 | NORMAL | CREATE | PENDING | 准备创建(目标节点) | create |
+| R15 | NORMAL | CREATE | IN_PROGRESS | 异步创建进行中 | sync |
+| R16 | NORMAL | CREATE | SUCCESS | 创建成功 | sync |
+| R17 | NORMAL | CREATE | FAILED | 创建失败 | sync |
+| R18 | NORMAL | UPDATE | PENDING | 准备更新(目标节点) | update |
+| R19 | NORMAL | UPDATE | IN_PROGRESS | 异步更新进行中 | sync |
+| R20 | NORMAL | UPDATE | SUCCESS | 更新成功 | sync |
+| R21 | NORMAL | UPDATE | FAILED | 更新失败 | sync |
+| R22 | NORMAL | UPDATE | PRECONDITION_FAILED | 更新前置条件失败 | update |
+| R23 | NORMAL | CREATE | SKIPPED | 创建被 Handler 跳过 | sync |
+
+> **不可达组合（示例）**：
+> - `(MISSING, UPDATE, *)` — MISSING 节点不可能被安排 UPDATE
+> - `(ABNORMAL, CREATE, *)` — ABNORMAL 节点不可能被安排 CREATE
+> - `(*, DELETE, *)` — DELETE 尚未实现
+> - `(UNCHECKED, CREATE, *)` — UNCHECKED 是瞬态，在 bind 之前不会有 CREATE
+> - `(DEPENDENCY_ERROR, UPDATE, *)` — DEPENDENCY_ERROR 节点不可能进入 update 流程
+
+### §1.3 辅助字段约束
+
+| 对应状态 | binding_status | action | status | data_id 约束 | error 约束 |
+|---------|---|---|---|-------------|-----------|
+| R14 | NORMAL | CREATE | PENDING | `""` (待远程返回) | None |
+| R16 | NORMAL | CREATE | SUCCESS | 非空 (远程回填) | None |
+| R17 | NORMAL | CREATE | FAILED | `""` (未回填) | 非空 |
+| R22 | NORMAL | UPDATE | PRECONDITION_FAILED | * | 非空 |
+| R13 | DEPENDENCY_ERROR | NONE | PENDING | * | 非空 |
+
+---
+
+## §2 不变量 (Invariants)
+
+以下约束在**任何事件执行后**都必须成立。违反即为 Bug。
+
+```
+INV-1  B = UNCHECKED  ⟹  A = NONE
+       (UNCHECKED 是瞬态，在 bind 之前不允许有动作)
+
+INV-2  B ∈ {ABNORMAL, WARNING, DEPENDENCY_ERROR}  ⟹  A = NONE
+       (阻断态节点不允许执行任何同步动作)
+
+INV-3  B = MISSING  ⟹  A ∈ {NONE, CREATE}
+       (MISSING 节点只能等待创建或保持不动)
+
+INV-4  A = CREATE  ⟹  B = NORMAL
+       (CREATE 动作只出现在目标节点上，其 binding_status 已被设为 NORMAL)
+
+INV-5  A = UPDATE  ⟹  B = NORMAL
+       (UPDATE 动作只对 NORMAL 节点执行)
+
+INV-6  S = IN_PROGRESS  ⟹  A ∈ {CREATE, UPDATE, DELETE}
+       (只有提交过 API 的节点才可能处于 IN_PROGRESS)
+
+INV-7  S = PRECONDITION_FAILED  ⟹  A = UPDATE
+       (PRECONDITION_FAILED 只在 update 阶段产生)
+
+INV-8  A = CREATE ∧ S = SUCCESS  ⟹  data_id ≠ ""
+       (创建成功必须回填 data_id)
+
+INV-9  S = FAILED  ⟹  error ≠ None
+       (失败必须有错误信息)
+
+INV-10 B = DEPENDENCY_ERROR  ⟹  error ≠ None
+       (依赖阻断必须有错误信息)
+```
+
+---
+
+## §3 事件与转换
+
+### §3.1 事件总览图
+
+```
+                    ┌─────────────────────────────────────────────────────┐
+                    │            节点生命周期事件流                         │
+                    └─────────────────────────────────────────────────────┘
+
+  持久化恢复                 策略层 (Strategy)                      执行层 (DataSource)
+ ═══════════         ══════════════════════════════════        ══════════════════════════
+                     ┌──────────────────────────────┐
+  ┌──────┐           │         bind()               │         ┌──────────────────────┐
+  │E01   │──────────▶│  E04 ─┐                      │         │   sync_all()         │
+  │RESET1│           │  E05  ├─ phase1: core_state   │         │                      │
+  └──┬───┘           │  E06 ─┘                      │         │  E12  SYNC_OK        │
+     │               │  E07 ── phase2: dep_check     │    ┌───▶│  E13  SYNC_FAIL      │
+  ┌──▼───┐           │  E08 ─┐                      │    │    │  E14  SYNC_ASYNC     │
+  │E02   │           │  E09  ├─ phase3: auto_bind    │    │    │  E15  SYNC_TIMEOUT   │
+  │ZOMBIE│           │  E10 ─┘                      │    │    │  E16  HANDLER_SKIP   │
+  └──┬───┘           └──────────────────────────────┘    │    │  E17  HANDLER_DOWN   │
+     │               ┌──────────────────────────────┐    │    └──────────────────────┘
+  ┌──▼───┐           │       create() / update()    │    │
+  │E03   │──────────▶│  E11a CREATE_OK              │────┘
+  │RESET2│           │  E11b CREATE_DEP_FAIL        │
+  └──────┘           │  E11c UPDATE_DIFF            │
+                     │  E11d UPDATE_PRECOND_FAIL    │
+                     │  E11e UPDATE_SKIP_FAILED     │
+                     └──────────────────────────────┘
+```
+
+
+### §3.2 状态转换详解
+
+本节按 Pipeline 执行阶段组织。每个阶段包含：
+1. **状态转换图**：状态（R 编号）为节点，事件（E 编号）为有向边
+2. **转换表**：每个事件的精确规格——起始状态、判断条件、结束状态、副作用
+
+---
+
+#### 🔄 阶段 0：重置
+
+**状态转换图：**
+
+```
+    ╔═══════════════════════════════════════╗
+    ║  任意持久化终态 (R6 ~ R23)             ║
+    ╚═══════════════════╤═══════════════════╝
+                        │ E01
+                        ▼
+    ┌────────────────────────────────────────┐     E02
+    │  瞬态: UNCHECKED                       │────────────▶ [节点删除 + 解除绑定]
+    │  (action 保留, status 保留, error=None) │
+    └────────────────────┬──────────────────┘
+                         │ E03 (存活节点)
+                         ▼
+    ╔══════════════════════════════════════════════════════════════╗
+    ║ [R1]  UNCHECKED,  NONE,  PENDING              ← 首次加载    ║
+    ║ [R2]  UNCHECKED,  NONE,  SUCCESS              ← 上轮成功    ║
+    ║ [R3]  UNCHECKED,  NONE,  FAILED               ← 上轮失败    ║
+    ║ [R4]  UNCHECKED,  NONE,  SKIPPED              ← 上轮跳过    ║
+    ║ [R5]  UNCHECKED,  NONE,  PRECONDITION_FAILED  ← 上轮前置    ║
+    ╚══════════════════════════════════════════════════════════════╝
+```
+
+**转换表：**
+
+| 事件 | 起始状态 | 判断条件 (Guard) | 结束状态 | 副作用 |
+|------|---------|-----------------|---------|--------|
+| **E01**: PHASE1_RESET | R6~R23 (任意持久化终态) | 节点从持久化加载 | 瞬态 (UNCHECKED, action 保留, status 保留) | error → None; data/origin_data → None |
+| **E02**: ZOMBIE_KILL | 瞬态 | action = CREATE ∧ (status = FAILED ∨ data_id = "") | **节点删除** | 解除绑定关系; 对 local/remote 两侧都扫描 |
+| **E03**: ACTION_RESET | 瞬态 (存活节点) | E02 完成后所有存活节点 | R1 / R2 / R3 / R4 / R5 (按原 status 分) | action → NONE |
+
+> **代码**: `NodeStateReset.get_phase1_reset_defaults()` · `cleanup_create_failed_zombies()` · `reset_action_for_nodes()`
+
+---
+
+#### 🔗 阶段 1：Bind
+
+Bind 由三个子阶段串行执行。后一阶段只处理前一阶段的遗留 MISSING 节点。
+
+**状态转换图：**
+
+```
+    [R1~R5]  UNCHECKED, NONE, *
+        │
+        │  ══════════ Phase 1: 核心状态判定 ══════════
+        │
+        ├── E04 (有绑定, 双方数据 VALID) ───────────▶ [R6/R7/R8] NORMAL ──────▶ 出口 ✅
+        ├── E04 (有绑定, 自身数据缺失/损坏) ────────▶ [R11] ABNORMAL ─────────▶ 出口 🔒
+        ├── E04 (有绑定, 对方数据缺失/损坏) ────────▶ [R12] WARNING ──────────▶ 出口 🔒
+        │
+        └── E05 (无绑定记录) ───────────────────────▶ [R9] MISSING
+                                                          │
+            ══════════ Phase 2: 依赖检查 ══════════      │
+                                                          │
+            ├── E06 (data = None) ──────────────────────▶ [R11] ABNORMAL ──────▶ 出口 🔒
+            ├── E07 (依赖节点不满足) ───────────────────▶ [R13] DEP_ERROR ─────▶ 出口 🔒
+            │   (无依赖配置 或 依赖全部满足 → 继续 ▼)
+            │
+            ══════════ Phase 3: 自动绑定 ══════════
+            │
+            ├── E08 (auto_bind 关闭) ──────────────────▶ [R12] WARNING ────────▶ 出口 🔒
+            ├── E09 (去噪后 1:1 匹配成功) ─────────────▶ [R6] NORMAL ─────────▶ 出口 ✅
+            ├── E10a (去噪后非 1:1, 多候选) ───────────▶ [R12] WARNING ────────▶ 出口 🔒
+            ├── E10b (业务键字段缺失) ─────────────────▶ [R12] WARNING ────────▶ 出口 🔒
+            ├── E10c (业务键中 ID 字段解析失败) ───────▶ [R13] DEP_ERROR ─────▶ 出口 🔒
+            │
+                └── (1:0 无远程匹配)
+                    ├── create_enabled = True  → [R9]  MISSING ──────────────▶ 进入 create
+                    └── create_enabled = False → [R12] WARNING ─────────────▶ 出口 🔒
+```
+
+**转换表：**
+
+| 事件 | 起始状态 | 判断条件 (Guard) | 结束状态 | 副作用 |
+|------|---------|-----------------|---------|--------|
+| **E04**: BIND_PAIRED | R1~R5 | 有绑定记录 ∧ 双方数据 VALID | R6 (PENDING) / R7 (SUCCESS) / R8 (FAILED) — status 保持 | 远程节点同步设置 binding_status |
+| **E04**: BIND_PAIRED (自身异常) | R1~R5 | 有绑定记录 ∧ 本方数据缺失或损坏 | R11 (ABNORMAL) | 对方节点设为 WARNING |
+| **E04**: BIND_PAIRED (对方异常) | R1~R5 | 有绑定记录 ∧ 对方数据缺失或损坏 | R12 (WARNING) | 对方节点设为 ABNORMAL |
+| **E05**: BIND_ORPHAN | R1~R5 | 无绑定记录 | R9 (MISSING, NONE, status 保持) | — |
+| **E06**: DATA_NULL | R9 | binding_status = MISSING ∧ data = None | R11 (ABNORMAL) | error = "数据损坏: 节点数据为空或不存在" |
+| **E07**: DEP_CHECK_FAIL | R9 | depend_fields 配置非空 ∧ ∃依赖节点: 不存在 ∨ status ≠ NORMAL ∨ data_id 为空 | R13 (DEPENDENCY_ERROR) | error = "依赖项不满足: ..."; depend_ids 填充 |
+| **E08**: AUTOBIND_DISABLED | R9 | auto_bind = False 或 auto_bind_fields 为空 | R12 (WARNING) | — |
+| **E09**: AUTOBIND_OK | R9 | 去噪后 local:remote = 1:1 ∧ 双方都是 MISSING | R6 (NORMAL) | 建立绑定记录; 双方都设为 NORMAL |
+| **E10a**: AUTOBIND_AMBIGUOUS | R9 | 去噪后非 1:1 (多候选) | R12 (WARNING) | error += "存在多个候选节点" |
+| **E10b**: AUTOBIND_KEY_MISSING | R9 | auto_bind_fields 中有字段不存在于 data | R12 (WARNING) | error += "缺少业务键字段: ..." |
+| **E10c**: AUTOBIND_ID_FAIL | R9 | 业务键包含 ID 字段 ∧ ID 解析失败 | R13 (DEPENDENCY_ERROR) | error = "业务键中的ID字段解析失败: ..." |
+| **E10d**: ORPHAN_CREATE_DISABLED | R9 | 去噪后 1:0 ∧ create_enabled = False | R12 (WARNING) | error += "孤儿且不允许自动创建" |
+
+> **E04 核心状态矩阵** (完整查表):
+>
+> | | 远程: VALID | 远程: ABSENT | 远程: INVALID |
+> |---|---|---|---|
+> | **本地: VALID** | 本:NORMAL 远:NORMAL | 本:WARNING 远:ABNORMAL | 本:WARNING 远:ABNORMAL |
+> | **本地: ABSENT** | 本:ABNORMAL 远:WARNING | 本:ABNORMAL 远:ABNORMAL | — |
+> | **本地: INVALID** | 本:ABNORMAL 远:WARNING | — | 本:ABNORMAL 远:ABNORMAL |
+>
+> 不在矩阵中的组合 → 默认 (ABNORMAL, ABNORMAL)
+
+> **代码**: `SyncDecisionEngine.determine_core_status()` · `strategy_ops/bind_ops.py::phase_core_state()` · `strategy_ops/bind_ops.py::check_dependencies_for_nodes()` · `strategy_ops/bind_ops.py::phase_auto_binding()`
+
+---
+
+#### ⚡ 阶段 2：Create / Update
+
+**状态转换图：**
+
+```
+    ═══════════════ Create ═══════════════
+
+    [R9]  MISSING, NONE, PENDING  (源节点, data ≠ None)
+        │
+        ├── E11a (ID 解析成功) ────▶  源节点: [R9] → [R6] NORMAL
+        │                            新建目标节点: → [R14] NORMAL, CREATE, PENDING
+        │                            + 建立绑定记录, 目标 data_id = ""
+        │
+        └── E11b (ID 解析失败) ────▶  源节点: [R9] → [R13] DEPENDENCY_ERROR
+
+
+    ═══════════════ Update ═══════════════
+
+    [R6/R7]  NORMAL, NONE, PENDING/SUCCESS  (源节点, status ≠ FAILED)
+        │
+        ├── E11c (差异检测通过) ────▶  目标节点 → [R18] NORMAL, UPDATE, PENDING
+        ├── E11d.1 (目标 data_id="") ▶  目标节点 → [R22] status = PRECONDITION_FAILED
+        ├── E11d.2 (ID 解析失败) ───▶  目标节点 → [R22] action = UPDATE, status = PRECOND_FAIL
+        └── (无差异) ──────────────▶  保持不变
+
+
+    ═══════════════ FAILED 保护 ═══════════════
+
+    [R8]  NORMAL, NONE, FAILED  (源节点)
+        │
+        └── E11e ──────────────────▶  跳过，保持 [R8] 不变
+```
+
+**转换表：**
+
+| 事件 | 起始状态 (源节点) | 判断条件 (Guard) | 结束状态 | 副作用 |
+|------|---------|-----------------|---------|--------|
+| **E11a**: CREATE_OK | R9 (MISSING) | data ≠ None ∧ IDResolver.resolve_and_validate() = OK | 源 → R6 (NORMAL); **新建**目标 → R14 | 建立绑定; 新节点 data = 已替换 ID 的副本, data_id = "" |
+| **E11b**: CREATE_DEP_FAIL | R9 (MISSING) | data ≠ None ∧ IDResolver.resolve_and_validate() = FAIL | R13 (DEPENDENCY_ERROR) | error = "创建时依赖 ID 未解析: ..." |
+| **E11c**: UPDATE_DIFF | R6/R7 (NORMAL, status≠FAILED) | 目标存在 ∧ 目标 data_id ≠ "" ∧ ID 解析 OK ∧ _needs_update() = True | 目标 → R18 (UPDATE, PENDING) | 目标: data 替换, error = None |
+| **E11d**: UPDATE_PRECOND_FAIL | R6/R7 (NORMAL, status≠FAILED) | 目标 data_id = "" (d1) 或 ID 解析失败 (d2) | 目标 → R22 (UPDATE, PRECONDITION_FAILED) | error = "目标缺少 data_id" 或 "依赖 ID 未解析" |
+| **E11e**: UPDATE_SKIP_FAILED | R8 (NORMAL, FAILED) | status = FAILED | R8 不变 | 保护上次的 error 和 FAILED 状态，不做任何修改 |
+
+> **代码**: `strategy_ops/create_ops.py::add_create_action()` · `strategy_ops/update_ops.py::add_update_action()`
+
+---
+
+#### 📡 阶段 3：Sync（物理同步）
+
+**状态转换图：**
+
+```
+    [R14] NORMAL, CREATE, PENDING       [R18] NORMAL, UPDATE, PENDING
+        │                                   │
+        └───────────────┬───────────────────┘
+                        │
+                        ├── E12 (API 成功) ──────▶ [R16] CREATE,SUCCESS / [R20] UPDATE,SUCCESS
+                        ├── E13 (API 失败) ──────▶ [R17] CREATE,FAILED  / [R21] UPDATE,FAILED
+                        ├── E16 (Handler 跳过) ──▶ [R23] CREATE, SKIPPED
+                        ├── E17 (Handler 降级) ──▶ [R6]  NORMAL, NONE, PENDING  (仅 UPDATE)
+                        │
+                        └── E14 (异步提交) ──────▶ [R15] CREATE,IN_PROGRESS / [R19] UPDATE,INP
+                                                       │
+                                                       ├── (轮询成功) ──▶ [R16] / [R20] SUCCESS
+                                                       └── E15 (超时)  ──▶ [R17] / [R21] FAILED
+```
+
+**转换表：**
+
+| 事件 | 起始状态 | 判断条件 (Guard) | 结束状态 | 副作用 |
+|------|---------|-----------------|---------|--------|
+| **E12**: SYNC_OK | R14 或 R18 | Handler API 返回 SUCCESS | R16 (CREATE) 或 R20 (UPDATE) | error → None; data_id 回填 (CREATE); origin_data 更新 (UPDATE) |
+| **E13**: SYNC_FAIL | R14 或 R18 | Handler API 返回 FAILED | R17 (CREATE) 或 R21 (UPDATE) | error = Handler 返回的错误信息 |
+| **E14**: SYNC_ASYNC | R14 或 R18 | Handler API 返回 IN_PROGRESS | R15 (CREATE) 或 R19 (UPDATE) | 记录 task_id, 进入轮询队列 |
+| **E15**: SYNC_TIMEOUT | R15 或 R19 | 轮询次数 > max_retries | R17 (CREATE) 或 R21 (UPDATE) | error = "Async task timeout after N seconds" |
+| **E16**: HANDLER_SKIP | R14 或 R18 | Handler API 返回 SKIPPED | R23 (CREATE,SKIPPED) | error → None |
+| **E17**: HANDLER_DOWNGRADE | R18 (仅 UPDATE) | Handler 运行时发现无实际变更字段 | R6 (NORMAL, NONE, PENDING) | action: UPDATE → NONE; 不提交 API; 统计列从 update 移入 none |
+
+> **代码**: `BaseDataSource._handle_task_result()` · `_poll_async_tasks()` · `domain/*/api_handler.py`
+
+---
+
+## §4 终态分类与死胡同
+
+### §4.1 终态分类
+
+| 分类 | 状态 | (binding_status, action, status) | 语义 | 下一轮行为 |
+|------|------|------|------|---------|
+| ✅ 成功 | R16 | (NORMAL, CREATE, SUCCESS) | 创建成功 | →R2→bind→R7→update 检查 |
+| ✅ 成功 | R20 | (NORMAL, UPDATE, SUCCESS) | 更新成功 | →R2→bind→R7→update 检查 |
+| ❌ 失败 | R17 | (NORMAL, CREATE, FAILED) | 创建失败 | E02 zombie 判定→删除节点→对方回到 R9 重建 |
+| ❌ 失败 | R21 | (NORMAL, UPDATE, FAILED) | 更新失败 | →R3→bind→R8→FAILED 保护(E11e)→保持 |
+| 🔒 阻断 | R11 | (ABNORMAL, NONE, \*) | 数据损坏 | 每轮重新 bind 检查; 需人工修复数据 |
+| 🔒 阻断 | R12 | (WARNING, NONE, \*) | 多候选/对方异常 | 每轮重新 bind 检查; 需人工绑定或修复 |
+| 🔒 阻断 | R13 | (DEPENDENCY_ERROR, NONE, PENDING) | 依赖不满足 | 每轮重新检查依赖; 依赖修复后自动恢复 |
+| ⏭ 跳过 | R23 | (NORMAL, CREATE, SKIPPED) | Handler 跳过创建 | →R4→bind→R6→update 检查（无绑定则再 create） |
+| 🔄 异步 | R15 | (NORMAL, CREATE, IN\_PROGRESS) | 创建异步中 | 轮询直到 SUCCESS 或超时→FAILED |
+| 🔄 异步 | R19 | (NORMAL, UPDATE, IN\_PROGRESS) | 更新异步中 | 轮询直到 SUCCESS 或超时→FAILED |
+| 🔄 前置失败 | R22 | (NORMAL, UPDATE, PRECONDITION\_FAILED) | 前置条件不满足 | →R5→bind→R6/R7→update 重试 |
+
+### §4.2 恢复路径
+
+```
+R17 (CREATE, FAILED):
+    持久化 → 下轮 E01 → 瞬态(UNCHECKED, CREATE, FAILED)
+    → E02: action=CREATE ∧ (status=FAILED ∨ data_id="") → 满足 zombie 条件
+    → 删除节点 + 解除绑定
+    → 对方节点回到 R9 (MISSING) → 重新进入 create 流程
+
+R21 (UPDATE, FAILED):
+    持久化 → 下轮 E01 → 瞬态(UNCHECKED, UPDATE, FAILED)
+    → E02: action=UPDATE ≠ CREATE → 非 zombie，存活
+    → E03: action → NONE → R3 (UNCHECKED, NONE, FAILED)
+    → bind → R8 (NORMAL, NONE, FAILED)
+    → E11e: FAILED 保护 → 跳过 update → 保持 R8
+    ⚠ 需人工清除 FAILED 才能恢复
+
+R22 (UPDATE, PRECONDITION_FAILED):
+    持久化 → 下轮 E01 → 瞬态(UNCHECKED, UPDATE, PRECONDITION_FAILED)
+    → E02: action=UPDATE ≠ CREATE → 非 zombie，存活
+    → E03: action → NONE → R5 (UNCHECKED, NONE, PRECONDITION_FAILED)
+    → bind → R6/R7 (NORMAL) → update 流程重试
+
+R11 (ABNORMAL):
+    每轮 E01 重置 → bind 重新检查
+    → 若数据被人工修复 → E04 → R6/R7/R8 (NORMAL)
+    → 若数据仍损坏 → 再次 R11
+
+R12 (WARNING):
+    每轮 E01 重置 → bind 重新检查
+    → 若人工建立了绑定 → E04 → R6/R7 (NORMAL)
+    → 若对方数据被修复 → E04 → R6/R7 (NORMAL)
+
+R13 (DEPENDENCY_ERROR):
+    每轮 E01 重置 → bind 重新检查依赖
+    → 依赖节点达到 NORMAL 且 data_id 非空后
+    → E07 通过 → 继续 auto_bind 或 create 流程
+```
+
+### §4.3 FAILED 保护机制详解
+
+FAILED 保护确保失败节点不会被后续流程静默覆盖，保留 error 信息供人工调查。
+
+```
+进入条件:
+    节点经过 bind 后为 R8 (NORMAL, NONE, FAILED)
+    即: 绑定关系正常，但上一轮执行失败
+
+保护行为:
+    `strategy_ops/update_ops.py::add_update_action()` 中:
+        if source.status == SyncStatus.FAILED:
+            skip  (→ 事件 E11e)
+    结果: R8 原样保持 → 持久化 → 下一轮依然 R8
+
+解除条件 (需人工介入):
+    1. 清除 error 字段 (→ None)
+    2. 将 status 改为 PENDING 或 SUCCESS
+    3. 下轮 bind 后 → R6 或 R7 → 正常进入 update 流程
+```
+
+---
+
+## §5 完备性分析
+
+### §5.1 状态 × 事件矩阵
+
+行 = 当前状态，列 = 可能触发的事件。`→Rx` = 转换到目标状态，`—` = 不可能触发。
+
+| 状态 | E01 | E02 | E03 | E04/E05 | E06~E10 | E11a/b | E11c/d/e | E12~E17 |
+|------|-----|-----|-----|---------|---------|--------|----------|---------|
+| R1~R5 | — | — | — | →R6~R13 | — | — | — | — |
+| R6/R7 | →瞬态 | — | — | — | — | — | →R18/R22 | — |
+| R8 | →瞬态 | — | — | — | — | — | →R8(skip) | — |
+| R9 | →瞬态 | — | — | — | →R6/R11~R13 | →R6+R14/R13 | — | — |
+| R11~R13 | →瞬态 | — | — | — | — | — | — | — |
+| R14 | →瞬态 | — | — | — | — | — | — | →R15~R17/R23 |
+| R15 | →瞬态 | — | — | — | — | — | — | →R16/R17 |
+| R18 | →瞬态 | — | — | — | — | — | — | →R6/R19~R21/R23 |
+| R19 | →瞬态 | — | — | — | — | — | — | →R20/R21 |
+| R16/R17 | →瞬态 | — | — | — | — | — | — | — |
+| R20~R23 | →瞬态 | — | — | — | — | — | — | — |
+
+> **读表方式**: 找到当前状态行和事件列组的交叉点，即可得到目标状态。`—` 表示该状态不可能触发该事件。
+
+### §5.2 已知 GAP
+
+| GAP | 描述 | 风险 | 建议 |
+|-----|------|------|------|
+| GAP-1 | `set_binding_status()` / `set_action()` / `set_status()` 是纯 setter，不验证转换合法性 | 中 | 加入前置断言：检查 (当前状态, 新状态) 是否匹配某条已知转换 |
+| GAP-2 | INV-1 ~ INV-10 未在代码中 assert | 中 | 每次 setter 调用后或阶段结束时断言所有不变量 |
+| GAP-3 | R22 (PRECONDITION\_FAILED) 节点下一轮行为路径需验证 | 低 | 已补充恢复路径: R22→E01→E03→R5→bind→R6/R7→update 重试 |
+| GAP-4 | Handler 降级 (E17) 后 status 残留为 PENDING 但 action 已清零 | 低 | 可考虑降级时同时重置 status 为 SUCCESS（当前保持 PENDING） |
+| GAP-5 | 物理同步后缺少整体一致性检查 (post-sync invariant check) | 低 | 在 `sync_all()` 结束后遍历所有节点验证 INV-1 ~ INV-10 |
+
+---
+
+## §6 引用
+
+| 文档 | 路径 |
+|------|------|
+| 枚举定义 | `sync_system_new/common/types.py` |
+| 决策引擎 | `sync_system_new/sync_system/decision.py` |
+| 重置策略 | `sync_system_new/common/state_reset.py` |
+| 同步策略 | `sync_system_new/sync_system/strategy.py` |
+| 物理同步 | `sync_system_new/datasource/datasource.py` |
+| ID 解析 | `sync_system_new/sync_system/resolve_ids.py` |
+| 节点生命周期(叙事) | [节点生命周期状态转移](./节点生命周期状态转移.md) |