v1.2

EventHubFrontAdminSpec.md

@@ -0,0 +1,183 @@
+# **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`, тело:
+```json
+{ "error": "insufficient_permissions", "message": "Требуется роль moderator или выше" }
+## 7.2 Статистика для дашборда с учётом ролей
+
+| Роль | Предоставляемые метрики |
+|------|--------------------------|
+| `superadmin` | Системные метрики (все пользователи, события, жалобы, баги за период, графики регистраций/событий по дням, активность администраторов). |
+| `moderator` | Собственные обработанные жалобы/события (количество, статусы, время реакции), общая статистика по модерации. |
+| `support` | Количество открытых багов и жалоб, назначенных на текущего сотрудника, персональные задачи. |
+
+Эндпоинт `GET /api/stats` должен возвращать JSON с секциями, доступными согласно роли вызывающего.