docs(internal): добавлена первая версия PRD для DWH-стенда

- Зачем: - необходим единый документ с требованиями для разработки ETL-процессов. - Что: - создан файл docs/internal/PRD.md с описанием архитектуры, требований к данным и сроков. - Проверка: - просмотр файла docs/internal/PRD.md.
2026-03-08 18:29:04 +03:00
parent f26ed7875c
commit d77da5686c
1 changed files with 393 additions and 0 deletions
@@ -0,0 +1,393 @@
+# PRD: Greenplum Bookings DWH
+
+> Курсовая работа для курса [DE Roadmap](https://github.com/dementev-dev/de-roadmap).
+> Статус: **ЧЕРНОВИК v0.1** | Дата: 2026-03-08
+
+---
+
+## 1. Видение продукта
+
+**Greenplum Bookings DWH** — учебный стенд, на котором студент самостоятельно строит
+end-to-end ETL-пайплайн: от базы-источника до аналитических витрин.
+
+Стенд имитирует реальную рабочую задачу Data-инженера:
+- Есть «боевая» система-источник (bookings-db), в которой каждый день появляются
+  новые данные — как в жизни, без ограниченного объёма.
+- Есть DWH на Greenplum с классическими слоями (STG → ODS → DDS → DM).
+- Есть Airflow, оркестрирующий загрузку.
+- Есть ТЗ от «аналитика» с описанием ожидаемых таблиц и маппингов.
+
+Студент получает **частично реализованный пайплайн** (эталонный вертикальный срез)
+и **дореализует остальное** по ТЗ — SQL-скрипты и таски в DAG.
+
+### Почему именно bookings?
+
+Домен бронирования авиабилетов выбран не ради предметной области, а благодаря
+генератору данных: каждый вызов `make bookings-generate-day` создаёт новый день
+с реалистичным объёмом. Это даёт бесконечный поток инкрементальных данных —
+как в настоящей production-системе.
+
+---
+
+## 2. Целевая аудитория и пререквизиты
+
+**Кто:** студенты курса DE Roadmap, дошедшие до раздела «Курсовая работа».
+
+**Что уже умеют** (к моменту старта):
+- Git: ветки, PR, merge, GitFlow
+- SQL: JOIN, CTE, оконные функции, планы запросов, моделирование (3NF, звезда, SCD)
+- Python: скрипты, pandas, базовое ООП
+- Docker: запуск контейнеров, логи, docker-compose
+- Airflow: понятие DAG, операторы, зависимости, UI, логи
+- Greenplum: распределение по сегментам, skew, EXPLAIN, отличие от Postgres
+
+**Уровень:** уверенный джун, готовящийся к первым собеседованиям.
+
+---
+
+## 3. Учебные результаты (Learning Outcomes)
+
+После выполнения курсовой студент умеет:
+
+1. **Проектировать и реализовывать ETL-пайплайн** по слоям DWH
+   (STG → ODS → DDS → DM) на реальном стеке Airflow + Greenplum.
+2. **Читать ТЗ от аналитика** (маппинги, описания таблиц) и превращать его
+   в работающий SQL + DAG.
+3. **Писать идемпотентные загрузки** с инкрементальностью (HWM, batch_id,
+   delete+insert), понимая, почему в Greenplum не используется MERGE.
+4. **Реализовывать SCD1/SCD2** и объяснять, когда что применяется.
+5. **Настраивать и проверять Data Quality** — понимает, зачем DQ-проверки
+   и как их встроить в пайплайн.
+6. **Работать с Greenplum** как с MPP: выбирать distribution key,
+   понимать heap vs AO, читать планы запросов.
+7. **Оформить проект как портфолио** — репозиторий пригоден для упаковки
+   в резюме как реальный опыт работы с Airflow и Greenplum.
+
+---
+
+## 4. Скоуп
+
+### В скоупе (In Scope)
+
+| Компонент             | Описание                                                    |
+|-----------------------|-------------------------------------------------------------|
+| Источник данных       | bookings-db (Postgres) с генератором дней                   |
+| DWH                   | Greenplum, 4 слоя: STG, ODS, DDS, DM                       |
+| Оркестрация           | Apache Airflow (PostgresOperator + SQL-файлы)               |
+| Федеративный доступ   | PXF (чтение из Postgres в Greenplum)                        |
+| Инфраструктура        | Docker Compose (полный стенд в одной команде)               |
+| Data Quality          | DQ-проверки, встроенные в DAG                               |
+| Документация          | README, ТЗ, design docs, naming conventions                 |
+
+### Вне скоупа (Out of Scope)
+
+| Что                   | Почему                                                      |
+|-----------------------|-------------------------------------------------------------|
+| Kafka / стриминг      | Отдельный стенд в курсе                                     |
+| BI-инструменты        | Фокус на ETL, не на визуализации                            |
+| CI/CD                 | Избыточно для курсовой                                      |
+| Spark / Trino / dbt   | Отдельные стенды в курсе                                    |
+| Второй источник       | Усложнение без пропорциональной учебной ценности            |
+| CSV-пайплайн          | Вынести в [airflow-manual](https://github.com/dementev-dev/airflow-manual) |
+| Облачная инфраструктура | Всё локально, через Docker                                |
+
+---
+
+## 5. Архитектура стенда
+
+### Сервисы (Docker Compose)
+
+```
+bookings-db (Postgres 16) ──PXF──> Greenplum 6.27
+                                      ├── stg.*    (стейджинг)
+                                      ├── ods.*    (операционное хранилище)
+                                      ├── dds.*    (детальное хранилище)
+                                      └── dm.*     (витрины)
+
+pgmeta (Postgres 16) ─────────────> Airflow (webserver + scheduler)
+```
+
+### Слои DWH
+
+| Слой | Назначение                        | Паттерн загрузки          | Кол-во таблиц |
+|------|-----------------------------------|---------------------------|---------------|
+| STG  | Зеркало источника                 | TRUNCATE + INSERT (batch) | 9             |
+| ODS  | Нормализованное хранилище         | SCD1 UPSERT               | 9             |
+| DDS  | Измерения + факты (Kimball)       | SCD1/SCD2 + fact load     | 7 (6D + 1F)  |
+| DM   | Аналитические витрины             | HWM-инкремент             | 5             |
+
+### Сущности
+
+| STG / ODS           | DDS                      | DM                    |
+|----------------------|--------------------------|-----------------------|
+| bookings             | dim_airports             | airport_traffic       |
+| tickets              | dim_airplanes            | monthly_overview      |
+| airports             | dim_passengers           | passenger_loyalty     |
+| airplanes            | dim_routes (SCD2)        | route_performance     |
+| routes               | dim_calendar             | sales_report          |
+| seats                | dim_tariffs              |                       |
+| flights              | fact_flight_sales        |                       |
+| segments             |                          |                       |
+| boarding_passes      |                          |                       |
+
+---
+
+## 6. Педагогическая модель
+
+### Принцип: «Эталонный срез + ТЗ»
+
+Студент получает репозиторий, в котором:
+
+1. **Эталонный вертикальный срез** — полностью реализованная цепочка для одной
+   витрины DM и всех её источников вниз по слоям (STG → ODS → DDS → DM).
+   Это — образец, на который студент ориентируется.
+
+2. **ТЗ от аналитика** — Markdown-документ с описанием остальных таблиц:
+   маппинги полей, бизнес-правила, ожидаемая гранулярность, тип SCD.
+
+3. **Частично готовый DAG** — Python-файлы DAG с реализованными тасками
+   эталонного среза. Студент добавляет свои таски по аналогии.
+
+4. **DQ-проверки** — <!-- TODO: проработать формат --> готовые проверки,
+   которые студент запускает для самоконтроля.
+
+### Что делает студент
+
+- Пишет DDL для назначенных таблиц (`*_ddl.sql`)
+- Пишет SQL-загрузки (`*_load.sql`)
+- При необходимости пишет DQ-проверки (`*_dq.sql`)
+- Добавляет таски в существующий DAG
+- Проверяет результат через DQ и запросы в Greenplum
+
+### Что студент НЕ делает
+
+- Не поднимает инфраструктуру с нуля (Docker Compose дан)
+- Не пишет DAG с нуля (шаблон дан)
+- Не настраивает Airflow Connections (преднастроены)
+- Не работает с PXF-конфигурацией (настроен)
+
+### Выбор эталонного среза
+
+### Эталонный срез: витрина `sales_report`
+
+Эталоном выбрана витрина `dm.sales_report` и вся её цепочка вниз по слоям.
+
+**Почему `sales_report`:**
+- Покрывает SCD1 (airports, tariffs), HWM-инкремент, fact load
+- Богатая денормализация — хороший образец для подражания
+- Средняя сложность — не пугает, но и не тривиальна
+
+**Эталонные таблицы (даны студенту):**
+
+| Слой | Таблицы                                                         |
+|------|-----------------------------------------------------------------|
+| DM   | `sales_report`                                                  |
+| DDS  | `fact_flight_sales`, `dim_airports` (SCD1), `dim_tariffs` (SCD1), `dim_calendar` |
+| ODS  | `bookings`, `tickets`, `segments`, `flights`, `boarding_passes`, `airports` |
+| STG  | `bookings`, `tickets`, `segments`, `flights`, `boarding_passes`, `airports` |
+
+**Задание студенту:**
+
+| Слой | Таблицы                                                           | Что нового для студента                          |
+|------|-------------------------------------------------------------------|--------------------------------------------------|
+| STG  | `airplanes`, `seats`, `routes`                                    | Практика по аналогии с эталоном                  |
+| ODS  | `airplanes`, `seats`, `routes`                                    | Практика SCD1 UPSERT по аналогии                |
+| DDS  | `dim_airplanes` (SCD1), `dim_passengers` (SCD1), `dim_routes` (SCD2) | **SCD2 — ключевой вызов курсовой**          |
+| DM   | `airport_traffic`, `monthly_overview`, `route_performance`, `passenger_loyalty` | Разная сложность (от простой к сложной)  |
+
+**Рекомендуемый порядок выполнения для студента:**
+1. STG (airplanes, seats, routes) — разминка, по аналогии
+2. ODS (airplanes, seats, routes) — закрепление UPSERT
+3. DDS dim_airplanes, dim_passengers (SCD1) — новые измерения
+4. DDS dim_routes (**SCD2**) — ключевой вызов
+5. DM airport_traffic — простая витрина, похожа на sales_report
+6. DM route_performance — TRUNCATE+INSERT, SCD2-агрегация по BK
+7. DM monthly_overview — двухуровневая агрегация
+8. DM passenger_loyalty — самая сложная, пересчёт истории
+
+### SCD2 в задании: подход «рецепт без готового SQL»
+
+Реализация `dim_routes` (SCD2) — ключевой вызов курсовой. Студент делает это
+самостоятельно, но ТЗ содержит пошаговую подсказку:
+
+1. Алгоритм SCD2 текстом (без SQL):
+   - Вычисли `hashdiff` по набору атрибутов (атрибуты перечислены в ТЗ)
+   - Найди строки, у которых `hashdiff` изменился
+   - Закрой старую версию (`valid_to = текущая_дата`)
+   - Вставь новую версию (`valid_from = текущая_дата`, `valid_to = NULL`)
+2. Формула hashdiff: `md5(concat_ws('|', field1, field2, ...))`
+3. Ссылка на `naming_conventions.md` (поля `valid_from`, `valid_to`, `hashdiff`)
+4. Напоминание: полуоткрытый интервал `[valid_from, valid_to)`
+5. Если застрял — ветка `solution`
+
+Самостоятельная реализация — ключ к запоминанию. SCD2 — обязательный вопрос
+на собеседованиях DE, и студент должен уметь объяснить его на основе
+собственного опыта.
+
+---
+
+### 6.1. Валидационный DAG (`bookings_validate`)
+
+Отдельный DAG для самопроверки студента. Запускается вручную в Airflow UI
+после реализации заданий. Таски сгруппированы по слоям — студент видит,
+где именно проблема.
+
+**Примерная структура тасков:**
+
+```
+bookings_validate
+├── validate_stg
+│   ├── check_stg_airplanes_exists      (таблица создана, >0 строк)
+│   ├── check_stg_seats_exists
+│   └── check_stg_routes_exists
+├── validate_ods
+│   ├── check_ods_airplanes_rowcount    (ODS >= STG по кол-ву уникальных BK)
+│   ├── check_ods_seats_rowcount
+│   ├── check_ods_routes_rowcount
+│   └── check_ods_no_null_pks           (PK not null)
+├── validate_dds
+│   ├── check_dim_airplanes_exists
+│   ├── check_dim_passengers_exists
+│   ├── check_dim_routes_scd2           (valid_from/valid_to корректны)
+│   └── check_dim_routes_no_gaps        (нет «дыр» в версиях SCD2)
+└── validate_dm
+    ├── check_airport_traffic_exists
+    ├── check_monthly_overview_exists
+    ├── check_route_performance_exists
+    └── check_passenger_loyalty_exists
+```
+
+**Реализация:** `PostgresOperator` + SQL-скрипты в `sql/validate/`.
+Каждый SQL-скрипт выполняет SELECT и бросает исключение (через
+`DO $$ ... RAISE EXCEPTION ... $$`), если проверка не пройдена.
+Сообщения об ошибках — дружелюбные, с подсказкой что делать дальше.
+
+**Ключевые проверки:**
+- Таблицы существуют и содержат данные
+- PK не содержат NULL
+- SCD2: `valid_to IS NULL` для текущих версий, нет перекрытий интервалов
+- Кросс-слойная консистентность (row count ODS vs STG)
+- DM-витрины содержат данные за загруженные дни
+
+---
+
+## 7. Формат ТЗ от аналитика
+
+Файл: `docs/assignment/analyst_spec.md` (или несколько файлов по слоям).
+
+Для каждой таблицы-задания документ содержит:
+
+- **Имя таблицы** и целевая схема (stg / ods / dds / dm)
+- **Описание** — что хранит таблица, бизнес-смысл
+- **Список полей** с типами и описанием
+- **Маппинг источников** — откуда берётся каждое поле
+- **Бизнес-правила и фильтры** (если есть)
+- **Тип историзации** (SCD1 / SCD2 / snapshot / append)
+- **Гранулярность** (одна строка = ?)
+- **Distribution key** (подсказка или задание на выбор)
+
+Формат — приближен к реальным ТЗ, которые студент встретит на работе.
+
+---
+
+## 8. Ветки и workflow
+
+```
+main (стартовое состояние)
+  ├── Эталонный срез: реализованные таблицы + DAG
+  ├── ТЗ от аналитика
+  ├── Инфраструктура (Docker, Make, PXF)
+  ├── Заглушки / TODO-маркеры для студенческих заданий
+  └── DQ-проверки для самоконтроля
+
+solution (полное решение)
+  └── Все таблицы реализованы — эталон для самопроверки
+      и подсказка, если студент застрял
+```
+
+### Workflow студента
+
+1. Форкает репозиторий
+2. Читает README и ТЗ
+3. `make up` — поднимает стенд
+4. `make bookings-init` — инициализирует источник
+5. Запускает DDL-DAG'и (эталонные таблицы создаются)
+6. Запускает ETL-DAG'и — эталонный срез работает
+7. Реализует задания из ТЗ (SQL + таски в DAG)
+8. Проверяет себя через DQ
+9. `make bookings-generate-day` — генерирует новый день, проверяет
+   инкрементальность
+10. Защищает работу перед ментором
+
+---
+
+## 9. Критерии приёмки курсовой
+
+### Для студента (самопроверка)
+
+- [ ] Стенд поднимается (`make up`) без ошибок
+- [ ] Все DAG'и проходят без failed-тасков
+- [ ] Данные доезжают от STG до DM
+- [ ] DQ-проверки проходят на всех реализованных таблицах
+- [ ] После `make bookings-generate-day` + повторного запуска DAG
+      данные корректно доливаются (инкрементальность работает)
+
+### Для ментора (ревью + защита)
+
+- [ ] Код соответствует naming conventions (`docs/internal/naming_conventions.md`)
+- [ ] SQL идемпотентен (повторный запуск не ломает данные)
+- [ ] Distribution keys выбраны осмысленно
+- [ ] Студент может объяснить: почему delete+insert, а не MERGE;
+      разницу SCD1/SCD2; что такое HWM; как работает batch_id
+- [ ] Код оформлен для портфолио (чистый Git-history, README)
+
+---
+
+## 10. Ограничения и риски
+
+| Риск / ограничение                         | Митигация                                      |
+|--------------------------------------------|-------------------------------------------------|
+| Стенд тяжёлый (~8-16 GB RAM)              | Указать минимальные требования; не утяжелять    |
+| bookings-db генерирует данные медленно     | Не добавлять нагрузку; задокументировать ожидание|
+| Студент может застрять надолго             | Ветка `solution` как подсказка; еженедельные встречи |
+| Greenplum 6.x — устаревающая версия       | Для учебных целей достаточно; паттерны переносимы |
+| PXF нестабилен при холодном старте         | Задокументировано в README; healthcheck настроен |
+
+### Требования к машине студента
+
+- 2-4 CPU, 8-16 GB RAM, 25-40 GB диска
+- Linux / WSL2 / macOS
+- Docker + Docker Compose
+
+---
+
+## 11. Таймлайн
+
+| Когда            | Что                                                        |
+|------------------|------------------------------------------------------------|
+| Ближайшие 2-3 нед. | Первый студент может подойти к курсовой                  |
+| До этого момента | Подготовить: ТЗ, стартовое состояние main, ветку solution  |
+
+---
+
+## 12. Открытые вопросы (TODO)
+
+1. ~~**Выбор эталонного среза**~~ — **РЕШЕНО.** Эталон: `sales_report` и её
+   цепочка. Задание: остальные 4 витрины + 3 STG/ODS + 3 DDS-измерения.
+   SCD2 (`dim_routes`) — задание с подсказками в ТЗ. (Раздел 6)
+
+2. ~~**Формат DQ для самоконтроля**~~ — **РЕШЕНО.** Отдельный валидационный DAG
+   (`bookings_validate.py`). Под капотом — SQL-проверки. Студент запускает DAG
+   в Airflow UI и видит красные/зелёные таски по слоям. Дополнительный бонус —
+   практика чтения логов Airflow. (см. Раздел 6.1 ниже)
+
+3. **Вынос CSV-пайплайна** — перенести `csv_to_greenplum.py`,
+   `csv_to_greenplum_dq.py`, `ddl_greenplum_base.py`, `helpers/greenplum.py`,
+   `sql/base/orders_ddl.sql` и связанные тесты в репозиторий
+   [airflow-manual](https://github.com/dementev-dev/airflow-manual).
+   Решение принято, нужно выполнить.
+
+4. **Подготовка main** — какие изменения внести в main для стартового
+   состояния (убрать лишние реализации, добавить TODO-маркеры)?
+
+5. **Название** — рабочее: «Greenplum Bookings DWH». Финализировать.