fleur-dagster-backfill-runbook

DG 回填手册

当 pipeline/scheduler 里的回填可以用 dg launch 表达时，使用这个 skill。

规则

• 所有 dg / dagster 命令必须使用根目录 .env 中的 DAGSTER_HOME 作为 Dagster home
• 执行前先在仓库根目录加载 .env：set -a; . ./.env; set +a
• 运行回填前先执行 make dagster-home，确保 Dagster home 和 pool 限制已初始化
• 在 pipeline/ 下执行命令
• 使用 uv run dg ...
• 通过 --target-path scheduler 指向 scheduler 项目
• 临时回填优先用明确的 asset selection
• 只有当 job 和目标工作负载完全一致时才用 job

流程

1. Source 到 ClickHouse raw 的手动修复优先使用统一 raw-only 入口 backfill__fetch_history_sources_to_raw_job。
2. Snapshot reference data 也使用 backfill__fetch_history_sources_to_raw_job；start_date 和 end_date 仍必填，但该 scope 会主动忽略日期。
3. 历史 source/raw 修复后需要继续推进 dbt、Furnace 和 marts 时，使用 backfill__fetch_history_sources_to_marts_job。
4. 日常 source/raw/downstream 主入口使用 daily__fetch_history_sources_to_marts_schedule_job；它不是 history backfill，但复用 source-to-marts registry，把 target_date 映射为单日增量。
5. Jiuyan 异动、行业列表、图片/OCR/OCR snapshot 后续单独设计 job；不纳入本轮统一 source-to-marts 回填模板或 daily source-to-marts 入口。
6. 只有调试单个资产、验证单个分区或统一入口暂不覆盖的临时操作，才使用精确 asset selection。
7. 判断目标是否分区。
8. 从 references/backfill-matrix.md 里选命令模板。
9. 需要时先用 uv run dg list defs --target-path scheduler --json 验证选择。
10. 先跑 dry_run: true，确认计划后再执行真实回填或真实 daily run。

统一 Source/Raw 回填入口

raw-only 首选手动入口：

cd pipeline
uv run dg launch --target-path scheduler \
  --job backfill__fetch_history_sources_to_raw_job \
  --config-json '{
    "ops": {
      "backfill__fetch_history_sources_to_raw_controller": {
        "config": {
          "target_scope": "baostock_daily_kline",
          "start_date": "2026-01-01",
          "end_date": "2026-06-30",
          "execution_mode": "full",
          "refresh_prerequisite_snapshots": false,
          "overwrite_source_partitions": false,
          "dry_run": true
        }
      }
    }
  }'

raw-only target_scope：

• baostock_daily_kline
• market_events（只纳入 THS limit up pool；Jiuyan 异动不进入统一 raw-only 或 source-to-marts 入口）
• eastmoney_f10
• chinabond
• snapshot_reference_data（日期字段必填，但该 scope 忽略日期）
• all_raw_yearly