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

# Challenge Service - Frontend Documentation

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

## 📚 Документы

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

1. **[CHALLENGE_FRONTEND_GUIDE.md](./CHALLENGE_FRONTEND_GUIDE.md)**
   - Основное руководство по интеграции
   - Сценарии использования
   - Структуры данных (TypeScript)
   - API взаимодействие
   - Готовые компоненты React
   - Best practices

2. **[CHALLENGE_REACT_EXAMPLE.md](./CHALLENGE_REACT_EXAMPLE.md)**
   - Полный пример React + TypeScript приложения
   - Готовый код компонентов
   - Custom hooks
   - State management
   - Стили

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```typescript
// Для студента
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
}
```

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

### Студенты

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

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

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

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

## 🎨 UI Components

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

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

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

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

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

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

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

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

```typescript
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 документация](../CHALLENGE_API_README.md)
- [Архитектура системы](../CHALLENGE_ARCHITECTURE.md)
- [Быстрый старт](../CHALLENGE_QUICK_START.md)

---

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