Администрирование и права доступа

Помимо базовой подачи и поиска, в Papex входит ориентированная на операторов админ-зона и тонкая система прав доступа. В этом руководстве рассмотрены четыре возможности:

1. Роли и права (RBAC) — контроль публикации, просмотра, скачивания и комментирования работ по ролям или отдельным пользователям.
2. Управление правами пользователей — назначение дополнительных ролей и установка индивидуальных переопределений разрешить/запретить для любого права.
3. Совместное рецензирование (peer review) — админы отправляют запросы на совместное рецензирование; рецензенты принимают, отправляют мнения и получают подтверждения, образуя замкнутый цикл.
4. Категоризированные сообщения и рассылка — единый центр уведомлений, охватывающий системные уведомления, результаты рецензий, подтверждения тикетов, запросы на совместное рецензирование, личные сообщения админов и ответы сообщества, плюс адресные рассылки.

---

1. Роли и права (RBAC)

Papex использует трёхуровневую модель — базовая роль + назначенные роли + индивидуальные переопределения — поддерживающую как массовую ролевую авторизацию, так и персонализированные ограничения по пользователям.

1.1 Модель прав

Уровень	Описание	Где поддерживается
Базовая роль	Роль, присущая каждому пользователю в users.role: author / moderator / admin	По умолчанию author при регистрации
Назначенные роли	Дополнительные роли поверх пользователя через таблицу связи user_roles	Страница управления пользователями
Индивидуальные переопределения	Явное разрешить или запретить для одного права у пользователя; наивысший приоритет	Страница управления пользователями

ℹ️ reader — это назначенная RBAC-роль (в таблице roles), а не базовая роль БД (users.role допускает только author / moderator / admin). Базовая роль определяет вход и границу прав по умолчанию; назначенные роли накладываются сверху.

1.2 Каталог прав

Система поставляется с 15 правами в 6 группах:

Группа	Ключ права	Название	Описание
paper	paper:publish	Публикация работы	Подать новую работу или версию
	paper:view	Просмотр работы	Просматривать опубликованные работы
	paper:download	Скачивание работы	Скачать PDF / исходный пакет
	paper:moderate	Модерация работы	Одобрить / отклонить / отозвать
comment	comment:create	Создание комментария	Комментировать и отвечать под работами
	comment:view	Просмотр комментариев	Просматривать раздел комментариев
ticket	ticket:create	Создание тикета	Открыть обратную связь / тикет
	ticket:manage	Управление тикетами	Отвечать на / обрабатывать тикеты
co_review	co_review:assign	Назначение рецензии	Отправить запрос на совместное рецензирование
	co_review:respond	Принятие рецензии	Принять / отклонить запрос
	co_review:manage	Управление рецензией	Просматривать весь прогресс рецензий
message	message:broadcast	Рассылка	Отправлять сообщения пользователям
admin	user:manage	Управление пользователями	Просматривать / редактировать пользователей
	role:manage	Управление ролями	Настраивать роли и права
	permission:manage	Управление переопределениями	Разрешить/запретить по пользователям

1.3 Права ролей по умолчанию

Начальные данные (db:seed) записывают карту прав по умолчанию для каждой системной роли:

Роль	Количество	Права
admin	15	Все права
moderator	12	просмотр/скачивание/модерация работ, создание/просмотр комментариев, создание/управление тикетами, назначение/принятие/управление рецензией, рассылка, управление пользователями
author	6	публикация/просмотр/скачивание работ, создание/просмотр комментариев, создание тикетов
reader	3	просмотр/скачивание работ, просмотр комментариев

1.4 Порядок разрешения

При выполнении защищённой операции эффективные права разрешаются так:

права базовой роли
  ∪ права назначенных ролей      (объединение ролей)
  ∪ индивидуальные переопределения с пометкой разрешить
  − индивидуальные переопределения с пометкой запретить  (переопределения побеждают)

Так что даже если ни базовая, ни назначенные роли не дают paper:publish, явное переопределение разрешить всё равно позволяет его; наоборот, явный запрет блокирует его, даже когда роли дают его.

