259 lines
12 KiB
Markdown
259 lines
12 KiB
Markdown
# Challenge Admin Panel
|
||
|
||
Админская панель для управления Challenge Service - системой автоматической проверки заданий с помощью LLM.
|
||
|
||
## 🎯 Реализованная функциональность
|
||
|
||
### ✅ Dashboard (Главная страница)
|
||
- **Основные метрики:**
|
||
- Количество пользователей, заданий, цепочек
|
||
- Общее количество проверок
|
||
- Статус очереди с загруженностью
|
||
- Среднее время проверки
|
||
- **Статистика проверок:**
|
||
- Принятые/отклоненные/ожидающие
|
||
- Распределение по статусам
|
||
- **Real-time обновление:** автоматическое обновление данных каждые 10 секунд
|
||
|
||
### ✅ CRUD для Tasks (Заданий)
|
||
- **Список заданий:**
|
||
- Таблица с названием, автором, датой создания
|
||
- Индикатор наличия скрытых инструкций (🔒)
|
||
- Поиск по названию
|
||
- Действия: редактировать, удалить
|
||
- **Создание/редактирование задания:**
|
||
- Название (обязательное, до 255 символов)
|
||
- Описание в формате Markdown с вкладками "Редактор" и "Превью"
|
||
- **Скрытые инструкции для LLM** (🔒 только для преподавателей):
|
||
- Специальное поле с визуальным выделением
|
||
- Инструкции передаются LLM при проверке, но не видны студентам
|
||
- Примеры использования в подсказках
|
||
- Отображение метаданных (автор, даты создания/обновления)
|
||
- Валидация и обработка ошибок
|
||
|
||
### ✅ CRUD для Chains (Цепочек)
|
||
- **Список цепочек:**
|
||
- Таблица с названием, количеством заданий, датой создания
|
||
- Поиск по названию
|
||
- Действия: редактировать, удалить
|
||
- **Создание/редактирование цепочки:**
|
||
- Название цепочки (обязательное)
|
||
- Выбор заданий из существующих
|
||
- Управление порядком заданий (кнопки вверх/вниз)
|
||
- Добавление/удаление заданий в цепочку
|
||
- Поиск доступных заданий
|
||
|
||
### ✅ Users (Пользователи)
|
||
- **Список пользователей:**
|
||
- Таблица с nickname, ID, датой регистрации
|
||
- Поиск по nickname
|
||
- Кнопка просмотра статистики
|
||
- **Детальная статистика пользователя (модальное окно):**
|
||
- Общие метрики: выполнено, всего попыток, в процессе, требует доработки
|
||
- Прогресс по цепочкам с визуальными прогресс-барами
|
||
- Детали по заданиям со статусами
|
||
- Среднее время проверки
|
||
|
||
### ✅ Submissions (Попытки)
|
||
- **Список попыток:**
|
||
- Таблица с пользователем, заданием, статусом, попыткой
|
||
- Дата отправки и время проверки
|
||
- **Фильтрация:**
|
||
- Поиск по пользователю или заданию
|
||
- Фильтр по статусу (все/принято/доработка/проверяется/ожидает)
|
||
- Цветные бейджи статусов
|
||
- **Детали попытки (модальное окно):**
|
||
- Метаданные: пользователь, статус, даты
|
||
- Описание задания (Markdown)
|
||
- Решение пользователя
|
||
- Обратная связь от LLM
|
||
- Время проверки
|
||
|
||
## 🛠 Технологический стек
|
||
|
||
- **React 18** + **TypeScript**
|
||
- **React Router** для навигации
|
||
- **Redux Toolkit** + **RTK Query** для state management и API
|
||
- **Chakra UI v3** для UI компонентов
|
||
- **react-markdown** для отображения Markdown
|
||
- **Keycloak** для авторизации преподавателей
|
||
|
||
## 📁 Структура проекта
|
||
|
||
```
|
||
src/
|
||
├── __data__/
|
||
│ ├── api/
|
||
│ │ └── api.ts # RTK Query API endpoints
|
||
│ ├── kc.ts # Keycloak конфигурация
|
||
│ ├── store.ts # Redux store
|
||
│ └── urls.ts # URL константы
|
||
├── components/
|
||
│ ├── ui/
|
||
│ │ └── toaster.tsx # Toast уведомления
|
||
│ ├── ConfirmDialog.tsx # Диалог подтверждения
|
||
│ ├── EmptyState.tsx # Пустое состояние
|
||
│ ├── ErrorAlert.tsx # Отображение ошибок
|
||
│ ├── Layout.tsx # Общий layout с навигацией
|
||
│ ├── LoadingSpinner.tsx # Индикатор загрузки
|
||
│ ├── StatCard.tsx # Карточка метрики
|
||
│ └── StatusBadge.tsx # Бейдж статуса
|
||
├── pages/
|
||
│ ├── dashboard/
|
||
│ │ └── DashboardPage.tsx # Главная страница
|
||
│ ├── tasks/
|
||
│ │ ├── TasksListPage.tsx # Список заданий
|
||
│ │ └── TaskFormPage.tsx # Форма задания
|
||
│ ├── chains/
|
||
│ │ ├── ChainsListPage.tsx # Список цепочек
|
||
│ │ └── ChainFormPage.tsx # Форма цепочки
|
||
│ ├── users/
|
||
│ │ └── UsersPage.tsx # Список пользователей
|
||
│ └── submissions/
|
||
│ └── SubmissionsPage.tsx # Список попыток
|
||
├── types/
|
||
│ └── challenge.ts # TypeScript типы
|
||
├── app.tsx # Главный компонент
|
||
├── dashboard.tsx # Роутинг
|
||
├── index.tsx # Entry point
|
||
└── theme.tsx # Chakra UI theme
|
||
```
|
||
|
||
## 🔐 Авторизация
|
||
|
||
Приложение требует авторизации через **Keycloak** с ролью **`teacher`** в клиенте **`journal`**.
|
||
|
||
Конфигурация в `bro.config.js`:
|
||
```javascript
|
||
KC_URL: 'https://auth.brojs.ru'
|
||
KC_REALM: 'itpark'
|
||
KC_CLIENT_ID: 'journal'
|
||
```
|
||
|
||
Все API запросы автоматически отправляют Bearer токен через RTK Query middleware.
|
||
|
||
## 🚀 Запуск проекта
|
||
|
||
```bash
|
||
# Установка зависимостей
|
||
npm install
|
||
|
||
# Запуск в режиме разработки (с стабами API)
|
||
npm start
|
||
|
||
# Сборка для production
|
||
npm run build:prod
|
||
```
|
||
|
||
Приложение будет доступно по адресу: `http://localhost:8099`
|
||
|
||
### 📡 Стабовый API сервер
|
||
|
||
Проект включает полнофункциональный стабовый API сервер для разработки и тестирования без реального бэкенда.
|
||
|
||
**Тестовые данные:**
|
||
- `stubs/api/data/tasks.json` - 5 заданий с hiddenInstructions
|
||
- `stubs/api/data/chains.json` - 3 цепочки заданий
|
||
- `stubs/api/data/users.json` - 8 пользователей
|
||
- `stubs/api/data/submissions.json` - 8 попыток с feedback от LLM
|
||
- `stubs/api/data/stats.json` - системная статистика
|
||
|
||
**Возможности:**
|
||
- ✅ Полный CRUD для заданий и цепочек
|
||
- ✅ In-memory хранилище (изменения сбрасываются при перезапуске)
|
||
- ✅ Автоматическое обновление статистики
|
||
- ✅ Генерация статистики пользователей на лету
|
||
- ✅ Поддержка всех endpoints из документации
|
||
|
||
**Примечание:** Все ответы возвращаются в формате `{ error: null, data: ... }`
|
||
|
||
## 📡 API Endpoints
|
||
|
||
Все endpoints используют базовый URL из конфига (`/api`).
|
||
|
||
### Tasks
|
||
- `GET /challenge/tasks` - список заданий
|
||
- `GET /challenge/task/:id` - одно задание
|
||
- `POST /challenge/task` - создать задание
|
||
- `PUT /challenge/task/:id` - обновить задание
|
||
- `DELETE /challenge/task/:id` - удалить задание
|
||
|
||
### Chains
|
||
- `GET /challenge/chains` - список цепочек
|
||
- `GET /challenge/chain/:id` - одна цепочка
|
||
- `POST /challenge/chain` - создать цепочку
|
||
- `PUT /challenge/chain/:id` - обновить цепочку
|
||
- `DELETE /challenge/chain/:id` - удалить цепочку
|
||
|
||
### Users & Stats
|
||
- `GET /challenge/users` - список пользователей
|
||
- `GET /challenge/stats` - общая статистика системы
|
||
- `GET /challenge/user/:userId/stats` - статистика пользователя
|
||
|
||
### Submissions
|
||
- `GET /challenge/submissions` - все попытки
|
||
- `GET /challenge/user/:userId/submissions` - попытки пользователя
|
||
|
||
## ⚙️ Ключевые особенности реализации
|
||
|
||
### RTK Query с кэшированием
|
||
Настроены `tagTypes` для автоматической инвалидации кэша:
|
||
- `Task` - для заданий
|
||
- `Chain` - для цепочек
|
||
- `User` - для пользователей
|
||
- `Submission` - для попыток
|
||
- `Stats` - для статистики
|
||
|
||
### Real-time обновления
|
||
Dashboard использует `pollingInterval: 10000` для автоматического обновления статистики каждые 10 секунд.
|
||
|
||
### hiddenInstructions (Скрытые инструкции)
|
||
Специальное поле только для преподавателей:
|
||
- Визуально выделено фиолетовым цветом
|
||
- Передаётся LLM при проверке решений
|
||
- Не видно студентам
|
||
- Позволяет тонко настроить проверку
|
||
|
||
### UX оптимизации
|
||
- Loading состояния для всех запросов
|
||
- Toast уведомления для успеха/ошибок
|
||
- Confirm диалоги для опасных действий (удаление)
|
||
- Empty states для пустых списков
|
||
- Поиск и фильтрация на всех страницах
|
||
- Адаптивный дизайн
|
||
|
||
## 🔗 Навигация
|
||
|
||
Переход между проектами настроен через `bro.config.js`:
|
||
```javascript
|
||
navigations: {
|
||
'challenge-admin-pl.main': '/challenge-admin-pl',
|
||
'link.challenge': '/challenge',
|
||
}
|
||
```
|
||
|
||
В Layout есть кнопка "Открыть проигрыватель" для перехода к студенческому интерфейсу.
|
||
|
||
## 📝 Документация
|
||
|
||
Подробная документация по API и архитектуре системы находится в папке `docs/`:
|
||
- `CHALLENGE_FRONTEND_GUIDE.md` - руководство для фронтенд разработчиков
|
||
- `TEACHER_GUIDE.md` - руководство для преподавателей
|
||
- `CHALLENGE_ANALYTICS_SUMMARY.md` - аналитика и метрики
|
||
- `CHALLENGE_REACT_EXAMPLE.md` - примеры React компонентов
|
||
|
||
## ✨ Дополнительно
|
||
|
||
- Все компоненты типизированы с TypeScript
|
||
- Markdown поддержка с превью и стилизацией
|
||
- Обработка ошибок API с понятными сообщениями
|
||
- Валидация форм
|
||
- Responsive design
|
||
|
||
---
|
||
|
||
**Версия:** 1.0.0
|
||
**Дата:** Ноябрь 2025
|
||
**Статус:** ✅ Production Ready
|
||
|