Поток данных запроса

Как HTTP-запрос проходит сквозь слои типичного сервиса (auth/user/project/admin).

Общий путь

sequenceDiagram
    participant C as Клиент
    participant MW as Middleware (CLS + cookie-parser)
    participant G as Guard (JWT-стратегия)
    participant CT as Controller
    participant VP as ValidationPipe
    participant S as Service (@Transactional)
    participant R as Repository
    participant DB as Prisma → PostgreSQL
    participant RD as Redis (сессии/коды)

    C->>MW: HTTP /api/v1/... (+ Bearer / cookie)
    MW->>MW: генерация X-Request-Id, старт CLS-контекста
    MW->>G: запрос
    G->>G: валидация JWT, извлечение пользователя/сессии
    G->>CT: разрешено
    CT->>VP: body/query/params
    VP->>VP: валидация + transform (excludeAll)
    VP->>S: типизированный DTO
    S->>S: бизнес-правила, старт транзакции (CLS)
    S->>R: вызов репозитория
    R->>DB: Prisma-запрос (в транзакции)
    R-->>S: сущность
    S->>RD: (опц.) чтение/запись сессии/кода
    S-->>CT: результат
    CT->>CT: маппинг сущность→DTO (MapperService)
    CT-->>C: JSON (+ Set-Cookie при необходимости)

Пошагово

1. Middleware. cookie-parser парсит cookie (refresh-токены). ClsModule создаёт контекст запроса и X-Request-Id (из заголовка или новый uuid). В этом же контексте живут транзакции.
2. Guard. Passport-JWT-стратегия по типу пользователя (customer/employee/admin) валидирует access-токен, проверяет регистрацию токена/сессии и блокировку, кладёт пользователя в request.
3. Controller. Извлекает данные декораторами (@Token(), @HeaderFingerprint(), @HeaderSessionId(), @Body() и т.д.) и вызывает сервис. Логики не содержит.
4. ValidationPipe (глобальный). Валидирует вход (class-validator) и трансформирует (class-transformer, стратегия excludeAll).
5. Service. Бизнес-правила. Транзакции — декларативно через CLS (@nestjs-cls/transactional), поэтому несколько репозиториев работают в одной транзакции без ручного проброса tx.
6. Repository. Инкапсулирует Prisma/Redis-запросы. PrismaClientService уже участвует в CLS-транзакции.
7. Ответ. Сущность маппится в DTO через MapperService; наружу уходят только @Expose()-поля. При аутентификации выставляются httpOnly cookie (cookie.helper).
8. Ошибки. Исключения Prisma перехватывает глобальный PrismaExceptionFilter и превращает в корректные HTTP-статусы.

Особые потоки

Аутентификация (выдача токенов)

Access-токен — в теле/заголовке ответа; refresh-токен — в httpOnly cookie. Сессия и/или регистрация токена хранятся так, чтобы можно было отозвать доступ. Детали — auth-api.

Реалтайм-чат (ai-agent-service)

Здесь путь другой — не «запрос-ответ», а WebSocket + RabbitMQ: клиент держит WS-соединение с gateway, сообщения уходят во внешнего AI-агента через очередь и возвращаются асинхронно. См. ai-agent-service и messaging.

Загрузка файлов/аватаров

Идёт через s3-client с presigned URL. См. user-api.