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

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

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

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

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

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

# Запустить мок-сервер (если есть отдельный порт)
# или полагаться на 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 (в разработке)