Откат: если таблицы roles / permissions ещё не заполнены (напр. свежая БД без db:seed), движок откатывается к константной карте по умолчанию выше, чтобы не заблокировать весь сайт. Всё же рекомендуется запустить db:seed после развёртывания.

1.5 Защищённые операции (шлюзы)

Ключевые операции защищены; при отсутствии права возвращается 403:

• POST /api/papers — требует paper:publish
• POST /api/papers/:id/comments — требует comment:create
• Модерация, обработка тикетов, назначение / управление рецензией, правки пользователей и ролей, рассылка и т. д. требуют соответствующих прав, а маршруты защищены middleware (только moderator / admin могут зайти в /admin).

---

2. Управление правами пользователей

Откройте /admin/users (требует user:manage):

• Поиск пользователей по имени / email / отображаемому имени с постраничным выводом.
• Назначение дополнительных ролей: отметьте системные роли (admin / moderator / author / reader) в редакторе пользователя, чтобы наложить на базовую роль.
• Трёх-state переопределение права: для каждого из 15 прав установите:
  • наследовать (по умолчанию) — следовать результату объединения ролей;
  • разрешить — принудительно дать, даже если роли не содержат;
  • запретить — принудительно заблокировать, даже если роли включают.

Все изменения сохраняются мгновенно через PATCH /api/admin/users/:id и применяются к последующим проверкам авторизации этого пользователя.

---

3. Совместное рецензирование (peer review)

Совместное рецензирование — это полный цикл рецензирования, связывающий админ → рецензент → автор.

3.1 Замкнутый цикл

Админ назначает ──► Рецензент получает сообщение «запрос на рецензию»
     │
     ▼
Рецензент отвечает (принять / отклонить)
     │ принять
     ▼
Рецензент отправляет мнение (одобрить / отклонить / доработать + комментарий)
     │
     ▼
Системное подтверждение ──► уведомляет назначившего «мнение отправлено»
                ──► уведомляет автора «рецензия завершена» (если автор ≠ назначивший)

3.2 Машина состояний

Запись совместной рецензии (co_reviews) переходит следующим образом:

Состояние	Значение	Вход
pending	Ожидание ответа рецензента	Назначение админом (POST /api/co-reviews)
accepted	Принято	Рецензент принимает (POST /api/co-reviews/:id/respond {accepted:true})
declined	Отклонено	Рецензент отклоняет (respond {accepted:false})
completed	Завершено	Рецензент отправляет мнение (submit)
expired	Просрочено	(зарезервированное состояние для закрытия по таймауту)

Рецензент может отвечать только в состоянии pending, а отправлять мнение — только в accepted. Несовпадение состояния возвращает INVALID_STATE.

3.3 Точки входа и уведомления

• Админ: /admin/co-reviews для назначения и мониторинга всех рецензий; /admin/co-reviews/:id для деталей. Назначение выбирает из работ в статусе submitted.
• Рецензент: /co-reviews (мои рецензии) и /co-reviews/:id (принять / отклонить + отправить мнение).
• Единые уведомления: каждое изменение состояния отправляет сообщение co_review_request / co_review_result соответствующим сторонам (см. Раздел 4).

---

4. Категоризированные сообщения и рассылка

4.1 Категории сообщений

Сообщения классифицируются по kind на 8 категорий, окрашенные и сгруппированные во входящих:

kind	Метка	Тон	Типичный источник
system	Системное уведомление	по умолчанию	Системные события
ticket_reply	Подтверждение тикета	синий info	Ответ на тикет
announcement	Объявление	жёлтый warning	Рассылка админа
review_result	Результат рецензии	зелёный success	Работа одобрена / отклонена
co_review_request	Запрос на рецензию	фиолетовый	Назначена рецензия
co_review_result	Подтверждение рецензии	фиолетовый	Отправлены ответ / мнение
admin_message	Личное сообщение админа	красный danger	Адресное личное сообщение
community_reply	Ответ сообщества	синий info	Ответ на комментарий

