airflow-greenplum/AGENTS.md

Agent System Instructions & Repository Guidelines

Этот репозиторий — учебный DWH-стенд (Airflow, Greenplum, Postgres) для начинающих Data инженеров.

1. Главное правило генерации кода (Баланс)

Создаваемый код должен иметь учебную ценность: быть эталоном для "боевого" применения, но без избыточного усложнения (over-engineering).

• Production-ready: Учитывайте идемпотентность DAG'ов, транзакционность, отсутствие хардкода секретов.
• KISS: Не используйте сложные ООП-паттерны, метапрограммирование или избыточные абстракции, если задачу решает стандартный оператор (например, PostgresOperator).
• Фокус на «Почему»: При использовании специфичных паттернов DWH (например, delete + insert для инкремента в Greenplum вместо merge) — добавляйте краткий комментарий, объясняющий этот выбор студентам.

2. Карта проекта (Навигация для Агента)

• airflow/dags/ — DAG-файлы (напр. csv_to_greenplum.py).
• sql/ — DDL и SQL-скрипты. Разделены на слои: src/ (исходные системы), stg/ (стейджинг), ods/ (операционное хранилище), dds/ (детальное хранилище), dm/ (слой витрин).
  • Правило ИИ: DDL таблиц хранится строго рядом с объектом (напр. sql/stg/bookings_ddl.sql).
• docs/internal/naming_conventions.md — Единый источник истины для нейминга служебных и SCD-полей. Правило ИИ: Всегда сверяться с этим файлом при генерации новых DDL/SQL.
• tests/ — pytest-тесты (smoke-тесты DAG'ов и юнит-тесты).
• .env — Настройки окружения (все секреты GP_*, AIRFLOW_* берем только отсюда).

3. Среда и Инструменты (Терминал)

Мы используем uv для управления зависимостями и make для автоматизации.

• Запрещено использовать pip install --user. Только uv.
• Если нужно запустить команду в терминале, используйте uv run ...
• Доступные Make-таргеты (агент может вызывать их для проверок):
  • make fmt, make lint — форматирование (black, isort) и линтинг кода.
  • make test — запуск pytest.
  • make up / make stop / make down — управление контейнерами docker-compose.
  • make ddl-gp — накат DDL на Greenplum.

4. Airflow + SQL Специфика

• В учебных DAG'ах основная логика выносится в SQL. По умолчанию используйте PostgresOperator + Airflow Connections (sql='sql/stg/bookings_load.sql').
• Сложную работу с соединениями (например, psycopg2 напрямую в Python) используйте только там, где реально много Python-логики и это служит учебной цели.

5. Стиль и Оформление

• Язык: Комментарии, docstrings, тексты ошибок — на русском языке. Ошибки должны быть дружелюбными и подсказывать студенту, что делать дальше.
• Код: Переменные, функции, SQL-идентификаторы (snake_case) — на английском.
• Коммиты: Придерживайтесь Conventional Commits (feat:, fix:, docs:, refactor:). Если меняется логика DAG'а, в описании PR (или коммита) указывайте, что именно изменилось.

Структура и нейминг SQL (слои DWH)

• В каталоге sql/ придерживаемся слоёв DWH:
  • sql/src/ — скрипты, работающие с исходными системами (например, bookings_generate_day_if_missing.sql);
  • sql/stg/ — скрипты для стейджинга (bookings_ddl.sql, bookings_load.sql, bookings_dq.sql);
  • в будущем можно добавить sql/ods/, sql/dds/, sql/dm/ по мере роста стенда.
• Именование файлов: {объект}_{роль}.sql, где:
  • объект — логическое имя сущности (bookings, orders, и т.п.);
  • роль — ddl (создание/изменение объектов), load (загрузка/инкремент), dq (проверки качества данных) и т.п.
• Общие DDL-скрипты (например, sql/ddl_gp.sql) могут подключать файловые DDL через \i, но сами определения таблиц живут рядом с объектом (sql/stg/bookings_ddl.sql и т.п.).

Airflow + SQL

• В учебных DAG’ах, где основная логика — в SQL, по умолчанию используем PostgresOperator + Airflow Connections:
  • DAG оркестрирует шаги и подключение к БД;
  • SQL-скрипты лежат в sql/... и подключаются по пути (sql='sql/stg/bookings_load.sql').
• Сложную ручную работу с подключениями (psycopg2, ENV-фоллбеки) используем только там, где реально много Python-логики и это помогает учебной цели.

Тестирование

• Тесты лежат в tests/ (pytest). Запуск: make test.
• Есть юнит‑тесты для helpers/greenplum.py и smoke‑тесты DAG‑структуры (tests/test_dags_smoke.py).
• Smoke‑тесты DAG автоматически пропускаются, если Airflow не установлен в venv.
• Для ручного прогона стенда см. TESTING.md (пошаговый чек‑лист для студентов).
• Для программной проверки DAG (без браузера) — см. docs/agent-dag-testing.md: CLI, REST API, проверка параллельности, запросы в Greenplum.

Pull Requests

• Conventional Commits: feat:, fix:, docs:, chore:, refactor:. Пример: feat(dags): load orders to Greenplum.
• Держите изменения минимальными и локальными. Не переименовывайте Make‑таргеты без обновления документации.
• В описании PR добавляйте скрин DAG‑графа или логи задач, если менялась логика.
• При изменении схемы/поведения — обновляйте README.md и sql/ddl_gp.sql.

Безопасность и конфигурация

• Все настройки — через .env; креды в коде не хардкодим. Частые переменные: GP_*, PG_*, AIRFLOW_*, CSV_*.
• make clean удаляет тома — предупреждайте студентов, что данные пропадут.

Для агента (особенности аудитории)

• Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике.
• Избегайте больших рефакторингов и сложных паттернов — студенты только начинают.
• Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»).
• Перед релевантными правками валидируйте локально: make up, затем откройте DAG в UI и/или прогоните make test.