challenge-pl/memory bank/frontend/README.md

Challenge Service - Frontend Documentation

Документация для фронтенд-разработчиков и преподавателей.

📚 Документы

Для всех фронтенд-разработчиков

1. CHALLENGE_FRONTEND_GUIDE.md

   • Основное руководство по интеграции
   • Сценарии использования
   • Структуры данных (TypeScript)
   • API взаимодействие
   • Готовые компоненты React
   • Best practices

2. CHALLENGE_REACT_EXAMPLE.md

   • Полный пример React + TypeScript приложения
   • Готовый код компонентов
   • Custom hooks
   • State management
   • Стили

3. CHALLENGE_ANALYTICS_SUMMARY.md

   • Метрики для отслеживания
   • Дашборды (Personal, Admin)
   • Визуализация данных
   • Real-time уведомления
   • A/B тестирование

Для преподавателей 🔒

4. TEACHER_GUIDE.md
   • Работа со скрытыми инструкциями для LLM
   • Настройка Keycloak
   • Создание и редактирование заданий
   • UI компоненты для преподавателей
   • Best practices
   • Примеры реальных сценариев

🚀 Быстрый старт

Для студентов (обычные пользователи)

1. Прочитайте CHALLENGE_FRONTEND_GUIDE.md
2. Посмотрите примеры в CHALLENGE_REACT_EXAMPLE.md
3. Используйте готовые компоненты как основу

Для преподавателей

1. Прочитайте TEACHER_GUIDE.md 🔒
2. Настройте Keycloak (роль teacher)
3. Используйте скрытые инструкции для улучшения проверки

🎯 Ключевые особенности

Для студентов

• ✅ Простая аутентификация (nickname)
• ✅ Просмотр цепочек с прогрессом
• ✅ Отправка решений
• ✅ Real-time отслеживание проверки
• ✅ Персональная статистика
• ✅ Feedback от AI

Для преподавателей 🔒

• ✅ Создание заданий через Keycloak
• ✅ Скрытые инструкции для LLM
• ✅ Управление цепочками
• ✅ Просмотр статистики
• ✅ Контроль качества проверок

📊 Структура данных

Task (с учетом ролей)

// Для студента
interface ChallengeTask {
  _id: string
  title: string
  description: string // Markdown
  createdAt: string
}

// Для преподавателя (teacher)
interface ChallengeTask {
  _id: string
  title: string
  description: string // Markdown
  hiddenInstructions: string // 🔒 Только для преподавателей
  creator: object // 🔒 Только для преподавателей
  createdAt: string
}

🔐 Авторизация

Студенты

// Простая регистрация по nickname
POST /api/challenge/auth
{ "nickname": "student123" }

Преподаватели

// Запросы с токеном Keycloak
headers: {
  'Authorization': 'Bearer <keycloak_token>'
}

// Требуется роль 'teacher' в клиенте 'journal'

🎨 UI Components

Для студентов

• AuthForm - вход по nickname
• ChainList - список цепочек
• TaskView - просмотр и решение
• CheckStatus - отслеживание проверки
• ResultView - результат
• UserStats - статистика

Для преподавателей 🔒

• TeacherTaskForm - создание с hiddenInstructions
• TaskCard - с индикацией скрытых инструкций
• AdminDashboard - полная статистика

📖 Примеры использования

Создание задания (преподаватель)

const task = await createTask({
  title: "Реализовать сортировку",
  description: "# Задание\n\nНапишите функцию...",
  hiddenInstructions: "Проверь сложность алгоритма O(n log n)" // 🔒
})

Отправка решения (студент)

const { queueId } = await submitSolution(userId, taskId, result)

// Polling
const submission = await pollCheckStatus(queueId, (status) => {
  console.log('Status:', status.status)
})

🛠️ Технологии

• React + TypeScript
• Keycloak для авторизации преподавателей
• Context API / Redux для state
• React Markdown
• Fetch API

📚 Дополнительные ресурсы

• API документация
• Архитектура системы
• Быстрый старт

---

Версия: 1.0.0
Дата: 29 октября 2025
Статус: ✅ Production Ready