# Airflow: настройка пайплайна отчетов по миграциям

DAG: `dags/migration_reporter_dag.py` — расписание **Пн / Ср / Пт 08:00** (`0 8 * * 1,3,5`).

Граф задач:

```
pull_repo → generate_excel → generate_html
```

Скрипт пайплайна: `migration_reporter.py` (лежит в корне репозитория миграций).

---

## 1. Установка Airflow 3 (docker-compose)

В каталоге проекта Airflow (например, `/projects/airflow-docker`) — по официальной документации
https://airflow.apache.org/docs/apache-airflow/stable/howto/docker-compose/index.html

Файл `.env` там же:

```env
_AIP_UID=..
# дополнительные пакеты в контейнерах (быстрый способ для теста)
_PIP_ADDITIONAL_REQUIREMENTS=openpyxl
```

> Для постоянной работы лучше свой Dockerfile:
> ```dockerfile
> FROM apache/airflow:3.3.2
> RUN pip install openpyxl
> ```
> и в `docker-compose.yaml` в `image:` указать имя собранного образа
> (`docker build -t airflow-with-pydeps .`).

## 2. Volume-монтирования (репозиторий + папка отчетов)

В `docker-compose.yaml` в общий блок `x-airflow-common`:

```yaml
x-airflow-common: &airflow-common
  volumes:
    - ./dags:/opt/airflow/dags
    - ./config:/opt/airflow/config
    - ./logs:/opt/airflow/logs
    - ./plugins:/opt/airflow/plugins
    # путь на хосте (Windows) : путь в контейнере
    - C:/Users/veremeytsev_dg/Desktop/migrations_tool:/opt/airflow/migrations_tool    # репозиторий миграций
    - C:/Users/veremeytsev_dg/Desktop/migrations_reports:/opt/airflow/reports         # общая папка отчетов
```

После этого перезапустить: `docker compose up -d`.

Дагфайл кладется в `./dags/migration_reporter_dag.py` (папка dags уже смонтирована).

## 3. Git-доступ из контейнера

На хосте Windows аутентификация работает через credential-manager — в контейнере его нет.
Два варианта (один раз, внутри контейнера):

```bash
# а) Токен в remote-url (быстро; хранить токен в Airflow Variable и клонировать им)
docker compose exec airflow-worker git clone \
  https://<user>:<token>@seedvault.coderocket.ru/SZA_analytics/migrations.git \
  /opt/airflow/migrations_tool

# б) SSH-deploy key в volume (надежнее для продакшена)
# смонтировать ключ и: git -c core.sshCommand="ssh -i /opt/airflow/ssh/key" clone ...
```

Проверка: `docker compose exec airflow-worker git -C /opt/airflow/migrations_tool pull --ff-only`

## 4. Airflow Variables (пути)

В UI: Admin → Variables, либо CLI:

```bash
docker compose exec airflow-scheduler airflow variables set migrations_repo_dir /opt/airflow/migrations_tool
docker compose exec airflow-scheduler airflow variables set migrations_reports_dir /opt/airflow/reports
```

Можно не задавать — в DAG есть env-fallback (`MIGRATIONS_REPO_DIR`, `MIGRATIONS_REPORTS_DIR`).

## 5. Запуск и проверка

```bash
docker compose exec airflow-scheduler airflow dags list
docker compose exec airflow-scheduler airflow dags trigger migration_reporter_pipeline
docker compose exec airflow-scheduler airflow tasks states-for-run migration_reporter_pipeline <run_id>
```

Артефакты прогона (в общей папке `/opt/airflow/reports` ↔ хост):

```
migration_report_YYYYMMDD_HHMMSS.xlsx   # Excel (11 листов)
migration_report_YYYYMMDD_HHMMSS.changes.json  # кэш изменений (между задачами DAG)
migration_report_YYYYMMDD_HHMMSS.html   # HTML-отчет (батчи по дате загрузки)
latest.xlsx / latest.html               # фиксированные имена последнего отчета
```

## 6. Локальный запуск без Airflow

```bash
cd migrations_tool
python migration_reporter.py run --dir pgsql --skip-pull          # без git pull
python migration_reporter.py run --dir pgsql                      # с git pull
python migration_reporter.py excel --dir pgsql --output r.xlsx    # только Excel
python migration_reporter.py html --cache r.changes.json --output r.html  # только HTML
```

## 7. Ручная генерация отдельного шага

| Команда | Что делает |
|---|---|
| `excel` | анализ + Excel-отчет + `.changes.json` кэш |
| `html`  | HTML из кэша (быстро, без повторного анализа) |
| `run`   | полный цикл (для локального запуска / восстановления) |