Входящие (/messages) поддерживает фильтрацию по категории (GET /api/messages?kind=...); нажатие на сообщение переводит к связанному link (работа, тикет, рецензия, …).

4.2 Единая воронка уведомлений

Все сквозные оповещения модулей испускаются через единый сервис notifications, так что модули рецензий, тикетов, совместного рецензирования и сообщества используют один контракт уведомлений:

• Рецензии: решение по работе → уведомить автора (review_result).
• Тикеты: ответ сотрудника → уведомить автора обращения (ticket_reply).
• Совместное рецензирование: назначение / ответ / отправка → уведомить рецензента, назначившего, автора (co_review_request / co_review_result).
• Сообщество: ответ на комментарий → уведомить автора родительского комментария (community_reply).

4.3 Рассылка

Откройте /admin/messages (требует message:broadcast):

• Охват:
  • all — каждый пользователь;
  • role — базовая роль (author / moderator / admin);
  • userIds — список конкретных ID пользователей.
• Вид: announcement / system / admin_message.
• Заполните заголовок, тело (с необязательным link), отправьте, и сообщение записывается массово целевой аудитории; возвращается количество успешно доставленных.

---

5. Навигация админа

Точки входа админа находятся в меню авторизованного пользователя и обзоре /admin, включая:

Модуль	Маршрут	Описание
Обзор	/admin	Карточки статистики + ярлыки модулей
Очередь рецензий	/admin/review	Одобрить / отклонить работы (+ причина)
Статистика	/admin/stats	Метрики платформы
Тикеты	/admin/tickets	Обработка тикетов
Рецензия	/admin/co-reviews	Назначение и мониторинг рецензий
Пользователи	/admin/users	Роли и переопределения прав
Роли	/admin/roles	Матрица прав ролей
Сообщения	/admin/messages	Рассылка

Эти маршруты защищены middleware; доступ к ним имеют только пользователи с базовой ролью moderator или admin, а операции записи дополнительно требуют соответствующего тонкого права.

---

6. Эксплуатация: миграция и начальные данные

Четыре системы зависят от миграции 0003_add_rbac_co_review_messages (добавляет roles / permissions / role_permissions / user_roles / user_permissions / co_reviews / moderation_logs и расширяет messages.kind до 8 категорий). При развёртывании или локальной инициализации выполните:

npm run db:migrate   # применить миграции (RBAC / совместное рецензирование / категории сообщений)
npm run db:seed      # записать 4 системные роли + 15 прав + значения по умолчанию (идемпотентно)

Начальные данные RBAC используют onConflictDoNothing и безопасны для повторного запуска. После миграции + начальных данных движок прав использует таблицы roles / permissions; до заполнения откатывается к константным значениям по умолчанию (см. 1.4).

---

7. Краткий справочник API

Метод	Путь	Описание
GET	/api/messages?kind=	Входящие, фильтр по категории
POST	/api/papers/:id/moderate	Модерация {action:"approve"|"reject"|"withdraw", reason?}
GET	/api/co-reviews?scope=mine|all	Список рецензий (мои / все)
POST	/api/co-reviews	Назначить {paperId, reviewerId, note?}
GET	/api/co-reviews/:id	Детали рецензии
POST	/api/co-reviews/:id/respond	Ответить {accepted:boolean}
POST	/api/co-reviews/:id/submit	Отправить {decision:"approve"|"reject"|"revise", comment}
GET	/api/admin/users	Список пользователей (постранично / поиск)
PATCH	/api/admin/users/:id	Установить роли {roleKeys} или переопределение {permission:{key,grant}}
GET	/api/admin/roles	Список ролей
PUT	/api/admin/roles/:id	Установить права роли {permissionKeys}
POST	/api/admin/messages	Рассылка {scope, role?, userIds?, kind, title, body, link?}
GET	/api/admin/stats	Статистика платформы

Полный список см. в справочнике API.