ecm_sync_system/docs/runtime_config_guide.md

运行配置业务说明

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

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）。
• target_project_ids
  • 兼容字段。作为两侧 datasource 的项目白名单兜底值。
  • 若 datasource 自身配置了 target_project_ids，则优先使用 datasource 级配置。
• local_datasource / remote_datasource
  • 分别定义两侧数据来源与执行端。
• strategies
  • 每个业务类型的行为策略（依赖、自动绑定、创建方向、更新方向、跳过等）。
• persist
  • 持久化开关与数据库位置。
• logging
  • 运行日志输出位置与级别。

3. 数据源字段（DataSource）

3.1 JSONL 数据源

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

3.2 API 数据源

• type=api：对接 HTTP API。
• api_base_url / api_uid / api_secret：接口访问参数。
• api_debug：开启后输出更多调试信息。
• poll_max_retries / poll_interval：异步任务轮询次数与间隔。
• target_project_ids：必填，该侧项目白名单；至少需要指定一个项目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 理解含义。