Полировка документации

README.md

@@ -18,19 +18,31 @@
 
 ## Что внутри
 
-- **Airflow** (UI: http://localhost:8080, логин/пароль: admin/admin)
+- **Airflow** (UI: http://localhost:8080, по умолчанию; логин/пароль: admin/admin)
 - **Greenplum** (single‑node для обучения; внешний порт по умолчанию `5435`)
 - **bookings-db** (Postgres с демо‑БД `demo`; внешний порт по умолчанию `5434`)
 - **PXF** как “транспорт” между Postgres и Greenplum (уже настроен в образе)
 - Побочный пример: загрузка данных через **pandas/CSV** (`csv_to_greenplum`)
 
-## PXF (в 5 строк)
+## Требования
 
-PXF (Platform Extension Framework) — компонент Greenplum для работы с внешними источниками.
+Стенд запускается в Docker и поднимает несколько сервисов (Airflow + Greenplum + 2×Postgres),
-В этом стенде PXF используется для чтения таблицы `bookings.bookings` из Postgres прямо из Greenplum
+поэтому важны ресурсы и настройки Docker.
-через внешнюю таблицу `stg.bookings_ext`. Поэтому загрузка в `stg.bookings` выглядит как обычный
+
-`INSERT ... SELECT` без промежуточных CSV.
+| Ресурс | Минимум | Рекомендуем |
-Подробное руководство по PXF смотрите в официальной документации Greenplum.
+|---|---:|---:|
+| CPU | 2 ядра | 4+ ядер |
+| RAM | 8 GB | 16 GB |
+| Диск | 25–30 GB свободного места | 40+ GB (SSD) |
+
+Работает на **Linux**, а на **Windows** — при использовании **WSL2**.
+
+Потребуется `make`, Docker (`docker`) и Docker Compose (`docker compose`) или Docker Desktop.
+Для первого запуска нужен доступ в интернет (скачать образы и зависимости).
+Порты `8080`, `5433`, `5434`, `5435` должны быть свободны (или измените их в `.env`).
+Порты настраиваются в `.env`: `AIRFLOW_WEB_PORT`, `PGMETA_PORT`, `BOOKINGS_DB_PORT`, `GP_HOST_PORT`.
+
+Про PXF и технические детали стенда: [docs/stack.md](docs/stack.md).
 
 ## Быстрый старт (основной сценарий: bookings → stg)
 
@@ -104,7 +116,7 @@ make clean              # полный reset: удалить контейнер
 ### Greenplum
 
 - `Host`: `localhost`
-- `Port`: `5435`
+- `Port`: значение `GP_HOST_PORT` из `.env` (по умолчанию `5435`)
 - `Database`: значение `GP_DB` из `.env` (по умолчанию `gp_dwh`)
 - `Username`: значение `GP_USER` (по умолчанию `gpadmin`)
 - `Password`: значение `GP_PASSWORD` (по умолчанию `gpadmin`)
@@ -132,7 +144,7 @@ make clean              # полный reset: удалить контейнер
 | Ошибка подключения к Greenplum | Убедитесь, что контейнер `greenplum` имеет статус `healthy` (`docker compose ps`) |
 | `protocol "pxf" does not exist` | Перезапустите `greenplum` и повторите `bookings_stg_ddl`/`make ddl-gp` — расширение `pxf` создаётся автоматически при старте контейнера. |
 | DAG `bookings_to_gp_stage` ругается на отсутствующие таблицы stg | Запустите `bookings_stg_ddl` (или выполните `make ddl-gp`), затем повторите запуск |
-| Порты 8080/5434/5435 заняты | Остановите локальные сервисы или измените порты в `.env`/`docker-compose.yml` |
+| Порты 8080/5433/5434/5435 заняты | Остановите локальные сервисы или измените порты в `.env` |
 
 ## Благодарности
 

docs/bookings_to_gp_stage.md

@@ -8,7 +8,7 @@
 
 - В источнике (`bookings-db`) генерирует следующий учебный день данных в `bookings.bookings`
   (генератор всегда “шагает” вперёд от `max(book_date)`).
-- В Greenplum загружает инкремент в `stg.bookings` через внешнюю таблицу `stg.bookings_ext` (PXF).
+- В Greenplum загружает инкремент в `stg.bookings` через внешнюю таблицу `stg.bookings_ext`, используя PXF.
 - Сверяет количество строк между источником (за окно инкремента) и загруженным батчем.
 
 ## Что должно быть готово перед запуском

docs/stack.md

@@ -49,6 +49,13 @@ make gp-psql
    - Login/Password: `gpadmin` / `gpadmin`
    - Port: `5432`
 
+## PXF (в 5 строк)
+
+PXF (Platform Extension Framework) — компонент Greenplum для работы с внешними источниками.
+В этом стенде PXF используется для чтения таблицы `bookings.bookings` из Postgres прямо из Greenplum
+через внешнюю таблицу `stg.bookings_ext`. Поэтому загрузка в `stg.bookings` выглядит как обычный
+`INSERT ... SELECT` без промежуточных CSV.
+
 ## Greenplum + PXF: свой образ
 
 Greenplum собирается из собственного `Dockerfile.greenplum`, чтобы:
@@ -106,10 +113,18 @@ make fmt
 
 Все настройки лежат в `.env` (шаблон: `.env.example`).
 
+### Порты на хосте
+
+- `AIRFLOW_WEB_PORT` — Airflow UI (по умолчанию `8080`)
+- `PGMETA_PORT` — мета‑БД Airflow (по умолчанию `5433`, обычно нужно только для диагностики)
+- `BOOKINGS_DB_PORT` — bookings-db (по умолчанию `5434`)
+- `GP_HOST_PORT` — Greenplum (по умолчанию `5435`)
+
 ### Greenplum
 
 - `GP_USER`, `GP_PASSWORD`, `GP_DB`
-- `GP_PORT` — внутренний порт в Docker-сети (обычно `5432`), внешний порт на хосте фиксирован на `5435`
+- `GP_PORT` — внутренний порт в Docker-сети (обычно `5432`)
+- `GP_HOST_PORT` — внешний порт на хосте (по умолчанию `5435`)
 
 ### bookings-db (Postgres)