Участие в разработке Umbryx¶

Предварительные требования¶

Docker + Docker Compose v2
Python 3.11+ (для разработки бэкенда вне контейнеров)
Node.js 20+ (для разработки фронта вне контейнеров)
Git

Локальная настройка¶

Скопируйте файл окружения и при необходимости поправьте значения:

cp .env.example .env

Соберите и запустите весь стек:

docker compose up -d --build

Приложение будет доступно на http://localhost:3000 (nginx-прокси). При первом запуске мастер настройки создаёт стартовый аккаунт админа.

Процесс разработки¶

Вся разработка функциональности следует модели ветвления: ветки функциональности вливаются в dev, а dev вливается в main вручную после валидации.

Коротко:

feature/<имя>  →  dev  →  main (только владелец)

Создайте ветку от dev:

git checkout dev
git checkout -b feature/my-feature

Внесите изменения.
Провалидируйте полной пересборкой контейнеров:

docker compose up -d --build

Прогоните линтер бэкенда:

cd backend
pip install ruff black
ruff check app
black --check app

Прогоните линт и сборку фронта:

cd frontend
npm ci
npm run lint
npm run build

Если возможность видна пользователю — задокументируйте её в журнале разработки (в приватном репозитории).
Влейте в dev:

git checkout dev
git merge --no-ff feature/my-feature

Конвенции кода¶

Бэкенд (Python)¶

Форматтер: black (длина строки 100)
Линтер: ruff
Конфиг: backend/pyproject.toml
Ошибки: используйте AppError из core/errors.py в новых эндпоинтах
Логирование: get_logger(__name__) из core/logging_setup.py; без голых print()
Енамы: типы из core/enums.py для ролей и severity; без магических строк

Фронтенд (JavaScript/JSX)¶

Линтер: eslint (flat config в frontend/eslint.config.js)
Запуск: npm run lint
Без голых console.log в коде для промышленной эксплуатации (console.warn и console.error разрешены)
Хуки доменных данных: src/hooks/useProjectData.js вместо прямых вызовов api.* в компонентах при стандартной выборке списков

Pre-commit хуки (опционально)¶

Установите pre-commit, чтобы проверки выполнялись автоматически перед каждым коммитом:

pip install pre-commit
pre-commit install

Конфиг: .pre-commit-config.yaml в корне репо.

Миграции базы данных¶

Изменения схемы обязаны оформляться Alembic-миграцией. Никогда не меняйте схему вручную и не правьте существующие миграции.

Добавление миграции¶

cd backend

# 1. Отредактируйте app/models/<domain>.py — добавьте колонку/таблицу в ORM-класс

# 2. Сгенерируйте миграцию (autogenerate сравнивает модели с живой БД):
make db-new MSG="add last_login_at to users"

# 3. Просмотрите файл в alembic/versions/ и проверьте корректность
#    и upgrade(), и downgrade()

# 4. Примените локально для подтверждения:
make db-upgrade

Стайлгайд миграций¶

Используйте op.add_column(), op.create_table(), op.drop_column() и т.п. (операции Alembic), а не сырой op.execute(text(...)) для структурных изменений.
Всегда реализуйте downgrade(). Для необратимых миграций данных добавьте комментарий, почему откат невозможен, и бросайте NotImplementedError — чтобы падало с явной ошибкой.
Одна миграция — одно логическое изменение.
Тестируйте оба направления: make db-upgrade, затем make db-downgrade, затем снова make db-upgrade.

Основные make-цели (из `backend/`)¶

Команда	Действие
`make db-status`	Текущая версия миграций
`make db-upgrade`	Применить все ожидающие миграции
`make db-downgrade`	Откатить на один шаг
`make db-new MSG="..."`	Сгенерировать миграцию из изменений моделей
`make db-history`	Полная цепочка миграций

Тесты¶

Тесты бэкенда лежат в backend/tests/. Запуск внутри контейнера:

docker compose exec -w /app backend python -m pytest tests/ -v

Со свежей изолированной БД (рекомендуется для CI):

docker compose exec backend python -m pytest tests/ --tb=short

Или через выделенный тестовый образ (SQLite, внешние сервисы не нужны):

docker build -t umbryx-test -f backend/Dockerfile.test backend/
docker run --rm umbryx-test pytest tests/ -q