# 架构分层设计：四层模型

本架构旨在将同步系统的**数据容器**、**同步逻辑**、**执行层**与**编排流程**完全解耦，提供极简且类型安全的开发体验。

---

## 1. 架构概览

系统分为四层，依赖关系严格从上到下：

1.  **通用层 (Common)**: 定义纯数据结构（Data Container）和基础工具。
2.  **同步系统层 (Sync System)**: 定义同步行为接口（SyncStrategy）与业务规则。
3.  **数据源层 (DataSource)**: 实现数据的加载与持久化，属于盲目执行层。
4.  **编排层 (Pipeline)**: 应用层逻辑，硬编码同步顺序，协调 ID 映射与错误传播。

---

## 2. 通用层 (Layer 0: Common)

本层不包含业务逻辑，仅定义数据契约。

- **SyncNode[T]**: 核心状态机容器。
  - `origin_data`: 原始数据（对应 `data_id`）。
  - `data`: 计算后的最新目标数据。
  - `data_id`: 业务主键ID。加载时必定有值，CREATE 节点初始为空字符串 `""`（布尔值为 False，可通过校验）。
  - `action`: 同步意图 (NONE, CREATE, UPDATE, DELETE)。
  - `status`: 执行状态 (PENDING, IN_PROGRESS, SUCCESS, FAILED, SKIPPED, PRECONDITION_FAILED)。
    - 详见 [状态定义规范 § 5.A](./状态定义规范.md#5-执行同步状态转换-physical-sync-state-transitions)
  - `binding_status`: 绑定状态 (UNCHECKED, NORMAL, MISSING, DEPENDENCY_ERROR, ABNORMAL, WARNING)。
    - 详见 [状态定义规范 § 1](./状态定义规范.md#1-核心状态判定表-core-binding-matrix)
  - `error`: 异常详情。
- **DataCollection**: 节点的集合，提供类型安全的查询和过滤方法。
- **BindingManager**: 
  - **ID 映射**: 维护 `local_node_id` <-> `remote_node_id` 的双向映射。
  - **绑定键**: 使用 `node_id` 作为绑定记录的键，**一致不变**。CREATE 成功后只更新节点的 `data_id`，绑定记录不变。
  - **持久化**: 将映射关系持久化到存储（如 JSON/数据库）。
- **Enums**: `SyncAction`, `SyncStatus`, `BindingStatus` 等。

---

## 3. 同步系统层 (Layer 1: Sync System)

核心业务逻辑层。通过实现 `SyncStrategy` 接口来定义特定实体的同步逻辑。

- **SyncStrategy[T] 接口**:
  - `bind()`: 
    - 职责：判定 `binding_status` (NORMAL/MISSING/ABNORMAL/WARNING/DEPENDENCY_ERROR)
    - 详见 [状态定义规范 § 1-3](./状态定义规范.md)
  - `create()`:
    - 职责：处理孤儿节点（MISSING），在对方侧创建新节点并设置 `action=CREATE`
    - **ID 替换**: 创建新节点时，复制数据并将依赖字段的本地 ID 替换为远程 ID
    - **内联检查**: 通过 `IDResolver.resolve_and_validate()` 验证依赖 ID 解析
    - 详见 [状态定义规范 § 4.C](./状态定义规范.md)
  - `update()`:
    - 职责：处理差异节点（NORMAL 且有 diff），设置 `action=UPDATE`
    - **ID 替换**: 准备更新数据时，替换数据中的依赖 ID
    - **内联检查**: 验证目标节点 data_id 完整性，失败则设置 `PRECONDITION_FAILED`
    - **FAILED 保护**: 自动跳过 `status=FAILED` 的节点
    - 详见 [状态定义规范 § 4.A](./状态定义规范.md)
---

## 4. 数据源层 (Layer 2: DataSource)

作为各个后端的适配器，负责数据加载与持久化。

- **职责**:
  - `load_nodes(node_type)`: 从后端加载并返回 `SyncNode` 集合，自动添加到 `DataCollection`。
  - `save_nodes(nodes)`: 
    - 遍历节点，仅处理 `status == PENDING` 且 `action != NONE` 的节点。
    - 根据 `action` 执行相应的 CREATE/UPDATE/DELETE 操作。
    - 执行成功后，更新节点的 `status` 和相关信息（如新生成的 remote_id）。

---

## 5. 编排层 (Layer 3: Pipeline)

最高层级，负责流程编排。

- **职责**:
  - **显式顺序**: 直接在代码中按顺序调用同步逻辑（例如：先同步项目，再同步合同）。
  - **故障传播**: 若前置实体某节点同步失败（`FAILED`），编排器在处理后续依赖节点时可将其标记为 `DEPENDENCY_ERROR`。
  - **生命周期管理**: 初始化 `BindingManager` 和 `DataCollection`，同步结束后调用持久化方法。

---

## 6. ID 映射与对齐：核心流程

为了解决本地数据引用本地 ID 与远程数据引用远程 ID 的冲突，系统采用以下映射逻辑：

### 绑定阶段 (Binding)
- **时机**: `Strategy.bind`
- **目标**: 在 `BindingManager` 中确定 local_id ↔ remote_id 映射
- **手段**: 业务键匹配（如 Code 匹配）、历史记录恢复等

### 执行阶段 (Execution)
- **时机**: `Strategy.create()` / `Strategy.update()` 阶段
- **目标**: 在创建新节点或准备更新时，将依赖字段的本地 ID 替换为远程 ID
- **手段**: 
  - `create()`: 创建对方节点时，复制数据并替换所有依赖 ID
  - `update()`: 准备更新数据时，替换数据中的依赖 ID
- **验证**: `_pre_commit_check` 在 create/update 最后检查，确保所有依赖节点都已有远程 ID

**注意**: ID 替换在 Strategy 的 create/update 阶段完成，DataSource 只负责盲目执行已准备好的数据。

---

## 7. 关键设计原则

- **删除类型依赖配置**: 依赖关系通过 `Pipeline` 中的代码调用顺序自然表达。
- **无状态 DataSource**: 数据源不了解绑定逻辑，只看到 `action`、`status` 和 `binding_status`。
- **BindingManager 为核心**: 负责 ID 空间映射和持久化。
- **配置驱动**: 通过 `StrategyConfig` 和预设配置（ConfigPresets）灵活控制同步行为。