docs/apps/backend-scenarios/change-region.md

title

title
Смена региона пользователя (Backend)

Сценарий 1.3: Смена региона пользователя

Бизнес-цель

Пользователь может переключать регион (филиал сети / географическая зона), чтобы видеть контент и услуги, релевантные выбранной территории. В API регион хранится в User::$regionId и участвует в выдаче данных на фронте.

Точки входа

Тип	Метод + URL	Класс
HTTP	PUT /user/change-region	App\Controller\UserController::changeRegion

Требуется аутентификация: #[IsGranted('ROLE_USER')] — клиент передаёт JWT в заголовке.

CLI и Messenger не используются.

Пошаговый алгоритм (flow)

1. Клиент отправляет JSON с полем regionId.
2. Данные попадают в App\Dto\RegionDto; Symfony Validator проверяет ограничения DTO.
3. Вызывается App\Service\User\UserProfileService::updateRegion($dto):
   • JWTDecoderService::getUser() — из текущего токена извлекается username и по нему загружается User из БД;
   • на найденного пользователя выставляется setRegionId($dto->regionId);
   • EntityManager::persist + flush.
4. Контроллер сериализует тот же User::toArray() и возвращает 200 с user и successful: true.

Mermaid

sequenceDiagram
    participant C as Клиент (JWT)
    participant UC as UserController
    participant V as Validator
    participant UPS as UserProfileService
    participant JWT as JWTDecoderService
    participant UR as UserRepository
    participant EM as EntityManager

    C->>UC: PUT /user/change-region {regionId}
    UC->>V: validate(RegionDto)
    UC->>UPS: updateRegion(dto)
    UPS->>JWT: getUser()
    JWT->>UR: find by token username
    UR-->>JWT: User
    UPS->>EM: setRegionId + flush
    UPS-->>UC: User
    UC-->>C: 200 { user, successful }

Внешние зависимости

Система	Участие
PostgreSQL	обновление строки в users
JWT	идентификация текущего пользователя

Обработка ошибок и edge cases

• Невалидный regionId — 400 с телом errors из Validator.
• getUser() вернул null — в текущей реализации сервиса нет явной проверки; при ROLE_USER обычно токен уже валиден, но при рассинхроне payload/БД возможна ошибка уровня type error или flush — сценарий стоит учитывать при доработках.
• Справочник регионов: этот эндпоинт не проверяет, существует ли regionId в таблице регионов — допустим любой int, прошедший валидацию DTO.

Ссылки на классы

• apps/backend/src/Controller/UserController.php (changeRegion)
• apps/backend/src/Service/User/UserProfileService.php
• apps/backend/src/Dto/RegionDto.php
• apps/backend/src/Service/DecoderJWT/JWTDecoderService.php

См. login-jwt.md и backend-ddd.md.