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