多pipeline同步支持

2026-03-23 21:02:52 +08:00
parent 0812489f9d
commit b51ed0175b
49 changed files with 2110 additions and 792 deletions
@@ -2,6 +2,91 @@

 本文档从业务视角说明配置字段含义、对阶段行为的影响，以及推荐的覆盖方式。

+## 0. 配置约定
+
+当前运行配置分成两层：
+
+1. 输入配置
+   - 你写在 `run_profiles/*.yaml` 或 `run_profiles/preset/*.default.yaml` 里的内容。
+   - 只建议写必要覆盖项，不要把默认值全部展开。
+2. Resolved Full Config
+   - pipeline 启动时打印并写入日志的全量配置。
+   - 其中已经补齐 datasource 默认值、策略默认值和日志/持久化默认值。
+
+也就是说：
+- 模板应当尽量短。
+- 排障时看启动日志里的 **Resolved Full Config**。
+
+### 0.1 一个最小输入示例
+
+```yaml
+local_datasource:
+  type: jsonl
+  jsonl_dir: ${PROJECT_ROOT}/filtered_datasource/datasource/filtered
+remote_datasource:
+  type: jsonl
+  jsonl_dir: ${PROJECT_ROOT}/remote_datasource/datasource
+persist:
+  db_path: ${PROJECT_ROOT}/test_results/sync_state_machine/demo.db
+strategies:
+  project:
+    config:
+      auto_bind: true
+      auto_bind_fields:
+        - name
+```
+
+### 0.2 对应的全量 resolved 结果骨架
+
+```yaml
+node_types:
+  - company
+  - supplier
+  - user
+  - project
+  ...
+local_datasource:
+  type: jsonl
+  jsonl_dir: /abs/path/filtered_datasource/datasource/filtered
+  read_only: false
+  handler_configs: {}
+remote_datasource:
+  type: jsonl
+  jsonl_dir: /abs/path/remote_datasource/datasource
+  read_only: false
+  handler_configs: {}
+strategies:
+  - node_type: project
+    skip_sync: false
+    config:
+      auto_bind: true
+      auto_bind_fields:
+        - name
+      pre_bind_data_id: []
+      depend_fields:
+        company_id: company
+      local_orphan_action: create_remote
+      remote_orphan_action: none
+      update_direction: push
+      field_direction_key: null
+      field_direction_overrides: {}
+      post_check_ignore_fields: []
+      compare_ignore_fields: []
+persist:
+  backend: sqlite
+  db_path: /abs/path/test_results/sync_state_machine/demo.db
+  backend_options: {}
+  enable: true
+  wipe_on_start: false
+logging:
+  initialize: true
+  file_path: null
+  file_dir: null
+  file_name_pattern: null
+  level: 20
+  suppress_node_logs: true
+```
+
 ## 1. 推荐使用方式（先 default，再覆盖）

 1. 先使用基线配置运行：
@@ -48,7 +133,7 @@

 ## 4. 策略字段（Strategy）

-每个 node_type 都建议显式写出以下字段，便于审阅与排障。
+每个 node_type 的 **Resolved Full Config** 都会包含以下字段，但输入配置不需要全部显式写出。

 ### 4.1 `update_direction`

@@ -97,6 +182,32 @@
  - `remote_datasource.handler_configs.supplier.load_mode: persisted_only`
 - `persisted_only` 表示只使用已持久化数据，不主动从外部拉新数据（具体以对应 handler 实现为准）。

+### 4.7 `field_direction_key` / `field_direction_overrides`
+
+- 这两个字段只在少数 node_type 上需要，典型例子是 `project_detail_data`。
+- `field_direction_key`
+  - 指定从节点 data 里取哪个字段作为“方向查表键”。
+  - 例如 `key`，表示用 `data["key"]` 决定这条记录是 push 还是 pull。
+- `field_direction_overrides`
+  - 指定“字段值 -> 更新方向”的映射。
+  - 没命中的值继续使用默认 `update_direction`。
+
+示例：
+
+```yaml
+project_detail_data:
+  config:
+    field_direction_key: key
+    field_direction_overrides:
+      ensure_production: pull
+      climb_production: pull
+      challenge_production: pull
+```
+
+含义：
+- `key=ensure_production/climb_production/challenge_production` 时，从远端拉回本地。
+- 其余 key 继续按默认 `update_direction=push` 处理。
+
 ## 5. 阶段行为与配置关系

 - bind 阶段
@@ -108,8 +219,9 @@
 - update 阶段
  - `update_direction` 决定是否和向哪侧更新。
 - 写入后 reload（Pipeline 内置）
-  - 当某个 node_type 的 create 或 update 发生实际写入成功后，pipeline 会自动对该 node_type 重新执行两侧 `load`。
-  - 目的：让后续 update 判断基于最新远端/本地数据，支持“create 后再补一次 update”的链路。
+  - 对 API / 需要重新拉取权威状态的数据源，create 或 update 成功后仍会按 node_type reload。
+  - 对纯 JSONL -> JSONL pipeline，reload 会跳过，直接复用当前内存状态。
+  - 目的：避免对离线 JSONL 数据做无意义重复扫描，同时保留 API 数据源的权威状态刷新。
 - 同步后一致性检查（Pipeline 内置）
  - 每个 node_type 在本轮同步后会基于绑定对执行数据一致性校验（比较时忽略 `id/_id` 字段）。
  - 若发现差异，会在日志中打印差异样本，并在汇总表新增 `Consistent` 列展示 `Y` / `N(差异数)`。