Ядро приложения (core)

Ядро организовано по слоям чистой архитектуры:

1. Presentation - контроллеры и представления.
2. Application - прикладной слой (DTO, команды, запросы, хендлеры).
3. Domain - доменная логика (сущности, value objects, события, исключения).
4. Infrastructure - реализации портов и вспомогательные компоненты (обработчик ошибок, репозитории).

Слой Presentation

Контроллеры

• BaseController - абстрактный контроллер, от которого наследуются все API-контроллеры. Предоставляет удобные методы для формирования ответов (см. base-controller.md).
• SwaggerController - отдаёт JSON-спецификацию OpenAPI и HTML-интерфейс Swagger UI.
• DocsController - использует пакет doctordanila/script-doc для отображения проектной документации.

Swagger

В папке core/presentation/swagger/ содержатся файлы с аннотациями @OA для генерации OpenAPI-документации:

• info.php - общая информация о API, серверы, схема безопасности (bearerAuth).
• parameters.php - общие параметры (page, limit, expand, fields).
• schemas.php - схемы данных (Collection, Item, Error).
• __include.php - подключает все вышеперечисленные файлы.

• Эти аннотации сканируются контроллером SwaggerController с помощью OpenApi\Generator.

Слой Application

Содержит DTO (Data Transfer Objects) и заготовки для команд, запросов, хендлеров и UseCase. Основные DTO:

• CollectionDto - для пагинированных коллекций (содержит items, _meta).
• ErrorDto - для ошибок (код, сообщение, детали).
• ItemDto - для одного объекта (обёртка item).
• SuccessDto - для успешных ответов (сообщение, данные).

Слой Domain

• Сущности - бизнес-объекты с уникальной идентичностью.
• Value Objects - неизменяемые объекты, например IdRange (парсинг диапазонов ID из строки вида 1,3:20,27). Предоставляет методы toArray(), contains(), isEmpty() и т.д.
• События - оповещения о произошедших изменениях.
• Исключения - доменные ошибки.

Слой Infrastructure

• JsonErrorHandler - переопределяет стандартный обработчик ошибок Yii2, возвращая всегда JSON-ответ с детализацией в зависимости от DEBUG_LVL.
• Заготовки для репозиториев, миграций, слушателей событий и т.п.