first commit
This commit is contained in:
strepsiades
@@ -0,0 +1,112 @@
|
||||
# 架构分层设计：四层模型
|
||||
|
||||
本架构旨在将同步系统的**数据容器**、**同步逻辑**、**执行层**与**编排流程**完全解耦，提供极简且类型安全的开发体验。
|
||||
|
||||
---
|
||||
|
||||
## 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）灵活控制同步行为。
|
||||
Reference in New Issue
Block a user