# 运行配置业务说明

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

## 1. 推荐使用方式（先 default，再覆盖）

1. 先使用基线配置运行：
  - `run_profiles/preset/jsonl_to_jsonl.default.yaml`
2. 若需项目定制，再复制为：
   - `run_profiles/jsonl_to_jsonl.local.yaml`
3. 仅改有业务差异的字段，避免一次改太多导致排障困难。

占位符：
- `${PROJECT_ROOT}` 会在运行时替换为项目根目录绝对路径。

## 2. 顶层字段（你在改什么）

- `node_types`
  - 本轮参与同步的业务类型列表。
  - 顺序会影响依赖链执行时机（当前按 node_type 串行执行 bind/create/update）。
- `local_datasource` / `remote_datasource`
  - 分别定义两侧数据来源与执行端。
- `strategies`
  - 每个业务类型的行为策略（依赖、自动绑定、创建方向、更新方向、跳过等）。
- `persist`
  - 持久化开关与数据库位置。
- `logging`
  - 运行日志输出位置与级别。

## 3. 数据源字段（DataSource）

### 3.1 JSONL 数据源

- `type=jsonl`：使用本地 JSONL 文件作为数据源。
- `jsonl_dir`：JSONL 目录路径。
- `read_only=false`：允许该侧执行 create/update 回写；若为 true，通常用于只读加载。
- `handler_configs.project.data_id_filter=[]`：项目白名单；为空时不进行项目筛选。
- `handler_configs`：按节点类型下发给各业务 handler 的扩展参数。

### 3.2 API 数据源

- `type=api`：对接 HTTP API。
- `api_base_url` / `api_uid` / `api_secret`：接口访问参数。
- `api_debug`：开启后输出更多调试信息。
- `poll_max_retries` / `poll_interval`：异步任务轮询次数与间隔。
- `handler_configs.project.data_id_filter`：建议显式配置的项目白名单；至少需要指定一个项目ID，以避免加载过多远程数据。
- `handler_configs`：业务 handler 扩展参数。

## 4. 策略字段（Strategy）

每个 node_type 都建议显式写出以下字段，便于审阅与排障。

### 4.1 `update_direction`

- `push`：本地变更推送到远端。
- `pull`：远端变更拉取到本地。
- `bidirectional`：双向更新（需要明确冲突策略，谨慎使用）。
- `none`：关闭 update 阶段。

### 4.2 `local_orphan_action` / `remote_orphan_action`

- `create_remote`：本地孤儿创建到远端。
- `create_local`：远端孤儿创建到本地。
- `none`：不自动创建。
- `delete_local` / `delete_remote`：当前主流程未作为默认路径，谨慎使用。

### 4.3 `auto_bind` / `auto_bind_fields` / `pre_bind_data_id`

- `auto_bind=true`：在 `S02(MISSING)` 上尝试自动匹配。
- `auto_bind=false`：不会做自动匹配，也不会走自动创建识别路径；通常会进入阻断态等待人工处理。
- `auto_bind_fields`：自动匹配使用的业务键字段。
- `pre_bind_data_id`：显式 data_id 预绑定清单（通用能力），格式为：
  - `- local_data_id: "..."`
    `  remote_data_id: "..."`
  - 规则：若两侧数据源都存在这对 data_id 对应节点，且当前无绑定记录，则直接绑定。
  - 不依赖 `auto_bind/auto_bind_fields`，即使 `auto_bind=false` 也会执行。
  - 不做业务键一对一匹配检查，按你给定的映射对优先执行。

### 4.4 `depend_fields`

- 定义依赖字段到依赖 node_type 的映射，例如：`company_id -> company`。
- 依赖节点状态非 `NORMAL` 时，会在 bind 的依赖检查阶段进入 `DEPENDENCY_ERROR`。

### 4.5 `skip_sync`

- 运行配置中已不建议使用 `skip_sync`。
- 推荐使用显式组合：
  - `local_orphan_action: none`
  - `remote_orphan_action: none`
  - `update_direction: none`
- 当三者同时为 `none/none/none` 时，pipeline 会跳过该 node_type 的 bind/create/update。

### 4.6 Handler 级参数（`handler_configs`）

- 建议将 handler 特有参数放在 datasource 的 `handler_configs.<node_type>` 下。
- 示例：
  - `remote_datasource.handler_configs.supplier.load_mode: persisted_only`
- `persisted_only` 表示只使用已持久化数据，不主动从外部拉新数据（具体以对应 handler 实现为准）。

## 5. 阶段行为与配置关系

- bind 阶段
  - `depend_fields` 决定是否做依赖校验。
  - `pre_bind_data_id` 先按显式 local/remote data_id 映射做预绑定。
  - `auto_bind/auto_bind_fields` 决定是否继续进行业务键自动绑定。
- create 阶段
  - `local_orphan_action` / `remote_orphan_action` 决定孤儿是否创建。
- update 阶段
  - `update_direction` 决定是否和向哪侧更新。
- 写入后 reload（Pipeline 内置）
  - 当某个 node_type 的 create 或 update 发生实际写入成功后，pipeline 会自动对该 node_type 重新执行两侧 `load`。
  - 目的：让后续 update 判断基于最新远端/本地数据，支持“create 后再补一次 update”的链路。
- 同步后一致性检查（Pipeline 内置）
  - 每个 node_type 在本轮同步后会基于绑定对执行数据一致性校验（比较时忽略 `id/_id` 字段）。
  - 若发现差异，会在日志中打印差异样本，并在汇总表新增 `Consistent` 列展示 `Y` / `N(差异数)`。
- 全局跳过
  - `local_orphan_action=none` + `remote_orphan_action=none` + `update_direction=none`
    可直接跳过该类型的 bind/create/update。

## 6. 覆盖配置建议

- 先在 default 跑通一轮，再做 local 覆盖。
- 每次只改一类问题相关字段（例如只改 `project` 的依赖与自动绑定）。
- 覆盖后优先看 `sync_log` 是否出现预期状态迁移。

## 7. 持久化与日志字段

### `persist`

- `enable`：是否开启持久化。
- `db_path`：SQLite 路径。
- `wipe_on_start`：启动是否清理历史持久化。

### `logging`

- `file_dir`：日志目录。
- `file_name_pattern`：文件命名模板。
- `level`：日志级别。

排障建议：运行失败时优先看日志中的 `状态机流转` 与 `reason=`，再对照 `docs/state_machine.md` 与 `docs/node_state_definition.md` 理解含义。