# 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