# Слои API Модуль — единица организации кода в `apps/api`: внутри него код разложен по слоям, а наружу он поставляет только то, что осознанно экспортирует. Слоёв три, и зависимости между ними идут строго в одну сторону: ``` Controller → Service → Data Access Layer ``` Сквозь все три слоя проходят два **контракта данных**: - **DTO** — форма данных на границе HTTP: что приходит в запросе и что уходит в ответе. - **Entities** — форма данных на границе БД: из чего состоит таблица. Модуль — не слой, а рамка, которая собирает эти части и определяет, что из них видно снаружи. ## Controllers **Тонкий контроллер.** Контроллер — точка входа HTTP. Он принимает запрос, объявляет контракт ручки для Swagger, проверяет формат входных данных и делегирует работу сервису. При этом контроллер не принимает доменных решений, не вычисляет и не агрегирует данные: почти всё тело метода занимает объявление API. Контроль доступа на этом уровне **декларативный**: `JwtAuthGuard`, `RolesGuard` с `@Roles(...)`, `ProjectAccessGuard` с декоратором роли в проекте. Проверка «пользователь — админ?» или «есть ли доступ к проекту?» читается из декораторов, а не вычисляется в теле метода. Валидация формата подключается пайпом **на конкретный параметр** (`@Body(...)`, `@Query(...)`), а не на весь метод: у проекта нет глобального `ValidationPipe`. **Входит:** - Контроль доступа на основе декларативных систем (guards, роли, декораторы) - Описание API (Swagger-декораторы, HTTP-статусы ответов) - Проверка формата входных данных (пайпы, DTO) **Не входит:** - Бизнес-логика - Проверка входных данных на основе бизнес-правил - Транзакции - Запросы к БД ## Services **Бизнес-логика и оркестрация.** Сервис — место, где принимаются решения. Здесь проверяются бизнес-правила, бросаются доменные ошибки, оркестрируются вызовы DAL и публичных сервисов других модулей, открываются транзакции и пишутся бизнес-события. Сложный домен делится на вложенные модули — по одному на поддомен (пример — `billing/modules/*`), а не разрастается в один сервис на весь домен. В публичный API модуля попадают сервисы, но не обязательно все: `exports` перечисляет их явно. Другие модули импортируют только сервисы, поэтому правило «доступ к данным чужого домена — через его публичный сервис» выполняется именно здесь, на уровне сервисов. **Входит:** - Бизнес-логика - Оркестрация: вызовы своего DAL и публичных сервисов других модулей - Транзакции (через `DataSource` — единственное исключение из правила «TypeORM только в DAL») - Контроль доступа на основе сложных бизнес-правил - Проверка входных данных на основе бизнес-правил - Логирование бизнес-событий - Вызовы внешних систем — после коммита транзакции **Не входит:** - Выполнение запросов к БД - Прямой доступ к репозиториям и `QueryBuilder` TypeORM - HTTP-специфика (объекты `Request`/`Response`, HTTP-статусы) ## Data Access Layer **Абстракция над БД.** DAL знает о бизнес-сущностях и предоставляет к ним удобный API. Сервис вызывает осмысленный метод и получает данные, не зная, как именно они достаются. DAL возвращает сущности как есть — отдельного слоя доменных моделей и мапперов в проекте нет. Минимум бизнес-логики: решения принимает сервис. Исключение — логика, которую **необходимо выполнять на стороне БД**: агрегаты, массовые `UPDATE`/`upsert`, выборки с блокировкой, оконные функции. Ради них DAL может выполнять чужую таблицу через join вместо похода в чужой сервис. DAL — **приватная часть модуля**: он не попадает в `exports` и недоступен другим модулям ни при каких условиях, даже родительскому модулю. Доступ к данным чужого домена — только через публичные сервисы модуля-владельца. Высокоуровневый API к данным выглядит так: `findById`, `getActiveProjects`, `softRemoveComment`, `getCommentsWithAuthors` — за именем стоит намерение, а не способ выборки (имена условные, они показывают уровень абстракции, а не конкретный модуль). Методы добавляются по мере необходимости, а не заранее «чтобы было». Метод принимает опциональный `manager?: EntityManager`: открывать транзакцию или нет — решает вызывающий, DAL лишь работает с тем контекстом, который ему передали. Транзакции, приватность модуля и логика на стороне БД разобраны подробно в [слое доступа к данным](30-data-access.md). **Входит:** - Выполнение запросов - Логика, которую необходимо выполнять на стороне БД **Не входит:** - Бизнес-логика (кроме логики, выполняемой в БД) - Открытие транзакций - Знание о HTTP и о том, кто его вызвал ## DTO **Контракт входа и валидация формата.** DTO описывает форму данных на границе HTTP: тело запроса, query-параметры, тело ответа. В нём объявлены поля, Swagger-описание (`@ApiProperty`) и class-validator-декораторы формата. Это описание данных, а не поведение: своих методов у DTO нет, кроме статической фабрики `from` — она переводит в форму ответа то, что вернул сервис, и держит белый список полей рядом с контрактом. Один DTO — один контракт ручки. Валидация формата (тип, обязательность, диапазон, формат строки) живёт здесь; проверка на основе бизнес-правил — уже в сервисе. DTO описывает и вход, и выход: response-модели вроде `*-response.dto.ts` кладутся в те же `dto/` и подставляются в `@ApiOkResponse({ type: ... })`. Отдельного слоя ответов нет; часть модулей держит свои read-модели плоскими интерфейсами в `*.types.ts`. **Входит:** - Форма входных и выходных данных - Валидация формата - Swagger-описание полей - Перевод данных в форму ответа — статическая фабрика `from` у response-моделей **Не входит:** - Бизнес-логика - Обращения к БД - Решения на основе бизнес-правил - Собственные методы, кроме `from`: входной DTO заполняет `ValidationPipe`, а не код самого DTO, а считать и решать, что отдавать, — дело сервиса ## Entities **Схема таблицы, а не модель поведения.** TypeORM-сущность описывает таблицу: колонки, типы, связи, индексы и имя таблицы. Имя таблицы — константа `*_TABLE_NAME`, объявленная рядом с сущностью и используемая в коде приложения. Сущность содержит только поля и связи — `Active Record` не используется, методов сохранения или поиска на ней нет. Бизнес-логики и валидации в сущности тоже нет: и то, и другое живёт в сервисе, а структура таблицы — здесь. Соглашения об именовании, расположении и связях описаны в [сущностях, таблицах и колонках](10-persistence.md). **Входит:** - Схема таблицы: колонки и типы - Связи и правила `onDelete` - Индексы - Имя таблицы **Не входит:** - Бизнес-логика - Методы `save`/`find` и любой доступ к данным - Валидация входных данных - Правила доступа