Доработки доокументации

airflow-greenplum/AGENTS.md

@@ -1,51 +1,57 @@
-# Repository Guidelines
+# Repository Guidelines (для агентa и контрибьюторов)
 
-## Project Structure & Module Organization
+Эта репа — учебный стенд для студентов (менти), которые только начинают с Airflow/Greenplum и Python. Пожалуйста, держите решения простыми, стабильными и хорошо объяснёнными.
-- `airflow/dags/` — Airflow DAGs (e.g., `airflow/dags/kafka_to_greenplum.py`).
-- `airflow/requirements.txt` — Python deps installed inside Airflow containers.
-- `sql/` — database DDL and helpers (e.g., `sql/ddl_gp.sql`).
-- `docker-compose.yml` — Greenplum, Kafka, Airflow, Postgres (metadata DB).
-- `Makefile` — local DX commands; see targets below.
-- `.env(.example)` — runtime configuration; never commit real secrets.
 
-## Build, Test, and Development Commands
+## Структура проекта
-- `make up` — start the full stack.
+- `airflow/dags/` — DAG-файлы (например, `csv_to_greenplum.py`, `data_quality_greenplum.py`).
-- `make airflow-init` — migrate metadata DB and create admin user.
+- `airflow/requirements.txt` — зависимости, которые ставятся внутри контейнеров Airflow.
-- `make logs` — follow webserver and scheduler logs.
+- `sql/` — DDL и вспомогательные SQL (например, `sql/ddl_gp.sql`).
-- `make ddl-gp` — apply DDL to Greenplum.
+- `docker-compose.yml` — Greenplum, Airflow, Postgres (мета-БД).
-- `make gp-psql` — open `psql` in the GP container.
+- `Makefile` — удобные команды для локальной работы.
-- `make down` — stop stack and remove volumes.
+- `.env(.example)` — настройки окружения (реальные секреты не коммитим).
-Example: `make up && make airflow-init` then open `http://localhost:8080`.
 
-## Локальное Python-окружение
+## Команды (основные)
-- Окружением управляет `uv`: достаточно выполнить `uv sync` (или `make dev-sync`), чтобы подтянуть нужный Python, создать `.venv` и установить зависимости.
+- `make up` — поднять весь стек.
-- `make dev-setup` пригодится, когда нужно перепинить версию Python или прогреть кэш (вызовет `uv python install` + `uv python pin` перед `uv sync`).
+- `make airflow-init` — инициализировать мета-БД Airflow и создать пользователя.
-- Команды разработчика: `make test`, `make lint`, `make fmt` (под капотом выполняются через `uv run`).
+- `make logs` — логи webserver и scheduler.
-- Не используем `pip install --user`; если пакеты попали в user-site, удаляем через `pip uninstall <package>` и проверяем `pip list --user`.
+- `make ddl-gp` — применить DDL к Greenplum.
-- В IDE выбираем интерпретатор из `.venv` (`.venv\Scripts\python.exe` на Windows, `.venv/bin/python` на Linux/macOS).
+- `make gp-psql` — открыть `psql` в контейнере Greenplum от `gpadmin`.
+- `make down` — остановить и удалить тома (данные будут потеряны).
 
-## Coding Style & Naming Conventions
+Пример: `make up && make airflow-init`, затем открыть `http://localhost:8080`.
-- Python: PEP 8, 4-space indents, `snake_case` for functions/vars, DAG IDs lower_snake_case.
-- Imports: stdlib → third-party → local; prefer one module per line.
-- SQL: uppercase keywords, `snake_case` identifiers, end statements with `;`.
-- Filenames: DAGs as `<source>_to_<target>.py` (e.g., `kafka_to_greenplum.py`).
-- Formatting: if available, use `black` (88 cols) and `isort`; otherwise keep existing style.
-- Language: комментарии, docstrings и документацию (README, описания PR/Issues) пишем на русском; имена идентификаторов и код — на английском.
 
-## Testing Guidelines
+## Локальное Python‑окружение
-- No test suite yet. If adding tests, use `pytest` under `tests/` with `test_*.py`.
+- Используем `uv`: достаточно `uv sync` (или `make dev-sync`) — подтянет Python, создаст `.venv`, установит зависимости.
-- Prefer unit tests for Python callables used by tasks; mock env vars and external systems.
+- `make dev-setup` полезен при смене версии Python (выполнит `uv python install` + `uv python pin` перед `uv sync`).
-- Run locally with `pytest -q`.
+- Проверки: `make test`, `make lint`, `make fmt` (выполняются через `uv run`).
+- Не используем `pip install --user`; если что‑то попало в user‑site — удалить `pip uninstall <package>` и проверить `pip list --user`.
+- В IDE выбираем интерпретатор из `.venv`.
 
