docs(all): реструктурирована документация — docs/internal/ заменён на design/, reference/, archive/, plans/

- Зачем: - docs/internal/ превратился в свалку: дизайн-документы, ревью, планы и справочники лежали вперемешку. - архивные планы были неотличимы от живых документов. - Что: - docs/internal/ удалён; файлы распределены по docs/design/, docs/reference/, docs/archive/, docs/plans/, docs/assignment/. - educational-tasks.md убран из корня в архив (устарел). - обновлены все перекрёстные ссылки в AGENTS.md, TODO.md, README.md, docs/README.md и внутри design/reference/. - актуализированы architecture_review.md (статус DM-слоя), db_schema.md (DM-слой), TESTING.md, dag_execution_order.md, pxf_bookings.md. - добавлены заглушки docs/assignment/README.md и docs/plans/README.md. - Проверка: - make test && make lint - rg 'docs/internal' --glob '!docs/archive/*' — должно быть пусто.
2026-03-10 23:02:41 +03:00
parent 5972bcc2d8
commit 6655326caa
29 changed files with 322 additions and 64 deletions
@@ -0,0 +1,244 @@
+# 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, _load_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. Педагогическая модель
+
+Подробности — в [assignment_design.md](assignment_design.md).
+
+### Принцип: «Эталонный срез + ТЗ»
+
+Студент получает репозиторий, в котором:
+
+1. **Эталонный вертикальный срез** — полностью реализованная цепочка
+   `sales_report` и все её источники вниз по слоям (STG → ODS → DDS → DM).
+2. **ТЗ от аналитика** — описание остальных таблиц
+   (analyst_spec.md — будет создан на Этапе 3, см. TODO.md).
+3. **Частично готовый DAG** — студент добавляет свои таски по аналогии.
+4. **Валидационный DAG** — студент запускает для самоконтроля.
+
+### Что делает студент
+
+- Пишет DDL, SQL-загрузки, DQ-проверки для назначенных таблиц
+- Добавляет таски в существующий DAG
+- Проверяет результат через валидационный DAG и запросы в Greenplum
+
+### Что студент НЕ делает
+
+- Не поднимает инфраструктуру с нуля (Docker Compose дан)
+- Не пишет DAG с нуля (шаблон дан)
+- Не настраивает Airflow Connections (преднастроены)
+- Не работает с PXF-конфигурацией (настроен)
+
+---
+
+## 7. Ветки и workflow
+
+```
+main (стартовое состояние)
+  ├── Эталонный срез: реализованные таблицы + DAG
+  ├── ТЗ от аналитика
+  ├── Инфраструктура (Docker, Make, PXF)
+  ├── Заглушки / TODO-маркеры для студенческих заданий
+  └── Валидационный DAG для самоконтроля
+
+solution (полное решение)
+  └── Все таблицы реализованы — эталон для самопроверки
+      и подсказка, если студент застрял
+```
+
+### Workflow студента
+
+1. Форкает репозиторий
+2. Читает README и ТЗ
+3. `make up` — поднимает стенд
+4. `make bookings-init` — инициализирует источник
+5. Запускает DDL-DAG'и (эталонные таблицы создаются)
+6. Запускает ETL-DAG'и — эталонный срез работает
+7. Реализует задания из ТЗ (SQL + таски в DAG)
+8. Проверяет себя через валидационный DAG
+9. `make bookings-generate-day` — генерирует новый день, проверяет
+   инкрементальность
+10. Защищает работу перед ментором
+
+---
+
+## 8. Критерии приёмки курсовой
+
+### Для студента (самопроверка)
+
+- [ ] Стенд поднимается (`make up`) без ошибок
+- [ ] Все DAG'и проходят без failed-тасков
+- [ ] Данные доезжают от STG до DM
+- [ ] Валидационный DAG проходит на всех реализованных таблицах
+- [ ] После `make bookings-generate-day` + повторного запуска DAG
+      данные корректно доливаются (инкрементальность работает)
+
+### Для ментора (ревью + защита)
+
+- [ ] Код соответствует naming conventions (`docs/design/naming_conventions.md`)
+- [ ] SQL идемпотентен (повторный запуск не ломает данные)
+- [ ] Distribution keys выбраны осмысленно
+- [ ] Студент может объяснить: почему delete+insert, а не MERGE;
+      разницу SCD1/SCD2; что такое HWM; как работает _load_id
+- [ ] Код оформлен для портфолио (чистый Git-history, README)
+
+---
+
+## 9. Ограничения и риски
+
+| Риск / ограничение                         | Митигация                                      |
+|--------------------------------------------|-------------------------------------------------|
+| Стенд тяжёлый (~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
+
+---
+
+## 10. План работ
+
+План с чекбоксами и рекомендациями по инструментам: [TODO.md](../../TODO.md).
+
+---
+
+## 11. Открытые вопросы
+
+1. **Название** — рабочее: «Greenplum Bookings DWH». Финализировать.