# План: выравнивание качества документации ETL DAG'ов

## Контекст

Документ `bookings_to_gp_stage.md` — эталон: пошаговый разбор задач, ASCII-граф,
ссылки на SQL-файлы, описание edge cases. Три остальных документа
(`_ods`, `_dds`, `_dm`) значительно беднее. Цель — подтянуть их до того же уровня.

## Единый шаблон секций (целевая структура)

Каждый документ должен содержать:

1. **Заголовок + вводный абзац** (что за DAG, какой слой, зачем)
2. **Что делает DAG** (буллеты, краткое описание)
3. **Что должно быть готово** (prerequisites)
4. **Как запустить** (UI + опциональные параметры)
5. **Граф зависимостей** (ASCII-диаграмма, не буллет-лист)
6. **Как это работает внутри (по шагам)** ← ГЛАВНОЕ ДОБАВЛЕНИЕ
   - Пронумерованные шаги: task_id → SQL-файл → что делает → паттерн (SCD1/SCD2/rebuild/HWM)
   - Учебные пояснения к нетривиальным паттернам
7. **Как проверить результат** (SQL-запросы)
8. **Типичные ошибки** (уже есть, оставляем)

## Что именно добавить/исправить в каждом документе

### A. `bookings_to_gp_ods.md`

**Текущее состояние:** 95 строк, нет пошагового разбора, нет ASCII-графа, нет SQL-путей.

| # | Что сделать | Детали |
|---|-------------|--------|
| A1 | ASCII-граф зависимостей | Заменить буллет-лист на диаграмму (как в stage). Показать параллельные ветки airports/airplanes, схождение на routes/seats, цепочку flights→segments→boarding_passes |
| A2 | Секция "Как это работает внутри" | 10 шагов: resolve_stg_batch_id (Python, INTERSECT-логика), затем 9 пар load→dq с указанием SQL-файлов |
| A3 | Пояснить паттерн SCD1 UPSERT | Кратко: TEMP TABLE → UPDATE (IS DISTINCT FROM) → INSERT. Одного абзаца достаточно, потом ссылка "паттерн одинаков для всех 9 таблиц" |
| A4 | Описать разницу snapshot vs HWM | Snapshot-справочники фильтруются по `stg_batch_id`; транзакционные таблицы — по HWM (`_load_ts`). Объяснить почему (чтобы не терять инкременты при повторных запусках STG) |
| A5 | Edge case: пустой батч | Для инкрементальных таблиц допустим; для snapshot — нет |

**Ожидаемый объём:** ~140–160 строк.

### B. `bookings_to_gp_dds.md`

**Текущее состояние:** 73 строки — самый бедный документ. Нет пошаговости, нет ASCII-графа, SCD2 не объяснён.

| # | Что сделать | Детали |
|---|-------------|--------|
| B1 | ASCII-граф зависимостей | calendar → параллельно 4 SCD1-измерения + dim_routes (после airports+airplanes) → fact (после всех dims) → summary |
| B2 | Секция "Как это работает внутри" | 8 шагов: calendar (rebuild), 4×SCD1-измерения, dim_routes (SCD2), fact_flight_sales, summary |
| B3 | Объяснить SCD2 для dim_routes | Учебный блок: hashdiff (MD5), закрытие старых версий, вставка новых, point-in-time valid_from. Это ключевой паттерн DDS — заслуживает 10–15 строк |
| B4 | Объяснить Phase 3 (денормализация) | Обновление SCD1-атрибутов (города, модель) во ВСЕХ версиях dim_routes. Зачем: чтобы не хранить устаревшие названия городов |
| B5 | Объяснить late-arriving dimensions | LEFT JOIN в fact_flight_sales: факт может прийти раньше справочника. 3–5 строк |
| B6 | Объяснить point-in-time join | Как факт привязывается к правильной версии SCD2-маршрута по дате рейса |
| B7 | Edge case: генерация SK | MAX() + ROW_NUMBER() безопасна только при concurrency=1 |

**Ожидаемый объём:** ~160–180 строк.

### C. `bookings_to_gp_dm.md`

**Текущее состояние:** 80 строк. ASCII-граф есть (хорошо!), описание стратегий загрузки есть (хорошо!), но нет пошагового разбора с SQL-файлами.

| # | Что сделать | Детали |
|---|-------------|--------|
| C1 | Секция "Как это работает внутри" | 5 шагов (по одному на витрину) + start_dm + finish_dm_summary. Для каждой витрины: task_id → SQL-файл → паттерн → зерно (grain) |
| C2 | Расширить описание sales_report | HWM-паттерн: какие даты пересчитываются, NULLIF-guard для boarding_rate, автоматическая "догонка" при первичной загрузке |
| C3 | Расширить описание route_performance | Почему Full Rebuild: AO Column (нет UPDATE/DELETE), таблица маленькая. 3-шаговый паттерн: TRUNCATE → агрегация по route_bk → JOIN с текущей версией SCD2 |
| C4 | Добавить grain для каждой витрины | sales_report: (flight_date, departure_airport_sk, arrival_airport_sk, tariff_sk); route_performance: route_bk; и т.д. |
| C5 | Добавить SQL-пути к задачам | Сейчас нигде не указаны пути к SQL-файлам |

**Ожидаемый объём:** ~140–160 строк.

### D. Мелкие правки в `bookings_to_gp_stage.md` (опционально)

| # | Что сделать | Детали |
|---|-------------|--------|
| D1 | Убедиться в консистентности шаблона | Если в ходе работы над ODS/DDS/DM выработается чуть лучшая структура — привести stage к тому же формату (только структурные правки, контент не менять) |

## Порядок работы

1. **ODS** (средняя сложность, знакомый паттерн SCD1)
2. **DDS** (наибольшая учебная ценность — SCD2, late-arriving dims)
3. **DM** (наименьший объём правок — ASCII-граф уже есть)
4. **Stage** — только если нужна косметика для консистентности

## Принципы

- Не раздувать: целевой объём каждого документа — 140–180 строк (stage = 157).
- Учебная ценность > полнота: объяснять «почему», а не перечислять все колонки.
- SQL-пути обязательны — это главный навигационный инструмент для студента.
- Один паттерн объясняем один раз подробно, дальше ссылаемся: "паттерн аналогичен X".