Первая публикация кода

AGENTS.md

@@ -0,0 +1,57 @@
+# Repository Guidelines (для агентa и контрибьюторов)
+
+Эта репа — учебный стенд для студентов (менти), которые только начинают с Airflow/Greenplum и Python. Пожалуйста, держите решения простыми, стабильными и хорошо объяснёнными.
+
+## Структура проекта
+- `airflow/dags/` — DAG-файлы (например, `csv_to_greenplum.py`, `data_quality_greenplum.py`).
+- `airflow/requirements.txt` — зависимости, которые ставятся внутри контейнеров Airflow.
+- `sql/` — DDL и вспомогательные SQL (например, `sql/ddl_gp.sql`).
+- `docker-compose.yml` — Greenplum, Airflow, Postgres (мета-БД).
+- `Makefile` — удобные команды для локальной работы.
+- `.env(.example)` — настройки окружения (реальные секреты не коммитим).
+
+## Команды (основные)
+- `make up` — поднять весь стек.
+- `make airflow-init` — инициализировать мета-БД Airflow и создать пользователя.
+- `make logs` — логи webserver и scheduler.
+- `make ddl-gp` — применить DDL к Greenplum.
+- `make gp-psql` — открыть `psql` в контейнере Greenplum от `gpadmin`.
+- `make down` — остановить и удалить тома (данные будут потеряны).
+
+Пример: `make up && make airflow-init`, затем открыть `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 и документацию — на русском; имена идентификаторов — на английском.
+
+## Тестирование
+- Тесты лежат в `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 && make airflow-init`, затем откройте DAG в UI и/или прогоните `make test`.