76 lines
7.3 KiB
Markdown
76 lines
7.3 KiB
Markdown
# Repository Guidelines (для агентa и контрибьюторов)
|
||
|
||
Эта репа — учебный стенд для студентов (менти), которые только начинают с Airflow/Greenplum и Python. Пожалуйста, держите решения простыми, стабильными и хорошо объяснёнными.
|
||
|
||
## Структура проекта
|
||
- `airflow/dags/` — DAG-файлы (например, `csv_to_greenplum.py`, `csv_to_greenplum_dq.py`).
|
||
- `airflow/requirements.txt` — зависимости, которые ставятся внутри контейнеров Airflow.
|
||
- `sql/` — DDL и вспомогательные SQL (например, `sql/ddl_gp.sql`).
|
||
- `docker-compose.yml` — Greenplum, Airflow, Postgres (мета-БД).
|
||
- `Makefile` — удобные команды для локальной работы.
|
||
- `.env(.example)` — настройки окружения (реальные секреты не коммитим).
|
||
|
||
## Команды (основные)
|
||
- `make up` — поднять весь стек (Airflow инициализируется автоматически при первом старте).
|
||
- `make stop` — остановить контейнеры, не трогая данные.
|
||
- `make down` — остановить и удалить контейнеры/сети (тома сохраняются).
|
||
- `make clean` — полный reset: остановить и удалить контейнеры/сети и тома (все данные будут потеряны).
|
||
- `make airflow-init` — вручную переинициализировать мета-БД Airflow и создать пользователя (обычно не нужно).
|
||
- `make logs` — логи webserver и scheduler.
|
||
- `make ddl-gp` — применить DDL к Greenplum.
|
||
- `make gp-psql` — открыть `psql` в контейнере Greenplum от `gpadmin`.
|
||
|
||
Пример: `make up`, затем открыть `http://localhost:8080`.
|
||
|
||
## Локальное Python‑окружение
|
||
- Используем `uv`: достаточно `uv sync` (или `make dev-sync`) — подтянет Python, создаст `.venv`, установит зависимости.
|
||
- `make dev-setup` полезен при смене версии Python (выполнит `uv python install` + `uv python pin` перед `uv sync`).
|
||
- Проверки: `make test`, `make lint`, `make fmt` (выполняются через `uv run`).
|
||
- Не используем `pip install --user`; если что‑то попало в user‑site — удалить `pip uninstall <package>` и проверить `pip list --user`.
|
||
- В IDE выбираем интерпретатор из `.venv`.
|
||
|
||
## Стиль кода
|
||
- Python: PEP 8, 4 пробела, `snake_case`; `dag_id` — `lower_snake_case`.
|
||
- Импорты: stdlib → third‑party → local, по одному модулю в строке.
|
||
- SQL: ключевые слова UPPERCASE, идентификаторы `snake_case`, завершаем `;`.
|
||
- Форматирование: `black` (88 cols) и `isort`. Если не уверены — запустите `make fmt`.
|
||
- Язык: комментарии, docstring и документацию — на русском; имена идентификаторов — на английском.
|
||
|
||
### Структура и нейминг 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` (пошаговый чек‑лист для студентов).
|
||
|
||
## 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 down` удаляет тома — предупреждайте студентов, что данные пропадут.
|
||
|
||
## Для агента (особенности аудитории)
|
||
- Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике.
|
||
- Избегайте больших рефакторингов и сложных паттернов — студенты только начинают.
|
||
- Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»).
|
||
- Перед релевантными правками валидируйте локально: `make up`, затем откройте DAG в UI и/или прогоните `make test`.
|