Отделы (Departments)
Отдел (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 |
|---|---|---|---|
head | 1 | Нет | Нет |
deputy | 2 | Нет | Нет |
member | 1000 | Нет | Нет |
- Кастомные роли могут иметь вес в диапазоне
3..999(по умолчанию500). Вес уникален внутри отдела. - Чем меньше число
weight, тем выше старшинство (ранг) роли. - Когда пользователь действует на основании своей роли в отделе, целевая роль или участник должны быть строго младше (больший
weight):- нельзя изменить собственную роль или воздействовать на участника с равным либо более высоким рангом;
- назначить, снять или изменить роль
head(вес1) может только администратор (departments:write), руководитель сверху или носитель персонального права; - единственное исключение по рангу — изменение собственной видимости
is_publicпри наличии праваmembers:visibility.
- Нельзя выдать право, которого нет у самого вызывающего: при создании/редактировании роли и при назначении роли участнику проверяется, что вызывающий сам может выполнять в этом отделе каждое право из роли (иначе возвращается
403 permission_not_held).
Каталог ролевых прав
В роль можно добавлять только права из каталога (на самой роли они хранятся без скоупа, а при вычислении прав участника получают скоуп :{department-slug}):
Право (authservice.departments...) | Действие в отделе | head | deputy | member |
|---|---|---|---|---|
: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.
Справочник кодов ошибок отделов
| HTTP | error | Причина |
|---|---|---|
400 | invalid_slug | slug не соответствует формату или зарезервирован (public, self) |
400 | slug_taken | Другой отдел уже использует этот slug |
400 | slug_immutable | Попытка изменить slug при обновлении |
400 | invalid_parent | Неизвестный/скрытый родитель, либо попытка перенести отдел в себя или своего потомка |
400 | has_children | Попытка удалить отдел, у которого есть подотделы |
400 | unknown_role | Указанный role_slug не найден в этом отделе |
400 | role_slug_taken | В отделе уже есть роль с таким slug |
400 | weight_taken | В отделе уже есть роль с таким weight |
400 | not_in_catalog | Указанное право не входит в каталог ролевых прав |
400 | system_role | Попытка удалить системную роль или изменить её slug/weight |
400 | role_has_members | Нельзя удалить роль, пока она назначена участникам |
400 | unknown_user | Пользователь с указанным user_id не найден |
400 | empty_update | В PATCH /members/{userId} не переданы ни role_slug, ни is_public |
400 | invalid_image | Изображение не прошло валидацию или не декодируется |
403 | forbidden | Недостаточно прав на действие |
403 | insufficient_rank | Цель не младше роли вызывающего |
403 | permission_not_held | Роль содержит права, которыми вызывающий не обладает в этом отделе |
404 | not_found | Отдел, участник или роль не найдены, либо отдел скрыт |
409 | already_member | Пользователь уже состоит в этом отделе |
422 | membership_grants_disabled | Выдача новых прав членства временно отключена |