ddadmin
3de4db8aa6
- Зачем:
- ветка содержала устаревшие ссылки, артефакты CSV-пайплайна и метки «черновик»
для полностью реализованных слоёв STG→ODS→DDS→DM.
- Что:
- AGENTS.md: заменена фраза «в будущем» на перечисление реальных слоёв ODS/DDS/DM.
- TESTING.md: удалены две строки про каталог data/ (артефакт CSV-пайплайна).
- README.md: список документации заменён на кликабельные markdown-ссылки, добавлены STG и DM DAG.
- docs/README.md: добавлен DM DAG в «Быстрый путь», DM design в «Технические детали»; убраны метки «(черновик)».
- docs/internal/bookings_stg_design.md: убран заголовок «черновик», исправлены описания слоёв и DDL.
- docs/internal/PRD.md: битая ссылка на analyst_spec.md заменена текстом с пометкой TODO.
- TODO.md: ссылка на plans/ обновлена на docs/internal/bookings_db_issues.md.
- docs/bookings_to_gp_dm.md: создан новый документ по аналогии с DDS doc (5 витрин, граф, DQ, ошибки).
- plans/ и docs/chore/: каталоги удалены (планы выполнены, история сохранена в git).
- Проверка:
- make lint && make test — прошло чисто.
- grep -n "черновик|data/|в будущем|plans/" — пустой результат.
79 lines
8.7 KiB
Markdown
79 lines
8.7 KiB
Markdown
# 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-файлы (напр. `bookings_to_gp_stage.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/` — скрипты ODS (операционное хранилище);
|
||
- `sql/dds/` — скрипты DDS (детальное хранилище, star schema);
|
||
- `sql/dm/` — скрипты DM (витрины / data marts).
|
||
- Нейминг служебных полей и SCD-полей фиксирован в `docs/internal/naming_conventions.md` (единый источник для всех новых слоёв).
|
||
- Именование файлов: `{объект}_{роль}.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`.
|
||
- Есть 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_*`.
|
||
- `make clean` удаляет тома — предупреждайте студентов, что данные пропадут.
|
||
|
||
## Для агента (особенности аудитории)
|
||
- Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике.
|
||
- Избегайте больших рефакторингов и сложных паттернов — студенты только начинают.
|
||
- Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»).
|
||
- Перед релевантными правками валидируйте локально: `make up`, затем откройте DAG в UI и/или прогоните `make test`.
|