Test Task CRM

Многопользовательская mini-CRM на FastAPI + PostgreSQL c сервисно-репозиторной архитектурой, JWT-аутентификацией, Alembic-миграциями и готовым React/Vite фронтендом.

Стек и особенности

• Python 3.14, FastAPI, SQLAlchemy Async ORM, Alembic.
• Pydantic Settings для конфигурации, JWT access/refresh токены, кеш аналитики в Redis.
• Frontend: Vite + React + TypeScript (см. frontend/).
• Докер-окружение для разработки (docker-compose-dev.yml) и деплоя (docker-compose-ci.yml).

Структура проекта

app/
  api/            # FastAPI-роуты и зависимости
  core/           # Настройки, база, безопасность
  models/         # SQLAlchemy-модели
  repositories/   # Работа с БД
  services/       # Бизнес-правила и сценарии
frontend/         # Vite + React SPA
migrations/       # Alembic-миграции
tests/            # Pytest (unit + интеграции)

Переменные окружения

1. Скопируйте шаблон: cp .env.example .env.
2. Обновите секреты (DB_PASSWORD, JWT_SECRET_KEY, и т.д.) перед запуском.
3. Все переменные описаны в app/core/config.py; Vite читает только ключи с префиксом VITE_.

Backend

Переменная	Значение по умолчанию	Назначение
PROJECT_NAME	"Test Task CRM"	Заголовки/метаданные API
VERSION	"0.1.0"	Версия приложения
API_V1_PREFIX	/api/v1	Базовый префикс REST
DB_HOST	localhost	Хост PostgreSQL
DB_PORT	5432	Порт PostgreSQL
DB_NAME	test_task_crm	Имя БД
DB_USER	postgres	Пользователь БД
DB_PASSWORD	postgres	Пароль пользователя
DATABASE_URL	—	Полный DSN (перекрывает DB_*), формат postgresql+asyncpg://user:pass@host:port/db
SQLALCHEMY_ECHO	false	Логирование SQL
JWT_SECRET_KEY	change-me	Секрет для подписи JWT
JWT_ALGORITHM	HS256	Алгоритм JWT
ACCESS_TOKEN_EXPIRE_MINUTES	30	TTL access-токена
REFRESH_TOKEN_EXPIRE_DAYS	7	TTL refresh-токена
REDIS_ENABLED	false	Включить кеш аналитики
REDIS_URL	redis://localhost:6379/0	Строка подключения к Redis
ANALYTICS_CACHE_TTL_SECONDS	120	TTL кэша аналитики
ANALYTICS_CACHE_BACKOFF_MS	200	max задержка при ретраях записи в кеш

Frontend (Vite)

Переменная	Значение по умолчанию	Назначение
VITE_API_URL	http://localhost:8000 (в .env.example), в src/config/env.ts дефолт https://kitchen-crm.k1nq.tech	Базовый URL бекенда (без завершающего /)
VITE_APP_URL	http://localhost:5173	URL SPA, используется для deeplink'ов и редиректов

⚠️ В frontend/src/config/env.ts зашит production URL (https://kitchen-crm.k1nq.tech). При деплое в другое место обязательно обновите VITE_API_URL/VITE_APP_URL в .env или настройте переменные окружения на уровне хостинга.

Локальный запуск без Docker

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

• Python 3.10+ и uv.
• PostgreSQL 16+ (локально или через Docker).
• (Опционально) Redis 7+ для кеша аналитики.

Backend (API)

# 1. Готовим окружение
cp .env.example .env
# отредактируйте .env: базы, секреты, VITE_* (если нужен фронтенд)

# 2. Устанавливаем зависимости
uv sync

# 3. Применяем миграции
uvx alembic upgrade head

# 4. Запускаем API (10 воркеров без hot-reload) или включаем reload при необходимости
uvx uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 10

PostgreSQL/Redis можно поднять вручную или командой docker compose -f docker-compose-dev.yml up postgres redis -d.

Frontend

cd frontend
npm install
npm run dev -- --host

Фронтенд ожидает, что VITE_API_URL указывает на работающий бекенд (например, http://localhost:8000).

Запуск через Docker Compose

Локальная разработка (docker-compose-dev.yml)

• Собирает бекенд из app/Dockerfile, поднимает postgres:16-alpine и redis:7-alpine.
• Порты по умолчанию: API 8000, Postgres 5432, Redis 6379.
• Все переменные берутся из .env.

docker compose -f docker-compose-dev.yml up --build
# или в фоне
docker compose -f docker-compose-dev.yml up --build -d

Прод/CI стек (docker-compose-ci.yml)

1. Соберите образы и статику:

   docker build -f app/Dockerfile -t <registry>/test-task-crm:app .
   docker build -f migrations/Dockerfile -t <registry>/test-task-crm:migrations .
   cd frontend && npm install && npm run build && cd ..
   

2. Залейте frontend/dist (используется как read-only volume) и задайте GIT_HOST, GIT_USER, GIT_REPO в .env.

3. Запустите стек:

   docker compose -f docker-compose-ci.yml up -d
   

В этом режиме migrations прогоняется один раз, app слушает порт 80, Postgres хранит данные на /mnt/data/postgres (смонтируйте хостовую директорию заранее).

Redis для аналитики

Кеш аналитики выключен по умолчанию. Чтобы включить:

1. Поднимите Redis (docker compose ... redis или любым другим способом).
2. В .env выставьте:
   • REDIS_ENABLED=true
   • REDIS_URL=redis://<host>:6379/0
   • (опционально) ANALYTICS_CACHE_TTL_SECONDS и ANALYTICS_CACHE_BACKOFF_MS.
3. При недоступности Redis сервис автоматически возвращается к прямым запросам в PostgreSQL и пишет предупреждения в лог.

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

Все тесты находятся в каталоге tests/ (unit на бизнес-правила и интеграционные сценарии API). Запуск:

uv run pytest

Полезные варианты:

• Запустить только юнит-тесты сервисов: uvx pytest tests/services -k service.
• Запустить конкретный сценарий API: uvx pytest tests/api/v1/test_deals.py -k won.

Перед деплоем рекомендуется прогонять миграции на чистой БД и выполнять uvx pytest для проверки правил ролей/стадий.

Линтинг и статический анализ

• uv run ruff check app tests — основной линтер (PEP8, сортировка импортов, дополнительные правила).
• uv run ruff format app tests — автоформатирование (аналог black) для единообразного стиля.
• uv run mypy app services tests — статическая проверка типов (строгий режим + плагин pydantic).

В CI/PR рекомендуется запускать команды именно в этом порядке, чтобы быстрее находить проблемы.