-## Commit & Pull Request Guidelines
+## Стиль кода
-- Use Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:` etc. Example: `feat(dags): load orders to Greenplum`.
+- Python: PEP 8, 4 пробела, `snake_case`; `dag_id` — `lower_snake_case`.
-- Keep PRs focused; include a description, run steps, and relevant screenshots (e.g., DAG graph or task logs).
+- Импорты: stdlib → third‑party → local, по одному модулю в строке.
-- Link issues; update `README.md` and DDL when behavior or schema changes.
+- SQL: ключевые слова UPPERCASE, идентификаторы `snake_case`, завершаем `;`.
+- Форматирование: `black` (88 cols) и `isort`. Если не уверены — запустите `make fmt`.
+- Язык: комментарии, docstring и документацию — на русском; имена идентификаторов — на английском.
 
-## Security & Configuration Tips
+## Тестирование
-- Configure via `.env`; do not hardcode credentials. Common vars: `GP_USER`, `GP_PASSWORD`, `GP_DB`, `GP_PORT`, `PG_*`, `AIRFLOW_*`.
+- Тесты лежат в `tests/` (pytest). Запуск: `make test`.
-- Be cautious with `make down` (removes volumes). Pin images/deps; prefer digests for critical images.
+- Есть юнит‑тесты для `helpers/greenplum.py` и smoke‑тесты DAG‑структуры (`tests/test_dags_smoke.py`).
+- Smoke‑тесты DAG автоматически пропускаются, если Airflow не установлен в venv.
+- Для ручного прогона стенда см. `TESTING.md` (пошаговый чек‑лист для студентов).
 
-## Agent-Specific Notes
+## Pull Requests
-- Keep changes minimal and localized; do not rename Make targets without updating docs.
+- Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`. Пример: `feat(dags): load orders to Greenplum`.
-- Validate by running `make up`, `make airflow-init`, and inspecting the DAG in Airflow.
+- Держите изменения минимальными и локальными. Не переименовывайте Make‑таргеты без обновления документации.
+- В описании PR добавляйте скрин DAG‑графа или логи задач, если менялась логика.
+- При изменении схемы/поведения — обновляйте `README.md` и `sql/ddl_gp.sql`.
+
+## Безопасность и конфигурация
+- Все настройки — через `.env`; креды в коде не хардкодим. Частые переменные: `GP_*`, `PG_*`, `AIRFLOW_*`, `CSV_*`.
+- `make down` удаляет тома — предупреждайте студентов, что данные пропадут.
+
+## Для агента (особенности аудитории)
+- Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике.
+- Избегайте больших рефакторингов и сложных паттернов — студенты только начинают.
+- Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»).
+- Перед релевантными правками валидируйте локально: `make up && make airflow-init`, затем откройте DAG в UI и/или прогоните `make test`.

airflow-greenplum/README.md

@@ -10,6 +10,19 @@
 - Как загружать данные в Greenplum пакетами и избегать дублей
 - Как проверять качество данных в автоматизированных pipeline
 - Основы проектирования ETL/ELT процессов
