RBAC

Канонический DDL находится в ../database-schema.md. SQL ниже является концептуальным примером RBAC-модели и не используется для миграций.

Зачем нужно

Документ описывает роли, permissions, назначения ролей и правила проверки прав доступа.

1. Роли

1.1. Три уровня ролей

Глобальные системные — неизменяемы, поставляются с системой:

Роль	`order`	Назначение
`super_admin`	0	Полный доступ ко всему
`admin`	1	Управление платформой (без super-возможностей)
`user`	2	Базовый пользователь

Глобальные кастомные — создаёт super_admin/admin через UI. Действуют на уровне всей платформы. Например: moderator, support, editor.

Организационные — создаёт владелец организации. Действуют только внутри этой организации. Они используют тот же централизованный формат permissions, но scope и membership ограничивают проверку конкретной организацией.

1.2. Наследование

Роли поддерживают иерархию через parentId. Дочерняя роль наследует все права родительской + свои собственные. Поле parent_id всегда означает «роль, от которой наследуем».

user (order=2)
  └── admin (order=1) inherits user
        └── super_admin (order=0) inherits admin

Наследование применяется при генерации JWT: getAllInheritedPermissions(roleId) обходит цепочку parentId вверх и собирает permissions текущей роли и всех родителей.

Кастомные роли тоже могут иметь parentId — например, moderator наследует от user.

1.3. Entity

Три отдельных таблицы — каждый уровень ролей в своей:

Глобальные роли (roles):

