EventHubSpec/EventHubFrontAdminSpec.md

EventHub Admin UI — Техническое задание (MVP)

1. Роли и права доступа

Роль	Идентификатор	Права
Суперадмин	superadmin	Полный доступ ко всем модулям, включая изменение ролей других админов, просмотр аудита, системные настройки.
Модератор	moderator	Модерация событий и жалоб, блокировка/разблокировка пользователей, работа с баг-трекером.
Поддержка	support	Просмотр пользователей и событий (read-only), обработка жалоб, создание и обновление багов.

Примечание: До реализации backend-эндпоинтов для управления ролями подразумевается одна роль admin (синоним superadmin).

---

2. Модули панели

2.1. Дашборд (Dashboard)

Виджеты:

• Статистика по пользователям: всего, новых за сегодня, активных за неделю.
• Статистика по событиям: всего, ожидают модерации, опубликовано, отклонено.
• Статистика по жалобам: новых, в обработке.
• График регистраций/событий по дням (за последние 30 дней) — если API предоставляет агрегации; иначе заглушка.
• Последние действия модераторов (аудит) — последние 10 записей.

Источник данных: GET /api/stats/* (приоритетный) или агрегация из списков ресурсов через X-Total-Count.

2.2. Управление пользователями

Эндпоинты: GET /api/users, GET /api/users/:id, PUT /api/users/:id, DELETE /api/users/:id

Функциональность:

• Список пользователей (ID, username, email, роль, дата регистрации, статус, рейтинг).
• Фильтрация: по роли, статусу, поиск по username/email.
• Детальная карточка:
  • Основная информация, аватар.
  • Список событий пользователя.
  • История жалоб на пользователя.
  • Блокировка/разблокировка, смена роли (только суперадмин).
  • Причина блокировки (поле ввода).
• Массовые действия: блокировка/удаление выбранных пользователей.

Особые требования: Подтверждение деструктивных действий через модальное окно.

2.3. Управление событиями

Эндпоинты: GET /api/events, GET /api/events/:id, PUT /api/events/:id, DELETE /api/events/:id, а также эндпоинт модерации (например, PATCH /api/events/:id/approve)

Функциональность:

• Список событий (название, организатор, календарь, статус, количество записей).
• Фильтрация: по статусу, календарю, дате.
• Детальный просмотр:
  • Полная информация о событии (описание, дата-время, локация, тип).
  • Список записей участников с возможностью ручного подтверждения/отклонения.
  • Кнопки «Одобрить» / «Отклонить» (изменение статуса с pending на approved/rejected).
  • При отклонении — обязательное указание причины.
• Редактирование любого поля события.
• Удаление с подтверждением.

2.4. Управление календарями

Эндпоинты: GET /api/calendars, POST /api/calendars, PUT /api/calendars/:id, DELETE /api/calendars/:id

Функциональность:

• Список календарей (название, владелец, тип, количество подписчиков).
• Детальный просмотр: информация, возможность деактивации календаря.
• Создание коммерческого календаря (опционально, если требуется админам).
• Просмотр списка подписчиков (только чтение).

2.5. Модерация жалоб

Эндпоинты: GET /api/complaints, GET /api/complaints/:id, PUT /api/complaints/:id

Функциональность:

• Список жалоб (ID, тип, подавший, объект жалобы, статус).
• Фильтрация: по статусу, типу.
• Детальный просмотр:
  • Текст жалобы, прикреплённые файлы/ссылки.
  • Информация о нарушителе/событии.
  • Кнопки «Рассмотрено» и «Отклонить».
  • Возможность перехода к блокировке пользователя/события прямо из карточки жалобы.

2.6. Баг-трекер

Эндпоинты: GET /api/bugs, POST /api/bugs, PUT /api/bugs/:id, DELETE /api/bugs/:id

Функциональность:

• Список багов (ID, заголовок, статус, приоритет, назначенный, дата создания).
• Детальный просмотр: описание, шаги воспроизведения, скриншоты.
• Смена статуса, назначение ответственного из числа админов.
• Комментарии к багу (если поддержано API).
• Создание новых багов (только внутренние, не от пользователей).

---

3. Интеграция с API и аутентификация

• JWT-аутентификация, аналогичная основному приложению.
• Эндпоинт входа: /api/auth/login (или /api/admin/login).
• Токен сохраняется в localStorage и добавляется ко всем запросам (Authorization: Bearer ...).
• При получении HTTP 401 — редирект на страницу входа.
• Для дашборда использовать специальные эндпоинты /api/stats/*; если их нет — собирать статистику через заголовок X-Total-Count и множественные запросы (временно).

---

4. Требования к UX/UI

• Material Design (React-Admin + MUI).
• Адаптивная верстка (планшеты).
• Пагинация (серверная предпочтительна, клиентская допустима для малых объемов).
• Сортировка по любому полю.
• Поиск с debounce 300 мс.
• Подтверждение деструктивных действий (удаление, блокировка).
• Уведомления об успехе/ошибке через Snackbar.
• Тёмная тема (опционально, переключатель).

---

5. Технологический стек

• Язык: TypeScript
• Сборщик: Vite
• UI-фреймворк: React-Admin v5 + Material UI v5
• Провайдер данных: ra-data-simple-rest с кастомизацией для JWT
• Аутентификация: кастомный authProvider
• Контейнеризация: Docker, Nginx

---

6. Этапы реализации (MVP)

1. Неделя 1: Инициализация проекта (Vite + React-Admin), простой dataProvider, страница входа.
2. Неделя 2: Модуль пользователей (список, детали, блокировка).
3. Неделя 3: Модуль событий (список, модерация).
4. Неделя 4: Модули жалоб, баг-трекера, календарей (базовый просмотр/изменение статусов).
5. Неделя 5: Дашборд (если API готово), финальные штрихи, тестирование, деплой в staging.

---

7. Что потребуется от бэкенда (EventHubBack)

7.1 Роли и права доступа

Описать три административные роли: superadmin, moderator, support.

В JWT-токене после аутентификации передавать поле role с одним из этих значений. Оставить поддержку "role": "admin" как синоним superadmin для обратной совместимости.

Middleware авторизации для админских эндпоинтов (/admin/* или порты 8445/8446) должен:

• Проверять валидность JWT.
• Извлекать роль.
• Сопоставлять с требуемыми правами для каждого действия.

Эндпоинт получения текущей роли:

• GET /admin/me (или GET /api/auth/me) — возвращает { id, username, role, permissions }.

Эндпоинты управления ролями (только для superadmin):

• GET /admin/admins — список администраторов.
• PUT /admin/admins/:id — изменить роль.
• POST /admin/admins — пригласить нового администратора.

Логирование действий (аудит):

• Таблица admin_audit (admin_id, username, роль, действие, тип объекта, ID объекта, timestamp, IP, причина).
• Эндпоинт GET /admin/audit с фильтрами (доступен только superadmin).

При блокировке пользователя / отклонении события обязательно принимать поле reason в теле запроса и сохранять в БД.

Разграничение прав на уровне API:

• support: read-only пользователи и события; может обновлять статусы жалоб и багов, создавать баги.
• moderator: всё, кроме управления админами и просмотра аудита.
• superadmin: полный доступ.

Ответ при недостаточности прав: 403 Forbidden, тело:

{ "error": "insufficient_permissions", "message": "Требуется роль moderator или выше" }
## 7.2 Статистика для дашборда с учётом ролей

| Роль | Предоставляемые метрики |
|------|--------------------------|
| `superadmin` | Системные метрики (все пользователи, события, жалобы, баги за период, графики регистраций/событий по дням, активность администраторов). |
| `moderator` | Собственные обработанные жалобы/события (количество, статусы, время реакции), общая статистика по модерации. |
| `support` | Количество открытых багов и жалоб, назначенных на текущего сотрудника, персональные задачи. |

Эндпоинт `GET /api/stats` должен возвращать JSON с секциями, доступными согласно роли вызывающего.