bro-js/challenge-admin-pl

Fork 0

Primakov Alexandr Alexandrovich e777b57991 init + api use

2025-11-03 17:59:08 +03:00

12 KiB

Raw Blame History

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:

KC_URL: 'https://auth.brojs.ru'
KC_REALM: 'itpark'
KC_CLIENT_ID: 'journal'

Все API запросы автоматически отправляют Bearer токен через RTK Query middleware.

🚀 Запуск проекта

# Установка зависимостей
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:

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

12 KiB Raw Blame History Unescape Escape