183 lines
12 KiB
Markdown
183 lines
12 KiB
Markdown
# **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 с секциями, доступными согласно роли вызывающего. |