Update README.md to provide comprehensive documentation for the Challenge Platform frontend, including project description, features for students and teachers, technology stack, project structure, installation instructions, API endpoints, configuration, local development setup, user roles, and key functionalities.

2025-11-03 13:00:46 +03:00 · 2025-11-03 13:00:46 +03:00 · 9b511a8e1e
commit 9b511a8e1e
parent 624280ab5e
1 changed files with 230 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1,2 +1,231 @@
-# challenge-pl
+# 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 (в разработке)