+
+## 👩‍🎓 Для студентов (10‑минутный чек‑лист)
+
+- Установите Docker Desktop и Git.
+- Скопируйте настройки: `cp .env.example .env`.
+- Поднимите стенд: `docker compose up -d` и инициализируйте Airflow: `docker compose run --rm airflow-init`.
+- Откройте UI: http://localhost:8080 (admin/admin).
+- Включите и запустите DAG `csv_to_greenplum`. Дождитесь Success.
+- Проверьте данные: `make gp-psql` → `SELECT COUNT(*) FROM public.orders;`.
+- Дополнительно: запустите `greenplum_data_quality` — все проверки должны быть зелёные.
+
+Если что‑то не работает — смотрите «Типичные проблемы» и «Быстрый reset» ниже.
+
 ## Локальное окружение разработчика
 
 Локальным окружением управляет [uv](https://docs.astral.sh/uv/) — он скачивает нужный Python и создаёт `.venv` на основе `pyproject.toml` / `uv.lock`.
@@ -93,6 +106,17 @@ SELECT * FROM public.orders LIMIT 5;
 
 CSV-файлы после выполнения DAG остаются в директории `./data`. Их можно открыть любым редактором или изучить через pandas.
 
+### Быстрый reset
+
+Если после изменений что‑то «сломалось»:
+
+```bash
+make down                 # Остановить и стереть данные в контейнерах
+make up && make airflow-init
+```
+
+Это помогает, когда Greenplum не стартует из‑за «грязной» остановки и внутренних файлов.
+
 ---
 
 ## 🛠️ Подробная настройка (для уверенных пользователей)
@@ -213,6 +237,7 @@ make logs               # Следить за логами Airflow
 | Ошибка подключения к Greenplum | Убедитесь, что контейнер `greenplum` стал статусом `healthy` (проверьте `docker compose ps`) |
 | Нет файла в `./data` после запуска DAG | Проверьте логи задачи `generate_csv`, убедитесь, что `CSV_DIR` смонтирован в docker-compose |
 | Команда `make` не найдена | Используйте полные команды `docker compose` или установите make |
+| Greenplum не стартует/падает при старте | Выполните `make down`, затем `make up && make airflow-init` (очищает тома и поднимает заново) |
 
 ---
 
@@ -239,5 +264,12 @@ make logs               # Следить за логами Airflow
 3. **Попробуйте другие источники** — замените генератор данных на чтение из файла или API
 4. **Изучите Airflow deeper** — добавьте зависимости между задачами, настройте расписания
 
+---
+
+## ✅ Тестирование
+
+- Локальные проверки: `make test` (pytest). Для форматирования — `make fmt`, для проверки — `make lint`.
+- Пошаговый сценарий с Docker (включая негативные кейсы и reset) — см. `TESTING.md`.
+
 Удачи в изучении Data Engineering! 🚀
 

airflow-greenplum/TESTING.md

@@ -1,6 +1,8 @@
-# План тестирования
+# План тестирования (для студентов)
 
-Документ описывает, как проверить актуальное состояние проекта Airflow ↔ Greenplum после серии изменений. Все шаги проверены локально на Windows в PowerShell; команды приведены в ожидаемом порядке.
+Этот документ — пошаговый чек‑лист, как проверить, что всё работает: от «быстрых локальных проверок» до запуска стенда в Docker и просмотра данных в Greenplum. Подходит начинающим: просто выполняйте шаги по порядку.
+
+Если что‑то пошло не так, смотрите раздел «Быстрый reset» ниже.
 
 ## 1. Быстрая проверка окружения
 - `uv sync` — подтягиваем Python и зависимости из `pyproject.toml`/`uv.lock`.
@@ -48,17 +50,22 @@
 - **Fallback без Airflow Connection**: установить `GP_USE_AIRFLOW_CONN=false`, перезапустить стек (`make down && make up && make airflow-init`), удостовериться, что загрузка и DQ работают через ENV.
 - **Дубликаты**: дважды вызвать `csv_to_greenplum` — ожидаем, что количество строк в `public.orders` не увеличится на размер CSV, а DAG `greenplum_data_quality` не найдёт дублей.
 
-## 7. Снятие метрик и мониторинг
+## 7. Быстрый reset (если «что-то сломалось»)
+- Перезапустить стенд с очисткой данных:
+  - `make down` — остановит контейнеры и удалит тома.
+  - `make up && make airflow-init` — заново поднимет всё и проинициализирует Airflow.
+- Иногда Greenplum не стартует после «грязных» остановок (из‑за старых внутренних файлов). Лечение: всегда делайте `make down` перед повторным `make up`.
+
+## 8. Снятие метрик и мониторинг
 - Контейнеры: `docker compose ps`, `docker stats` (по желанию).
 - Логи задач: в Airflow UI → конкретный таск → Log.
 - Хостовые CSV: каталог `data/` (можно открыть любой файл и убедиться в структуре).
 
-## 8. Завершение работы
+## 9. Завершение работы
 - `make down` — выключает сервисы и удаляет тома (перезапишет данные в Greenplum!).
 - При необходимости сохранить данные: скопировать CSV из `data/` и дампы из контейнера до `make down`.
 
-## Текущий статус (обновлено агентом)
+## Текущий статус (пример успешного прогона)
 - `uv run pytest -q` — 11 passed, 2 smoke-теста DAG пропущены (Airflow не установлен в venv).
 - `make lint` — падает, потому что `airflow/dags/*.py` не отформатированы black/isort. После `make fmt` проблема уйдёт.
 - Docker-стенд не запускался в рамках этой сессии; ожидается, что инструкции выше обеспечат полноценную проверку.
-