Бэкенд (Spring Boot)

Стек и зависимости

Технология	Версия	Назначение
Java	21	Язык программирования
Spring Boot	4.0.4	Основной фреймворк
Spring Data JPA	—	Доступ к БД через репозитории
Spring Security	—	JWT-авторизация
PostgreSQL	15	Реляционная БД
Liquibase	—	Миграции схемы БД
MapStruct	—	Генерация маппер-классов
AWS SDK v2 (S3)	—	Работа с SeaweedFS
Caffeine	—	In-memory кеш
JJWT	—	Генерация и валидация JWT
Springdoc OpenAPI	—	Swagger-документация
Spring `RestClient`	—	HTTP-клиент для mphone API (с интерсепторами авторизации)
Jsoup	—	Парсинг HTML страниц поставщика для скрейпинга картинок
Spring Mail	—	Email-уведомления
Lombok	—	Генерация boilerplate-кода

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

ru.mbc.studio.dmshop/
├── controller/          # REST-контроллеры
├── service/             # Интерфейсы сервисов
│   └── impl/            # Реализации сервисов
├── repository/          # Spring Data JPA репозитории
│   └── spec/            # JPA Specifications (динамические фильтры)
├── entity/              # JPA-сущности
├── model/               # Внутренние Java records
├── dto/                 # HTTP Request/Response records
│   ├── product/
│   ├── order/
│   ├── user/
│   └── ...
├── mapper/              # MapStruct маппер-интерфейсы
├── exception/           # Доменные исключения
├── common/
│   └── exception/       # GlobalExceptionHandler, ApiErrorResponse
├── config/              # Конфигурационные классы Spring
└── sync/                # Интеграция с mphone и XML-фидом
    ├── client/          # MphoneApiClient (RestClient)
    ├── config/          # MphoneApiProperties, MphoneApiConfig
    ├── service/         # SyncService, XmlFeedSyncService, скрейпинг картинок
    ├── job/             # @Scheduled-задачи (SyncJob, CategoryVisibilityJob, GbstoreMappingJob)
    ├── pipeline/        # XML-пайплайн: оркестратор + этапы (stages/)
    └── jackson/         # MphoneDateDeserializer

Контроллеры и эндпоинты

Публичные (без авторизации)

Контроллер	Эндпоинт	Метод	Описание
AuthController	`POST /api/v1/auth/register`	—	Регистрация
AuthController	`POST /api/v1/auth/login`	—	Вход, возвращает JWT
ProductController	`GET /api/v1/products`	—	Список товаров (пагинация, фильтры)
ProductController	`GET /api/v1/products/{id}`	—	Карточка товара
CategoryController	`GET /api/v1/categories`	—	Все категории
CategoryController	`GET /api/v1/categories/tree`	—	Дерево категорий
CategoryController	`GET /api/v1/categories/homepage`	—	Категории для главной
BrandController	`GET /api/v1/brands`	—	Список брендов
ReviewController	`GET /api/v1/reviews/active`	—	Активные отзывы (для витрины)
BannerBlockController	`GET /api/v1/banner-blocks/active`	—	Активные баннеры
FeatureItemController	`GET /api/v1/feature-items/active`	—	Активные фичи
AppConfigPublicController	`GET /api/v1/config/public`	—	Публичные настройки сайта
ContactController	`POST /api/v1/contacts`	—	Отправка обращения
ImageController	`GET /api/v1/images/{id}`	—	Скачать изображение
CartController	`POST /api/v1/cart/validate`	—	Валидация корзины

Пользовательские (роль USER)

Контроллер	Эндпоинт	Метод	Описание
OrderController	`POST /api/v1/orders`	—	Оформить заказ
OrderController	`GET /api/v1/orders/{id}`	—	Просмотр заказа
OrderController	`GET /api/v1/orders/my`	—	Мои заказы
AuthController	`PUT /api/v1/auth/profile`	—	Обновить профиль
AuthController	`PUT /api/v1/auth/change-password`	—	Сменить пароль

Административные (роль ADMIN / MANAGER)

