Доступ и сущности

Отделы (Departments)

Иерархия отделов, slug, системные и кастомные роли, старшинство, правила видимости и справочник кодов ошибок.

Отдел (Department) — структурная единица (команда) со своим профилем (название, описание, аватар, баннер), участниками и ролями. Отделы образуют лес деревьев (корневых отделов может быть несколько). Один пользователь может состоять в нескольких отделах, но внутри одного отдела всегда имеет ровно одну роль.

Все REST-маршруты находятся под /v1/departments, принимают Bearer JWT и X-Api-Key, используют snake_case.

Идентификатор slug

slug уникален глобально и используется в скоупе всех ролевых прав отдела (например, authservice.departments.members:invite:dev-team), поэтому он неизменяем после создания.

  • Формат: ^[a-z0-9]+(-[a-z0-9]+)*$, длина от 2 до 64 символов.
  • Зарезервированные значения (отклоняются при создании): public, self.
  • Передача slug в PATCH /v1/departments/{id} возвращает 400 slug_immutable.

Роли и старшинство (веса)

При создании отдела автоматически создаются три системные роли:

Роль (slug)Вес (weight)Можно удалитьМожно менять slug / weight
head1НетНет
deputy2НетНет
member1000НетНет
  • Кастомные роли могут иметь вес в диапазоне 3..999 (по умолчанию 500). Вес уникален внутри отдела.
  • Чем меньше число weight, тем выше старшинство (ранг) роли.
  • Когда пользователь действует на основании своей роли в отделе, целевая роль или участник должны быть строго младше (больший weight):
    • нельзя изменить собственную роль или воздействовать на участника с равным либо более высоким рангом;
    • назначить, снять или изменить роль head (вес 1) может только администратор (departments:write), руководитель сверху или носитель персонального права;
    • единственное исключение по рангу — изменение собственной видимости is_public при наличии права members:visibility.
  • Нельзя выдать право, которого нет у самого вызывающего: при создании/редактировании роли и при назначении роли участнику проверяется, что вызывающий сам может выполнять в этом отделе каждое право из роли (иначе возвращается 403 permission_not_held).

Каталог ролевых прав

В роль можно добавлять только права из каталога (на самой роли они хранятся без скоупа, а при вычислении прав участника получают скоуп :{department-slug}):

Право (authservice.departments...)Действие в отделеheaddeputymember
:readПолное чтение отдела, приватных участников и ролей✓✓✓
:editРедактирование профиля (name, description, avatar, banner, is_hidden)✓✓
.members:inviteДобавление участника✓✓
.members:visibilityИзменение флага is_public участника✓✓
.members:role_changeСмена роли участника✓✓
.members:removeИсключение участника✓
.roles:manageСоздание, изменение и удаление ролей✓
.children:createСоздание подотдела✓
.children:manageУправление прямыми подотделами✓
.descendants:manageУправление подотделами на любую глубину

:read автоматически покрывает более узкие .members:read, .roles:read и .permissions:read.

Управление сверху и структурные операции

Пользователь управляет отделом сверху, если имеет:

  • authservice.departments.children:manage:{slug-родителя}, или
  • authservice.departments.descendants:manage:{slug-любого-предка}.

Такой руководитель может выполнять любые действия из каталога и структурные операции над отделом (удаление, перенос parent_id, изменение sort_order и is_active), обходя проверку старшинства внутри отдела (включая head).

  • Структурные операции над корневым отделом или перенос в корень (parent_id: null) доступны только с authservice.departments:write.
  • Удаление отдела отклоняется (400 has_children), пока у него есть подотделы.
  • При переносе отдела дополнительно требуется children:create в новом родителе; циклические переносы отклоняются (400 invalid_parent).
  • В PATCH /v1/departments/{id} явный null трактуется как очистка/сброс поля (например, parent_id: null или description: null), а отсутствие поля оставляет значение без изменений.

Видимость отделов и участников

