feat: migrate to VitePress from monorepo docs, add test-contour section

2026-05-28 12:29:31 +03:00
parent e90dfe1bd4
commit e3e438df68
76 changed files with 11998 additions and 60 deletions
@@ -0,0 +1,74 @@
+---
+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
+
+```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](./login-jwt.md) и [backend-ddd.md](../backend-ddd.md).