ddadmin
8932148c44
- Зачем:
- файлы планов именовались хаотично (микс snake_case/kebab-case, без дат),
из-за чего архив не сортировался хронологически.
- Что:
- установлен формат YYYY-MM-DD_краткое-описание.md для docs/plans/ и docs/archive/.
- переименованы 6 архивных файлов по новой конвенции (git mv).
- конвенция зафиксирована в AGENTS.md (секция «Карта проекта»).
- Проверка:
- ls docs/archive/ — все файлы начинаются с даты в kebab-case.
89 lines
7.8 KiB
Markdown
89 lines
7.8 KiB
Markdown
# План: выравнивание качества документации 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".
|