diff --git a/docs/CHALLENGE_LEARNING_MATERIAL.md b/docs/CHALLENGE_LEARNING_MATERIAL.md new file mode 100644 index 0000000..2118bcb --- /dev/null +++ b/docs/CHALLENGE_LEARNING_MATERIAL.md @@ -0,0 +1,202 @@ +# Добавление поля 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 ( +
+ +