challenge-pl/UPDATE.md

# Добавление поля learningMaterial в задачу челленджа

## Описание изменений

В модель задачи челленджа (`ChallengeTask`) добавлено новое необязательное текстовое поле `learningMaterial` для хранения дополнительной обучающей информации в формате Markdown.

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

### Модель ChallengeTask

```typescript
{
  title: string,           // Заголовок задания (обязательное)
  description: string,     // Основное описание в Markdown (обязательное, видно студентам)
  learningMaterial: string, // Дополнительный учебный материал в Markdown (необязательное, видно студентам)
  hiddenInstructions: string, // Скрытые инструкции для LLM (необязательное, только для преподавателей)
  createdAt: Date,         // Дата создания
  updatedAt: Date,         // Дата последнего обновления
  creator: Object          // Данные создателя из Keycloak
}
```

## Изменения в API

### 1. Создание задания (POST /challenge/task)

**Добавлено поле в тело запроса:**
```json
{
  "title": "Название задания",
  "description": "Основное описание в Markdown",
  "learningMaterial": "Дополнительный учебный материал в Markdown",
  "hiddenInstructions": "Скрытые инструкции для преподавателей"
}
```

**Пример запроса:**
```bash
POST /challenge/task
Content-Type: application/json

{
  "title": "Реализация алгоритма сортировки",
  "description": "Напишите функцию сортировки массива методом пузырька",
  "learningMaterial": "## Теория\n\nМетод пузырьковой сортировки работает путем...\n\n## Полезные ссылки\n- [Википедия](https://ru.wikipedia.org/wiki/Сортировка_пузырьком)\n- [Видео объяснение](https://example.com/video)",
  "hiddenInstructions": "Оценить эффективность алгоритма и стиль кода"
}
```

### 2. Обновление задания (PUT /challenge/task/:taskId)

**Добавлено поле в тело запроса:**
```json
{
  "title": "Новое название",
  "description": "Обновленное описание",
  "learningMaterial": "Обновленный учебный материал",
  "hiddenInstructions": "Обновленные инструкции"
}
```

## Получение данных

### Получение задания (GET /challenge/task/:taskId)

**Ответ содержит новое поле:**
```json
{
  "id": "task_id",
  "title": "Название задания",
  "description": "Основное описание в Markdown",
  "learningMaterial": "Дополнительный учебный материал в Markdown",
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
```

**Важно:** Поле `learningMaterial` видно всем пользователям (студентам и преподавателям), в отличие от `hiddenInstructions`, которое скрывается от студентов.

### Получение всех заданий (GET /challenge/tasks)

Возвращает массив заданий с новым полем `learningMaterial`.

### Получение цепочек (GET /challenge/chains, GET /challenge/chain/:chainId)

При получении цепочек с populate заданий, поле `learningMaterial` будет доступно в каждом задании цепочки.

## Frontend изменения

### Интерфейсы TypeScript

```typescript
interface ChallengeTask {
  id: string;
  title: string;
  description: string;     // Markdown
  learningMaterial?: string; // Новое поле - дополнительный материал в Markdown
  createdAt: string;
  updatedAt: string;
}
```

### Формы создания/редактирования заданий

В формах создания и редактирования заданий необходимо добавить поле для ввода `learningMaterial`:

```typescript
// Пример компонента формы
const TaskForm = () => {
  const [formData, setFormData] = useState({
    title: '',
    description: '',
    learningMaterial: '', // Новое поле
    hiddenInstructions: ''
  });

  // Визуальный редактор или textarea для learningMaterial
  return (
    <form>
      <input name="title" value={formData.title} />
      <textarea name="description" value={formData.description} />

      {/* Новое поле для дополнительного материала */}
      <label>Дополнительный учебный материал (Markdown)</label>
      <textarea
        name="learningMaterial"
        value={formData.learningMaterial}
        placeholder="Дополнительные объяснения, ссылки, примеры..."
      />

      {/* Только для преподавателей */}
      <textarea name="hiddenInstructions" value={formData.hiddenInstructions} />
    </form>
  );
};
```

### Отображение заданий

При отображении задания студентам показывать `learningMaterial` как дополнительную информацию:

```typescript
const TaskView = ({ task }: { task: ChallengeTask }) => {
  return (
    <div>
      <h1>{task.title}</h1>

      {/* Основное описание */}
      <div dangerouslySetInnerHTML={{ __html: marked(task.description) }} />

      {/* Дополнительный учебный материал */}
      {task.learningMaterial && (
        <div className="learning-material">
          <h2>Дополнительные материалы</h2>
          <div dangerouslySetInnerHTML={{ __html: marked(task.learningMaterial) }} />
        </div>
      )}
    </div>
  );
};
```

## Миграция данных

Поле `learningMaterial` добавлено как необязательное с значением по умолчанию `''`, поэтому:
- Существующие задания будут работать без изменений
- Новое поле будет пустым для старых заданий
- Можно постепенно добавлять учебный материал к существующим заданиям

## Тестирование

### Создание задания с учебным материалом
```bash
# Создать задание с дополнительным материалом
POST /challenge/task
{
  "title": "Тестовое задание",
  "description": "Основное задание",
  "learningMaterial": "# Полезная информация\n\nЭто дополнительный материал для студентов"
}
```

### Получение задания
```bash
GET /challenge/task/{taskId}
# Проверить, что learningMaterial присутствует в ответе
```

### Обновление учебного материала
```bash
PUT /challenge/task/{taskId}
{
  "learningMaterial": "# Обновленная информация\n\nНовые полезные материалы..."
}
```

## Влияние на существующий код

- Все существующие эндпоинты получения данных автоматически возвращают новое поле
- Создание заданий без указания `learningMaterial` работает как прежде
- Фильтрация и валидация не затрагиваются
- Поле индексируется MongoDB автоматически