API Map: Управление Ролями и Доступом¶

Этот документ описывает карту API-методов, необходимых для полноценной работы ролевой модели в системе Архыз.CLUB.

1. Аутентификация и Контекст Пользователя¶

Базовые методы для получения информации о правах текущего пользователя и управления его активной сессией.

Метод	Путь	Описание	Доступ
`GET`	`/auth/current-user-roles`	Получение полных данных о ролях текущего пользователя (список, флаги, активная роль). Используется фронтендом и Edge-функциями.	Authenticated
`GET`	`/auth/me/roles`	Легковесная версия для проверки прав (используется внешними сервисами).	Authenticated
`GET`	`/auth/available-roles`	Список ролей, доступных для выбора при регистрации (Tourist, Hotelier, etc.).	Public / Authenticated
`POST`	`/auth/self/set-active-role`	Переключение активной роли пользователя. Может обновлять токен доступа.	Authenticated

Модели данных¶

UserRolesResponse

{
  "user_id": "uuid",
  "roles": [
    { "role_id": 1, "role_name": "admin", "role_description": "..." }
  ],
  "role_flags": {
    "is_admin": true,
    "is_hotelier": false,
    "is_tourist": false
  },
  "role_names": ["admin"],
  "active_role": "admin"
}

SetActiveRoleRequest

{
  "role_name": "hotelier"
}

2. Система Заявок на Роли (Role Requests)¶

Функционал для запроса новых прав пользователями и их обработки администраторами.

Пользовательская часть¶

Метод	Путь	Описание	Доступ
`GET`	`/role-requests/available-roles`	Список ролей, которые пользователь может запросить (с флагами `hasRole`, `hasPendingRequest`).	Authenticated
`GET`	`/role-requests/my`	Список заявок текущего пользователя.	Authenticated
`POST`	`/role-requests`	Создание новой заявки на роль.	Authenticated

Административная часть¶

Метод	Путь	Описание	Доступ
`GET`	`/admin/role-requests`	Получение всех заявок с фильтрацией по статусу и роли.	Admin
`POST`	`/admin/role-requests/{id}/approve`	Одобрение заявки. Опционально делает роль активной.	Admin
`POST`	`/admin/role-requests/{id}/reject`	Отклонение заявки с комментарием.	Admin

Модели данных¶

RoleRequestOut

{
  "id": "uuid",
  "user_id": "uuid",
  "role_id": 1,
  "status": "pending|approved|rejected",
  "reason": "text",
  "created_at": "timestamp",
  "user": { "full_name": "...", "email": "..." },
  "role": { "name": "..." }
}

ApproveRequest

{
  "make_active": boolean,
  "admin_comment": "string"
}

3. Администрирование Пользователей (User Roles Management)¶

Прямое управление ролями пользователей администратором.

Метод	Путь	Описание	Доступ
`GET`	`/users`	Поиск пользователей. Поддерживает фильтр `?role_id=...`.	Admin
`GET`	`/users/{user_id}/roles`	Получение списка ролей конкретного пользователя.	Admin
`PUT`	`/users/{user_id}/roles`	Полная замена ролей пользователя (назначение/снятие). Валидирует конфликты Primary ролей.	Admin

Логика валидации ролей¶

При назначении ролей через API должны соблюдаться правила: - Primary Roles (можно иметь только одну активную из списка): admin, hotelier, tourist, touroperator. - Secondary Roles (можно комбинировать): instructor, moderator, transfer_provider, restaurateur.

4. Справочники¶

Метод	Путь	Описание	Доступ
`GET`	`/roles`	Получение полного списка всех системных ролей.	Authenticated

План реализации (Roadmap)¶

Фаза 1: Auth & Self - Реализация эндпоинтов /auth/* для поддержки фронтенда и Edge-функций.
Фаза 2: Role Requests - Реализация полного цикла заявок (пользователь -> админ -> обработка).
Фаза 3: User Management - Реализация прямого управления ролями через админку.