Доводка стилистики документации

airflow/dags/bookings_stg_ddl.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
 """
-Учебный DAG: создаёт схему stg и таблицы bookings_ext/bookings/tickets в Greenplum.
-Запускается вручную перед DAG загрузки bookings_to_gp_stage или после изменения DDL.
+Учебный DAG: создаёт/обновляет слой stg в Greenplum для демо-источника bookings.
+
+Запускается вручную перед DAG загрузки `bookings_to_gp_stage` или после изменения DDL.
+Создаёт внешние таблицы PXF (`*_ext`) и внутренние таблицы STG (9 таблиц: bookings, tickets,
+airports, airplanes, routes, seats, flights, segments, boarding_passes).
 """
 
 from datetime import timedelta
@@ -23,8 +26,8 @@ with DAG(
     catchup=False,
     template_searchpath="/sql",
     default_args=default_args,
-    tags=["demo", "greenplum", "ddl", "bookings", "tickets", "stg"],
-    description="Создаёт/обновляет stg.bookings_ext/bookings/tickets для учебного DAG",
+    tags=["demo", "greenplum", "ddl", "bookings", "stg"],
+    description="Учебный DDL DAG: создаёт/обновляет stg.* (PXF external + internal STG) для bookings",
 ) as dag:
     apply_stg_bookings_ddl = PostgresOperator(
         task_id="apply_stg_bookings_ddl",
@@ -82,7 +85,8 @@ with DAG(
         sql="stg/boarding_passes_ddl.sql",
     )
 
-    # Сначала создаются справочники, затем транзакционные таблицы (последовательно)
+    # DDL применяем последовательно, чтобы порядок был понятным для новичков,
+    # а ошибки — воспроизводимыми (в логах сразу видно, на каком объекте упали).
     (
         apply_stg_bookings_ddl
         >> apply_stg_tickets_ddl

airflow/dags/bookings_to_gp_stage.py

@@ -13,6 +13,8 @@ from __future__ import annotations
 - генератор в демо-БД bookings добавляет следующий учебный день после max(book_date);
 - загрузка в Greenplum берёт все строки, появившиеся после предыдущих батчей;
 - `run_id` используется как метка запуска (в `batch_id`, в логах и DQ).
+
+Важно: для инкрементальных таблиц «пустое окно инкремента» допустимо (это не ошибка).
 """
 
 from datetime import timedelta
@@ -56,7 +58,7 @@ with DAG(
     template_searchpath="/sql",
     default_args=default_args,
     tags=["demo", "bookings", "greenplum", "stg"],
-    description="Учебный DAG: загрузка из bookings-db в stg.bookings и stg.tickets (Greenplum)",
+    description="Учебный DAG: загрузка из bookings-db в слой stg (Greenplum) + DQ проверки",
 ) as dag:
     # 1. Генерируем один (или несколько стартовых) учебный день в демо-БД bookings
     generate_bookings_day = PostgresOperator(
@@ -180,7 +182,7 @@ with DAG(
         sql="stg/boarding_passes_dq.sql",
     )
 
-    # 6. Финальный лог/сводка
+    # Финальный лог/сводка
     finish_summary = PythonOperator(
         task_id="finish_summary",
         python_callable=_finish_summary,
@@ -190,13 +192,15 @@ with DAG(
     generate_bookings_day >> load_bookings_to_stg >> check_row_counts
     check_row_counts >> load_tickets_to_stg >> check_tickets_dq
 
-    # Затем загружаются справочники (последовательная загрузка)
+    # Затем загружаются справочники.
+    # Для простоты (и более понятных логов для новичков) делаем это последовательно.
+    # Если позже понадобится ускорить DAG, эти шаги можно распараллелить, сохранив зависимости.
     check_tickets_dq >> load_airports_to_stg >> check_airports_dq
     check_airports_dq >> load_airplanes_to_stg >> check_airplanes_dq
     check_airplanes_dq >> load_routes_to_stg >> check_routes_dq
     check_routes_dq >> load_seats_to_stg >> check_seats_dq
 
-    # Затем загружаются транзакции (последовательная загрузка)
+    # Затем загружаются транзакции (тоже последовательно, по тем же причинам).
     check_seats_dq >> load_flights_to_stg >> check_flights_dq
     check_flights_dq >> load_segments_to_stg >> check_segments_dq
     check_segments_dq >> load_boarding_passes_to_stg >> check_boarding_passes_dq