ВызывающийЧто видит
Любой аутентифицированный пользовательДерево нескрытых отделов: id, slug, name, description, avatar, banner, parent_id, sort_order
+ authservice.departments:read:publicДополнительно публичных участников (is_public = true) с названием и slug их роли
Полное чтение отдела (:read, :write или управление сверху)Всё: статус скрытости, приватных участников, список ролей с их правами
  • Новые участники по умолчанию создаются приватными (is_public = false).
  • Флаг is_hidden = true скрывает отдел и всё его поддерево от пользователей без полного чтения.
  • Если пользователь видит дочерний отдел внутри скрытого предка, в ответе этот отдел привязывается к ближайшему видимому предку (или становится корневым), не раскрывая скрытых предков.
  • Попытка обратиться к скрытому отделу без доступа возвращает 404 not_found, не раскрывая факт его существования.
  • Если после успешного изменения (PATCH / PUT) отдел больше не виден вызывающему, возвращается 204 No Content (для POST — 201 Created с заголовком Location без тела).

Права членства отдела (Membership Grants)

Временно недоступно. Выдача новых прав на уровне отдела (permissions и включение наследования inherit_permissions: true) сейчас отключена. Попытка создать отдел с непустым permissions / inherit_permissions: true, добавить новые строки через PUT /v1/departments/{id}/permissions или перенести/активировать отдел с появлением новых прав членства возвращает 422 membership_grants_disabled. Существующие записи и их удаление продолжают работать; ролевые права отделов работают в штатном режиме.

Загрузка аватара и баннера отдела

Эндпоинты PATCH /v1/departments/{id}/avatar и PATCH /v1/departments/{id}/banner требуют права :edit на отдел и подчиняются тем же требованиям к формату, размерам (WebP 1024×1024 / 3000×1000) и rate limit (3 загрузки за 5 минут), что и медиа пользователей.

Основные REST-маршруты

ГруппаМаршруты
ОтделыGET /v1/departments?tree=true, GET /v1/departments/{id}?includeMembers&includeRoles, POST /v1/departments, PATCH /v1/departments/{id}, DELETE /v1/departments/{id}
МедиаPATCH /v1/departments/{id}/avatar, PATCH /v1/departments/{id}/banner
УчастникиGET / POST /v1/departments/{id}/members, PATCH / DELETE /v1/departments/{id}/members/{userId}
РолиGET / POST /v1/departments/{id}/roles, PATCH / DELETE /v1/departments/{id}/roles/{roleId}
Права членстваGET / PUT /v1/departments/{id}/permissions (выдача новых прав временно недоступна)

Подробные схемы запросов и ответов смотрите в OpenAPI Reference.

Справочник кодов ошибок отделов

HTTPerrorПричина
400invalid_slugslug не соответствует формату или зарезервирован (public, self)
400slug_takenДругой отдел уже использует этот slug
400slug_immutableПопытка изменить slug при обновлении
400invalid_parentНеизвестный/скрытый родитель, либо попытка перенести отдел в себя или своего потомка
400has_childrenПопытка удалить отдел, у которого есть подотделы
400unknown_roleУказанный role_slug не найден в этом отделе
400role_slug_takenВ отделе уже есть роль с таким slug
400weight_takenВ отделе уже есть роль с таким weight
400not_in_catalogУказанное право не входит в каталог ролевых прав
400system_roleПопытка удалить системную роль или изменить её slug/weight
400role_has_membersНельзя удалить роль, пока она назначена участникам
400unknown_userПользователь с указанным user_id не найден
400empty_updateВ PATCH /members/{userId} не переданы ни role_slug, ни is_public
400invalid_imageИзображение не прошло валидацию или не декодируется
403forbiddenНедостаточно прав на действие
403insufficient_rankЦель не младше роли вызывающего
403permission_not_heldРоль содержит права, которыми вызывающий не обладает в этом отделе
404not_foundОтдел, участник или роль не найдены, либо отдел скрыт
409already_memberПользователь уже состоит в этом отделе
422membership_grants_disabledВыдача новых прав членства временно отключена