feat(airflow): пульт стал world_init, добавлен DAG world_next_day (#4)

- Зачем:
  - список DAG'ов должен читаться лесенкой ddl_init → world_init →
    world_next_day, а путь менти — проходиться пустыми формами
    (issue #4, спека редизайна пути менти, решения 2–3).
- Что:
  - generator_control переименован в world_init, дефолт операции —
    import; next-day ушёл из выпадашки в отдельный DAG;
  - новый беспараметрный world_next_day: расписание */30 * * * *,
    создаётся на паузе, catchup=False, max_active_runs=1; общие
    задачи вынесены в airflow/dags/utils/startup_history_tasks.py;
  - доки и контрактные тесты обновлены синхронно; быстрый старт
    README — без make ddl, схему создаёт DAG ddl_init.
- Проверка:
  - make test (210 + 31) и make lint зелёные;
  - живая приёмка на чистом стенде: world_init пустой формой
    импортировал эталонный мир за 217 с (3 дня, 280 437 событий),
    world_next_day после снятия с паузы добавляет ровно один день
    за прогон, дашборд Superset собирается.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-22 21:45:02 +03:00
co-authored by Claude Fable 5
parent 76ff669cf7
commit ac7a973504
12 changed files with 268 additions and 192 deletions
+28 -17
View File
@@ -27,8 +27,9 @@
flowchart LR
subgraph AF["Airflow"]
DAG1["ddl_init"]
DAG2["generator_control"]
DAG3["etl_pipeline"]
DAG2["world_init"]
DAG3["world_next_day"]
DAG4["etl_pipeline"]
end
subgraph GEN["Generator"]
@@ -57,7 +58,8 @@ flowchart LR
V[витрины VIEW]
end
DAG2 -->|startup-history backfill/import| K
DAG2 -->|import/backfill| K
DAG3 -->|следующий день| K
G -->|live после make generator-continue| K
K -->|MV| S
S -->|batch| O
@@ -66,12 +68,13 @@ flowchart LR
D1 & D2 -->|VIEW| V
DAG1 -.->|DDL| STG & ODS & DDS & DM
DAG3 -.->|batch| ODS & DDS
DAG4 -.->|batch| ODS & DDS
```
В учебном стенде предусмотрены два пути загрузки:
- `startup-history`: DAG `generator_control` создаёт или импортирует историю, добавляет следующий модельный день, запускает ETL и проверяет витрины;
- `startup-history`: `world_init` импортирует или создаёт историю, а
`world_next_day` добавляет один модельный день; оба запускают ETL и проверяют витрины;
- `live`: генератор запускается явно через `make generator-continue`, когда нужна непрерывная подача новых событий.
### Слои и их назначение
@@ -80,8 +83,9 @@ flowchart LR
flowchart LR
subgraph AF["Airflow"]
DAG1["ddl_init"]
DAG2["generator_control"]
DAG3["etl_pipeline"]
DAG2["world_init"]
DAG3["world_next_day"]
DAG4["etl_pipeline"]
end
subgraph GEN["Generator"]
@@ -106,7 +110,8 @@ flowchart LR
DM_T["VIEW"]
end
DAG2 -->|startup-history| KAFKA
DAG2 -->|стартовый мир| KAFKA
DAG3 -->|следующий день| KAFKA
G -->|live| KAFKA
KAFKA -->|MV| STG_T
STG_T -->|batch| ODS_T
@@ -114,7 +119,7 @@ flowchart LR
ODS_T -.->|ошибки| DQ
DAG1 -.->|DDL| L1 & L2 & L3 & L4
DAG3 -.->|batch| ODS_T & DDS_T
DAG4 -.->|batch| ODS_T & DDS_T
```
---
@@ -387,10 +392,12 @@ sequenceDiagram
CH-->>User: ✅ Структура БД создана
alt Startup-history режим
User->>Airflow: Trigger generator_control (backfill/import)
User->>Airflow: Trigger world_init с пустой формой
Airflow->>K: события стартовой истории
Airflow->>Airflow: trigger etl_pipeline + check
K-->>User: ✅ История в Kafka и витринах
User->>Airflow: Trigger world_next_day с пустой формой
Airflow->>K: события следующего модельного дня
else Live режим
User->>Compose: make generator-continue
loop каждые 1-10 секунд
@@ -637,7 +644,8 @@ INSERT INTO dm.daily_traffic SELECT * FROM dm.v_daily_traffic;
```python
# airflow/dags/ddl_init_dag.py — создание баз/таблиц
# airflow/dags/generator_control_dag.py — backfill/import/next-day/check стартовой истории
# airflow/dags/world_init_dag.py — import/backfill/check стартового мира
# airflow/dags/world_next_day_dag.py — добавление одного модельного дня
# airflow/dags/etl_pipeline_dag.py — основной ETL (STG→ODS→DDS→DM)
# airflow/dags/kafka_load_dag.py — архивный ручной путь из JSONL, не основной контур
@@ -645,22 +653,25 @@ INSERT INTO dm.daily_traffic SELECT * FROM dm.v_daily_traffic;
# - DDL и трансформации выполняются явными SQL-task через ClickHouseOperator;
# - SQL-файлы вызываются по фиксированным путям;
# - загрузка может идти двумя путями:
# 1) startup-history через DAG `generator_control`;
# 1) стартовый мир через `world_init` и рост через `world_next_day`;
# 2) live-поток через явный `make generator-continue`.
#
# Базовый demo-сценарий:
# ddl_init -> generator_control(backfill/import) -> etl_pipeline -> check
# ddl_init -> world_init(import) -> etl_pipeline -> check
# Расширенный учебный сценарий:
# make generator-continue + периодический etl_pipeline
```
**DAG `generator_control`**:
- `backfill`: создаёт стартовую историю через генератор
- `import`: импортирует портативный артефакт стартовой истории
- `next-day`: пакетно добавляет следующий модельный день от текущего слепка мира
**DAG `world_init`**:
- `import` по умолчанию импортирует портативный артефакт стартового мира
- `backfill` создаёт стартовую историю через генератор
- `check`: сверяет ClickHouse с manifest стартовой истории
- После `backfill` и `import` запускает `etl_pipeline` с `full_refresh`
**DAG `world_next_day`** без параметров пакетно добавляет следующий модельный
день, запускает `etl_pipeline` с `full_refresh` и сверяет manifest. У него задано
расписание каждые 30 минут, но DAG создаётся на паузе и не выполняет пропущенные интервалы.
**Подключение к ClickHouse:**
- Connection: `clickhouse_default`
- URL: `clickhouse://default:123456@clickhouse:9000/default` (native TCP для Airflow plugin)