CREATE TABLE roles (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name          VARCHAR(100) NOT NULL UNIQUE,
  display_name  JSONB NOT NULL,
  description   JSONB,
  is_system     BOOLEAN NOT NULL DEFAULT FALSE,
  parent_id     UUID REFERENCES roles(id),
  "order"       INT NOT NULL DEFAULT 100,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Организационные и командные роли — см. organizations.md (organization_roles, team_roles).

2. Права доступа

2.1. Формат

Формат наследуется из ../../../platform/permissions-model.md:

<domain>.<resource>.<action>[.<scope>]

Каждый permission — гранулярное право на конкретное действие. Identity не вводит отдельный формат resource.action: все permissions, включая организационные и platform permissions, проходят через единый каталог packages/permissions/catalog.ts.

2.2. Seed-набор identity/platform permissions

Этот список — стартовый seed-набор для bootstrap identity/admin UI. Он не является закрытым числом permissions: каталог расширяется доменными permissions-matrix.md.

Пользователи:

Permission	Отображение (ru)
`identity.users.read`	Просмотр пользователей
`identity.users.manage`	Редактирование пользователей
`identity.users.delete`	Anonymization пользователя (GDPR data erasure, см. users.md)
`identity.users.block`	Бан/разбан пользователей

Организации:

Permission	Отображение (ru)
`identity.organizations.create.own`	Создание своей организации
`identity.organizations.read.own`	Просмотр своих организаций
`identity.organizations.read`	Просмотр организаций
`identity.organizations.read.organization`	Просмотр организации в organization scope
`identity.organizations.manage`	Редактирование организаций
`identity.organizations.manage.organization`	Редактирование организации в organization scope
`identity.organizations.archive`	Архивирование организаций на global/admin уровне
`identity.organizations.archive.organization`	Архивирование организации в organization scope
`identity.organizations.transfer-ownership.organization`	Передача владения организацией
`identity.organizations.hard-delete.global`	Физическое удаление never-used организаций (break-glass)
`identity.organization-references.manage`	Управление справочником организаций
`identity.organization-members.manage`	Управление участниками организации на global/admin уровне
`identity.organization-members.approve.organization`	Подтверждение и отклонение заявок на вступление
`identity.organization-members.suspend.organization`	Приостановка членства
`identity.organization-roles.manage`	Управление ролями организации на global/admin уровне
`identity.organization-ownership-claims.review`	Рассмотрение заявок на владение
`identity.organization-merges.manage`	Ручная склейка организаций
`identity.organization-members.read.organization`	Просмотр участников внутри организации
`identity.organization-members.manage.organization`	Управление участниками внутри организации
`identity.organization-members.assign.organization`	Назначение ролей участников внутри организации
`identity.organization-roles.read.organization`	Просмотр ролей внутри организации
`identity.organization-roles.manage.organization`	Управление ролями внутри организации
`identity.organization-contacts.manage.organization`	Управление контактами организации
`identity.organization-invitations.create.organization`	Отправка приглашений организации
`identity.organization-invitations.manage.organization`	Управление приглашениями организации
`identity.teams.read.organization`	Просмотр команд организации
`identity.teams.manage.organization`	Управление командами организации
`identity.organization-students.read.organization`	Просмотр учеников организации
`identity.organization-students.create.organization`	Создание учеников организации
`identity.organization-students.manage.organization`	Редактирование учеников организации
`identity.organization-students.archive.organization`	Архивирование учеников организации
`identity.organization-permission-grants.manage.organization`	Управление organization-local permission grants

Плагины:

Permission	Отображение (ru)
`platform.plugins.read`	Просмотр плагинов
`platform.plugins.install`	Установка плагинов
`platform.plugins.manage`	Управление плагинами (настройка/включение/выключение)

RBAC:

Permission	Отображение (ru)
`identity.roles.read`	Просмотр ролей
`identity.roles.manage`	Создание и редактирование ролей
`identity.roles.assign`	Назначение и снятие ролей с пользователей
`identity.permissions.read`	Просмотр permissions

Настройки платформы:

Permission	Отображение (ru)
`platform.settings.read`	Просмотр настроек платформы
`platform.settings.manage`	Изменение настроек платформы
`platform.branding.manage`	Редактирование брендинга
`platform.navigation.manage`	Редактирование навигации

Уведомления:

Permission	Отображение (ru)
`platform.notifications.read`	Просмотр правил уведомлений
`platform.notifications.manage`	Редактирование правил уведомлений

Семья:

Permission	Отображение (ru)
`identity.families.read`	Просмотр семейной группы
`identity.families.manage`	Управление семейной группой

OAuth-клиенты:

Permission	Отображение (ru)
`identity.oauth_clients.read`	Просмотр OAuth-клиентов
`identity.oauth_clients.manage`	Управление OAuth-клиентами

Аудит:

Permission	Отображение (ru)
`identity.audit.read`	Просмотр журнала аудита

2.3. Организационные permissions

Организационные роли используют те же permission keys из централизованного catalog, но применяют их только внутри конкретной организации через scope = organization или более узкий domain-specific scope.

Набор permissions для организационных ролей определяется в organizations.md.

2.4. Человекочитаемость

Каждый permission хранит display_name (JSONB с локалями) для отображения в UI:

CREATE TABLE permissions (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name          VARCHAR(100) NOT NULL UNIQUE,  -- "identity.users.read"
  display_name  JSONB NOT NULL,                -- { "ru": "Просмотр списка пользователей" }
  description   JSONB,
  resource      VARCHAR(100) NOT NULL,         -- "users"
  action        VARCHAR(100) NOT NULL,         -- "list"
  is_system     BOOLEAN NOT NULL DEFAULT FALSE,
  UNIQUE(name)
);

2.5. Wildcard

Wildcard levels:

Global wildcard * applies only to global/platform permissions. It does not automatically grant organization-local owner role.
Organization wildcard * applies only inside one organization.
Team wildcard * applies only inside one team.

Global super_admin access to organization data is break-glass/admin access: it requires explicit global permission, is always audited, and does not mutate organization membership. Wildcard values are not stored in permissions; they are resolved dynamically when generating effective permissions.

3. Назначение ролей

3.1. Таблица `user_role_assignments`

Только для глобальных ролей. Организационные и командные назначения — через organization_memberships и organization_team_memberships (см. organizations.md).

CREATE TABLE user_role_assignments (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  role_id     UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
  assigned_by UUID REFERENCES users(id),
  expires_at  TIMESTAMPTZ,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE(user_id, role_id)
);

3.2. Правила

Пользователь может иметь несколько глобальных ролей
Организационные и командные роли назначаются через membership (см. organizations.md)
Нельзя назначить роль с большими привилегиями (меньший order), чем у назначающего
expires_at — опциональный срок действия роли; истёкшие назначения исключаются на уровне запроса (WHERE expires_at IS NULL OR expires_at > now()), cron-очистка не требуется. При истечении mid-session: текущий access token сохраняет старые permissions до естественного истечения (макс. 15 мин), при refresh token генерируется новый access token без истёкшей роли. Принудительный revoke не выполняется — задержка до 15 мин приемлема
При регистрации: первый пользователь → super_admin, остальные → user
Аудит: назначение и снятие ролей логируются в audit_logs — действие identity.role.assigned / identity.role.revoked с assigned_by, role_id, user_id. Это security-значимое действие, аудит обязателен

4. Проверка прав

4.1. Серверная часть (API gateway)

Проверка из JWT-payload (синхронная, без обращения к БД):

JwtAuthGuard — аутентификация (есть токен?)
RolesGuard — проверка роли по имени: @RequireRoles('admin') → hasRole(name: string) сравнивает с полем name из JWT, без иерархии уровней
PermissionsGuard — проверка permissions (@RequirePermissions('identity.users.read'))
super_admin и wildcard * — bypass только в allowed wildcard level; organization-local owner/team lead checks still use local membership or explicit audited global permission.

4.2. Фронтенд

PermissionProvider оборачивает приложение и предоставляет контекст прав через хук usePermissions:

Читает roles и permissions из auth store (JWT-payload)
hasPermission(permission: string) — проверяет наличие строки в массиве permissions из JWT
hasRole(name: string) — проверяет точное совпадение имени роли с одним из значений в roles из JWT (сравнение по имени, не по уровню)
isSuperAdmin — wildcard check

Компоненты: AdminRoute, PermissionRoute — защита маршрутов.

4.3. Задержка обновления

Права из JWT — кэш на 15 минут (TTL access token). Изменение ролей вступает в силу при следующем refresh token.

5. Организационные и командные роли

5.1. Организационные роли

Организационные роли независимы от глобальных назначений, но используют тот же permission catalog:

Создаются владельцем организации
Действуют только внутри организации
Не влияют на глобальные права пользователя
Хранятся в organization_roles (см. organizations.md §4.1–4.2)

Шаблонные роли (создаются автоматически при создании организации, is_system: true):

Роль	`order`	Права	Назначение
`owner`	0	`["*"]`	Полный доступ, создатель организации
`admin`	1	управление членами, командами, ролями, настройками	Администратор
`member`	2	базовый доступ	Обычный участник

Владелец/admin может создавать кастомные роли с произвольным набором permissions.

5.2. Командные роли

Командные роли действуют только внутри конкретной команды организации:

Создаются lead/admin команды
Не влияют ни на глобальные, ни на организационные права
Хранятся в team_roles (см. organizations.md §4.3–4.4)

Шаблонные роли (создаются автоматически при создании команды):

Роль	`order`	Права	Назначение
`lead`	0	Добавление/удаление участников, редактирование команды	Руководитель
`member`	1	Просмотр и участие	Участник

5.3. Три уровня — без пересечений

Глобальные роли (roles)
  └── Действуют на всю платформу
  └── Назначаются через user_role_assignments

Организационные роли (organization_roles)
  └── Действуют внутри конкретной организации
  └── Назначаются через organization_memberships.role_id

Командные роли (team_roles)
  └── Действуют внутри конкретной команды
  └── Назначаются через organization_team_memberships.role_id

Каждый уровень имеет свою таблицу, свой набор permissions, свои шаблонные роли. Глобальный super_admin имеет доступ ко всему (wildcard *), но это реализуется через глобальную проверку, а не через организационные/командные permissions.

6. API-эндпоинты

HTTP	Путь	Auth	Назначение
GET	`/api/v2/identity/admin/roles`	JWT + `identity.roles.read`	Список глобальных ролей
POST	`/api/v2/identity/admin/roles`	JWT + `identity.roles.manage`	Создать роль
PATCH	`/api/v2/identity/admin/roles/:id`	JWT + `identity.roles.manage`	Редактировать роль
DELETE	`/api/v2/identity/admin/roles/:id`	JWT + `identity.roles.manage`	Удалить роль
GET	`/api/v2/identity/admin/roles/:id/permissions`	JWT + `identity.roles.read`	Итоговые permissions (с наследованием)
GET	`/api/v2/identity/admin/permissions`	JWT + `identity.permissions.read`	Список permissions
POST	`/api/v2/identity/admin/role-assignments`	JWT + `identity.roles.assign`	Назначить роль пользователю
DELETE	`/api/v2/identity/admin/role-assignments/:id`	JWT + `identity.roles.assign`	Снять роль

7. UX/UI

7.1. Admin: RolesManagementPage

Страница /:lang/admin/roles — управление ролями и правами.

Список ролей:

RoleTreeSimple — иерархическое дерево ролей (parent-child)
Каждая роль: название + количество пользователей + бейдж уровня
Системные роли (super_admin, admin, user) — не удаляемые, помечены бейджем "Системная"

RoleModal (создание/редактирование):

Поля: название, описание, parent role (select из дерева)
PermissionBuilder — визуальный конструктор: категории permissions (users, organizations, plugins и др.) с чекбоксами
Наследование: отображает permissions от parent role (disabled чекбоксы, помечены "Наследовано")

7.2. UserDetailPanel — таб "Роли"

В UserDetailPanel (slide-in панель на странице управления пользователями):

UserDetailRolesTab: список назначенных ролей
RolesSelector — select для добавления роли
Кнопка "Удалить" для каждой назначенной роли (кроме дефолтной user)
Предупреждение при назначении super_admin

7.3. Визуальное отображение прав

В UI права влияют на:

Sidebar: пункты меню фильтруются по requiredPermissions — пользователь видит только разрешённые
Страницы: PermissionRoute проверяет permission до рендера; при отсутствии — AccessDeniedBlock (403)
Элементы интерфейса: кнопки, действия, секции скрываются через usePermissions().hasPermission(name)
Admin sidebar: группы и пункты фильтруются по permissions текущего пользователя

Зачем нужно​

1. Роли​

1.1. Три уровня ролей​

1.2. Наследование​

1.3. Entity​

2. Права доступа​

2.1. Формат​

2.2. Seed-набор identity/platform permissions​

2.3. Организационные permissions​

2.4. Человекочитаемость​

2.5. Wildcard​

3. Назначение ролей​

3.1. Таблица user_role_assignments​

3.2. Правила​

4. Проверка прав​

4.1. Серверная часть (API gateway)​

4.2. Фронтенд​

4.3. Задержка обновления​

5. Организационные и командные роли​

5.1. Организационные роли​

5.2. Командные роли​

5.3. Три уровня — без пересечений​

6. API-эндпоинты​

7. UX/UI​

7.1. Admin: RolesManagementPage​

7.2. UserDetailPanel — таб "Роли"​

7.3. Визуальное отображение прав​