Логика и бизнес-процессы: от схемы БД до сервисного слоя

Принцип слоёв

Схема

API (роутеры) → Services (логика) → Models (SQLAlchemy) → PostgreSQL

                     ↑

              Pydantic schemas (граница)

Роутеры не содержат бизнес-правил — только HTTP, authz и маппинг ошибок.

Инструкция

Шаг 1. Доменная модель

Опишите сущности и связи:

• User, News, Comment — для медиа-платформы;

• Order, Payment — для e-commerce;

• Document, Version — для CMS.

Нарисуйте ER-диаграмму (можно попросить агента в Mermaid).

Шаг 2. Миграции Alembic

Сравнение

alembic revision --autogenerate -m "add comments"

alembic upgrade head

• Обратимые миграции для prod.

• Индексы на частые фильтры (published_at, user_id).

• Ограничения UNIQUE там, где нужна целостность.

Шаг 3. Сервисный слой

# services/news.py

async def publish_news(db, data: NewsCreate, *, user_id: int) -> News:

    # проверка прав, slug, dedup

    ...

Unit-тесты на services без HTTP.

Шаг 4. API и authz

• Пользователь видит только свои данные (PII).

• Admin-операции — отдельный router + ADMIN_API_KEY или RBAC.

• 422 / 404 / 403 — предсказуемые коды.

Шаг 5. Чеклист качества

Советы

• Нет SQL string concatenation — только ORM/params

• PII не в логах

• Транзакции на multi-step операциях

• Документированы env vars в .env.example

Связанные материалы

• Парсер и лента новостей

• Деплой на VPS

Ключевые выводы

Доменная логика живёт в services/, не в роутерах. Миграции обратимы, authz на каждом эндпоинте с PII, тесты на services.

FAQ

Fat models или fat services?

Services: модели — структура данных, services — правила и сценарии.

Где валидировать входные данные?

Pydantic на границе API; бизнес-инварианты — в services.

Нужны ли транзакции?

Да, для операций из нескольких шагов (списание + запись + уведомление).