challenge-pl/README.md

# Challenge Platform - Frontend

Фронтенд-приложение для системы проверки заданий через LLM (Challenge Service).

## Описание

Платформа позволяет студентам проходить цепочки заданий с автоматической проверкой через LLM, отслеживать прогресс и получать детальную обратную связь. Преподаватели имеют доступ к расширенной аналитике и панели администратора.

## Возможности

### Для студентов
- ✅ Персональный dashboard с прогрессом и рекомендациями
- ✅ Просмотр цепочек заданий и переход между задачами
- ✅ Отправка решений с real-time отслеживанием проверки (polling)
- ✅ Визуализация метрик: графики прогресса, timeline, heatmap активности
- ✅ Экспорт статистики в CSV
- ✅ Автосохранение черновиков решений (offline-режим)
- ✅ Уведомления о результатах проверки

### Для преподавателей (роль `teacher`)
- ✅ Панель администратора с системной аналитикой
- ✅ Метрики по заданиям: сложность, успешность, среднее время
- ✅ Мониторинг очереди проверок
- ✅ Выявление проблемных областей (длинная очередь, низкая успешность)
- ✅ A/B тестирование вариантов интерфейса
- ✅ Фильтрация заданий по сложности

## Технологический стек

- **React 18** + **TypeScript**
- **Chakra UI 3** (компонентная библиотека)
- **Redux Toolkit** + **RTK Query** (state management, API)
- **React Router** (маршрутизация)
- **Keycloak** (авторизация преподавателей)
- **BroJS CLI** (инфраструктура сборки)

## Структура проекта

```
src/
├── __data__/
│   ├── api/
│   │   └── api.ts              # RTK Query эндпоинты
│   ├── types.ts                # TypeScript типы
│   ├── store.ts                # Redux store
│   ├── urls.ts                 # URL-конфигурация
│   └── kc.ts                   # Keycloak клиент
├── components/
│   ├── personal/               # Компоненты для студентов
│   │   ├── PersonalDashboard.tsx
│   │   ├── TaskWorkspace.tsx
│   │   ├── StatCard.tsx
│   │   ├── ProgressChart.tsx
│   │   ├── TimelineChart.tsx
│   │   ├── ActivityHeatmap.tsx
│   │   ├── CheckStatusView.tsx
│   │   ├── ResultView.tsx
│   │   └── MobileDashboard.tsx
│   └── admin/                  # Компоненты для преподавателей
│       └── ABTestPanel.tsx
├── context/
│   └── ChallengeContext.tsx    # Контекст с кешем, polling, events
├── hooks/
│   └── useSubmission.ts        # Хук для отправки и отслеживания
├── pages/
│   ├── main/                   # Главная страница студента
│   │   └── main.tsx
│   └── admin/                  # Панель администратора
│       └── AdminDashboard.tsx
├── utils/
│   ├── analytics/              # Метрики и аналитика
│   │   └── index.ts
│   ├── polling.ts              # Менеджер polling с exp. backoff
│   ├── events.ts               # Event emitter
│   ├── drafts.ts               # Работа с черновиками
│   └── errors.ts               # Обработка ошибок
├── app.tsx                     # Корневой компонент
├── dashboard.tsx               # Роутинг
├── index.tsx                   # Entry point
└── theme.tsx                   # Chakra UI theme

stubs/api/
├── index.js                    # Express роутер для мок-данных
└── data/                       # JSON-стабы всех эндпоинтов
    ├── auth.json
    ├── chains.json
    ├── user-stats.json
    ├── user-submissions.json
    ├── system-stats.json
    ├── submissions.json
    ├── queue-status.json
    └── submit.json
```

## Установка и запуск

```bash
# Установка зависимостей
npm install

# Запуск dev-сервера
npm start

# Сборка production
npm run build:prod

# Линтинг
npm run eslint
npm run eslint:fix
```

## API эндпоинты

Приложение взаимодействует с Challenge Service API:

- `POST /api/challenge/auth` — Аутентификация по nickname
- `GET /api/challenge/chains` — Список цепочек заданий
- `GET /api/challenge/chain/:id` — Детали цепочки
- `GET /api/challenge/task/:id` — Детали задания
- `POST /api/challenge/submit` — Отправка решения
- `GET /api/challenge/check-status/:queueId` — Статус проверки (polling)
- `GET /api/challenge/user/:id/stats` — Статистика пользователя
- `GET /api/challenge/user/:id/submissions` — История отправок
- `GET /api/challenge/stats` — Системная статистика (только teacher)
- `GET /api/challenge/submissions` — Все отправки (только teacher)

## Конфигурация

Настройки задаются через `bro.config.js`:

```javascript
module.exports = {
  config: {
    journal: {
      back: {
        url: 'http://localhost:8082',
      },
    },
  },
  navigation: {
    'challenge.main': '/',
    'link.challenge.admin': '/admin',
  },
}
```

## Локальная разработка с моками

Для работы без бэкенда используются стабы из `stubs/api`:

```bash
# Запустить мок-сервер (если есть отдельный порт)
# или полагаться на brojs server, который использует stubs/api/index.js
npm start
```

Мок-данные находятся в `stubs/api/data/*.json` и возвращаются Express-роутером.

## Роли и доступ

### Студенты (любой пользователь)
- Доступ к главной странице (`/`)
- Аутентификация через nickname (без пароля)
- Просмотр своих заданий и статистики

### Преподаватели (роль `teacher` в Keycloak)
- Доступ к панели администратора (`/admin`)
- Просмотр системных метрик и всех отправок
- A/B тестирование
- Аналитика по заданиям и пользователям

Роль `teacher` должна быть назначена в Keycloak клиенте `journal`.

## Основные функции

### 1. ChallengeContext

Глобальный контекст предоставляет:
- Авторизацию пользователя (`login`, `logout`)
- Статистику и персональный dashboard
- Event emitter для уведомлений
- Polling manager с экспоненциальной задержкой
- Кеширование запросов (60 сек)
- Сохранение/загрузка черновиков

### 2. Polling механизм

Автоматическое отслеживание статуса проверки:
- Начальная задержка: 2 секунды
- Экспоненциальный рост до 10 секунд
- Автоматическая остановка при завершении

### 3. Метрики

Классы для сбора аналитики:
- `MetricsCollector` — производительность проверок
- `BehaviorTracker` — поведение пользователя (время, правки)
- Функции построения dashboard и визуализаций

### 4. Offline-режим

- Автосохранение черновиков в localStorage
- Индикатор офлайн-статуса
- Возможность продолжить работу без сети

## Типы данных

Все TypeScript-интерфейсы описаны в `src/__data__/types.ts`:

- `ChallengeUser`, `ChallengeTask`, `ChallengeChain`
- `ChallengeSubmission`, `QueueStatus`
- `UserStats`, `SystemStats`, `PersonalDashboard`
- `PerformanceMetrics`, `BehaviorMetrics`, `SuccessMetrics`
- Визуализация: `ProgressChartData`, `TimelineChartData`, `HeatmapData`
- A/B тестирование: `ABTestMetrics`

## Документация

Подробная аналитика и руководства находятся в:
- `memory bank/frontend/CHALLENGE_FRONTEND_GUIDE.md` — основное руководство
- `memory bank/frontend/CHALLENGE_REACT_EXAMPLE.md` — примеры компонентов
- `memory bank/frontend/CHALLENGE_ANALYTICS_SUMMARY.md` — метрики и дашборды
- `memory bank/frontend/TEACHER_GUIDE.md` — для преподавателей

## Лицензия

ISC

## Версия

0.0.0 (в разработке)