feat(airflow): добавлен пульт управления генератором

- Зачем:
  - нужен основной ручной интерфейс стенда для backfill/import/check без консольной матрицы переменных.
- Что:
  - добавлен DAG generator_control с параметрами Airflow, ветвлением операций и ожиданием ETL.
  - вынесена общая логика запуска и предпроверок генератора для Airflow.
  - обновлены compose-настройки, зависимости, тесты и документация по пульту.
- Проверка:
  - uv run --with pytest --with-requirements generator/requirements.txt pytest generator/tests -q.
  - docker compose config --quiet.

docs/OPERATIONS.md

@@ -37,9 +37,31 @@
 
 ## Airflow DAGs
 
-Штатный аналитический путь больше не начинается с `kafka_load`: чистый стенд
-получает данные из стартовой истории генератора. DAG-и ниже остаются для
-ручных экспериментов, отладки и совместимости учебного стенда.
+Штатный ручной путь начинается с `generator_control`: чистый стенд получает
+стартовую историю генератора, затем этот же DAG запускает ETL и проверку.
+`kafka_load` остаётся для экспериментов и совместимости учебного стенда.
+
+### `generator_control`
+
+- Запуск: ручной (`Trigger DAG`).
+- Назначение: пульт стартовой истории генератора.
+- Операции:
+  - `backfill` — создать стартовую историю, затем запустить `etl_pipeline` и
+    дождаться `success`;
+  - `import` — импортировать портативный артефакт, затем запустить
+    `etl_pipeline` и дождаться `success`;
+  - `check` — сверить ClickHouse с manifest из Kafka.
+- Параметры:
+  - `operation` (`backfill` / `import` / `check`);
+  - `profile` — список берётся из `PROFILES` генератора;
+  - `duration` — `6h`, `2d` и т.п.; пусто означает длительность профиля;
+  - `seed`, `model_time_speed` — необязательные переопределения мира;
+  - `artifact_path` — для `backfill` путь сохранения, для `import` путь чтения.
+
+Backfill/import требуют чистый стенд: пустые data-топики Kafka и пустые
+`stg.*_raw`. При отказе очистите стенд через `make clean`. Операции `continue`
+в DAG нет: live-генератор — долгоживущий сервис, его запускают с консоли через
+`make generator-continue`.
 
 ### `ddl_init`
 
@@ -81,12 +103,17 @@
 
 ## Генератор событий (автономный стриминг)
 
-Автономный сервис для непрерывной генерации событий в Kafka. Работает независимо от Airflow DAGs.
+Автономный сервис для непрерывной генерации событий в Kafka. Работает независимо
+от Airflow DAGs. `make up` его не запускает: live включается только явной
+командой.
 
 ### Управление
 
 ```bash
-# Запустить генератор
+# Продолжить live-поток из state
+make generator-continue
+
+# Запустить генератор с текущими env напрямую
 make generator-up
 
 # Остановить генератор

docs/runbooks/startup-history.md

@@ -34,6 +34,46 @@
 Длительность можно переопределить через `GEN_HISTORY_DURATION`, например `2d`.
 Команда сама считает `GEN_MODEL_T_END` от `GEN_MODEL_T0`.
 
+## Пульт в Airflow
+
+Основной ручной путь — DAG `generator_control` в Airflow UI:
+
+1. Поднимите стенд: `make up`.
+2. Если DDL ещё не применён, запустите `ddl_init`.
+3. Откройте `generator_control` и выберите `operation`.
+
+Операции:
+
+- `backfill` — создать стартовую историю. После записи в Kafka DAG сам запускает
+  `etl_pipeline`, ждёт завершения и выполняет `check`.
+- `import` — прочитать артефакт из `artifact_path`. Несовместимый артефакт
+  отклоняется до записи в Kafka.
+- `check` — сверить ClickHouse с manifest из Kafka.
+
+Поля формы:
+
+- `profile` берётся из профилей генератора.
+- `duration` можно оставить пустым, тогда берётся длительность профиля.
+- `seed` и `model_time_speed` — необязательные переопределения мира.
+- `artifact_path`: для `backfill` — куда сохранить файл; пусто — не сохранять.
+  Для `import` — что читать; пусто — `/opt/airflow/data/startup-history-import.json`.
+
+Backfill и import работают только на чистом стенде. Если Kafka-топики данных или
+STG уже непустые, DAG упадёт до записи и подскажет `make clean`. Это защита от
+смешивания разных миров.
+
+Границы пульта:
+
+- `make up`, `make clean` и live-продолжение остаются в консоли.
+- Операции `continue` в DAG нет намеренно: live — долгоживущий сервис, а пульт
+  управляет разовыми пакетными операциями.
+- Airflow не получает доступ к жизненному циклу контейнеров; таски выполняют обычный
+  Python-код генератора.
+
+Если backfill сохраняет файл в `./data`, он создаётся пользователем Airflow
+внутри контейнера. Чтение работает из Airflow и консольных команд, но перезапись
+чужого файла может потребовать удалить старый файл вручную.
+
 ## Экспорт
 
 По умолчанию создаётся быстрый 6-часовой артефакт:
@@ -103,5 +143,9 @@ PROFILE=ci make generator-continue
 полей. Это защита от смешения разных миров. Для намеренного нового мира
 используйте `make generator-reset` или `make clean`.
 
+После нестандартного мира `make generator-continue` нужно запускать с теми же
+настройками, что были у backfill/import. При расхождении генератор громко
+покажет поля, которые не совпали.
+
 Старые переменные `GEN_RUN_MODE`, `GEN_STATE_RESET` и `GEN_MODEL_T_END` остаются
 низкоуровневым способом для отладки и прямого `docker compose run`.