Контроллер	Эндпоинт	Описание
AdminOrderController	`GET/PATCH /api/v1/admin/orders`	Управление заказами
AdminOrderController	`POST /api/v1/admin/orders/{id}/submit`	Передача в mphone
AdminUserController	`GET/POST/PUT/DELETE /api/v1/admin/users`	Управление пользователями
AdminContactController	`GET/PUT/DELETE /api/v1/admin/contacts`	Обращения клиентов
AdminSyncController	`GET /api/v1/admin/sync/states`	Статус синхронизации
AdminSyncController	`POST /api/v1/admin/sync/run`	Запустить синхронизацию
AppConfigAdminController	`GET/POST/PUT/DELETE /api/v1/admin/config`	Настройки сайта
ReviewController	`GET/POST/PUT/DELETE /api/v1/reviews`	Управление отзывами
ReviewController	`GET /api/v1/reviews/export`	Экспорт отзывов в JSON
ReviewController	`POST /api/v1/reviews/import`	Импорт отзывов из JSON
BannerBlockController	`GET/POST/PUT/DELETE /api/v1/banner-blocks`	Баннеры
FeatureItemController	`GET/POST/PUT/DELETE /api/v1/feature-items`	Фичи
ImageController	`GET /api/v1/images`	Список изображений
ImageController	`POST /api/v1/images`	Загрузить изображение
ImageController	`PUT /api/v1/images/{id}/replace`	Заменить файл (FK сохраняются)
ImageController	`DELETE /api/v1/images/{id}`	Удалить изображение
ProductController	`POST/PUT/PATCH/DELETE /api/v1/products`	Редактирование товаров
ProductController	`PUT /api/v1/products/{id}/attributes`	Ручные атрибуты товара
CategoryController	`PUT /api/v1/categories/{id}`	Обновить категорию
CategoryController	`POST /api/v1/categories/{id}/move`, `/reorder`	Порядок категорий
CategoryController	`.../actions/hide-unused/preview` `/apply`	Скрыть неиспользуемые категории
AdminOrderController	`PATCH .../delivery-cost`, `DELETE .../bulk-delete`	Доставка и очистка заказов
LicenseController	`/api/v1/admin/license/**`	Баланс, прайсы, пополнения лицензии
EmailNotificationController	`POST /api/v1/admin/notifications/email/test`	Тестовое письмо
AttributeAliasRuleController	`/api/v1/admin/attribute-rules`	Правила атрибутов из фида
XmlFeedAdminController	`/api/v1/admin/xml-feed/**`	Ручной синк фида, маппинг категорий
XmlFeedPipelineAdminController	`/api/v1/admin/xml-pipeline/**`	Запуски, снепшоты, переопределения картинок
GbstoreScrapeQueueAdminController	`/api/v1/admin/scrape-queue/**`	Очередь и лог скрейпинга картинок

Полный перечень эндпоинтов всегда доступен в Swagger UI (/swagger-ui.html). Точные роли по каждому пути — в разделе Безопасность.

Фильтрация товаров

ProductRepository использует JPA Specifications (spec/ProductSpecifications):

// Пример динамического фильтра
Specification<ProductEntity> spec = ProductSpecifications
    .hasCategory(categoryId)
    .and(ProductSpecifications.hasBrand(brandId))
    .and(ProductSpecifications.isActive(true))
    .and(ProductSpecifications.priceBetween(min, max));

Параметры через GET /api/v1/products:

categoryId, brandId
minPrice, maxPrice
search (по названию)
active
page, size, sort

Сервисы

Каждый сервис содержит интерфейс в service/ и реализацию в service/impl/:

ProductService → ProductServiceImpl
OrderService → OrderServiceImpl
AdminOrderService → AdminOrderServiceImpl
AuthService → AuthServiceImpl
UserService → UserServiceImpl
CategoryService → CategoryServiceImpl
ReviewService → ReviewServiceImpl
ImageService → ImageServiceImpl
BannerBlockService → BannerBlockServiceImpl
FeatureItemService → FeatureItemServiceImpl
AppConfigService → AppConfigServiceImpl
ContactRequestService → ContactRequestServiceImpl
SpamProtectionService — защита от спама (без impl)
CartService → CartServiceImpl

SpamProtectionService

Защищает эндпоинт POST /api/v1/contacts от флуда: ограничивает количество обращений с одного IP за заданный промежуток времени.

MapStruct-маппинг

Каждый домен имеет свой маппер. Пример для Product:

@Mapper(componentModel = "spring")
public interface ProductMapper {
    ProductModel toModel(ProductEntity entity);
    ProductResponse toResponse(ProductModel model);
    ProductEntity toEntity(CreateProductRequest request);
}

Поля, которые не заполняются из запроса (например, externalId, productImages), помечаются:

@Mapping(target = "externalId", ignore = true)
@Mapping(target = "productImages", ignore = true)

Конфигурационные классы

Класс	Назначение
`SecurityConfig`	JWT-фильтр, CORS, разрешения эндпоинтов
`JwtService`	Генерация и валидация JWT
`JwtAuthFilter`	Servlet-фильтр: читает заголовок `Authorization`
`JwtProperties`	`@ConfigurationProperties("jwt")`: `secret`, `expirationMs`
`S3Config`	Создаёт бин `S3Client` (AWS SDK) для SeaweedFS
`S3Properties`	`@ConfigurationProperties("storage.s3")`
`CacheConfig`	Caffeine: 1000 записей, TTL 30 с
`WebConfig`	CORS (origin из `cors.allowed-origins`)
`ApplicationConfig`	`UserDetailsService`, `PasswordEncoder`
`SchedulingConfig`	`@EnableScheduling`

Стек и зависимости​

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

Контроллеры и эндпоинты​

Публичные (без авторизации)​

Пользовательские (роль USER)​

Административные (роль ADMIN / MANAGER)​

Фильтрация товаров​

Сервисы​

SpamProtectionService​

MapStruct-маппинг​

Конфигурационные классы​