challenge-admin-pl/docs/updateAPI.md

Обновление API Challenge Service

Документ для frontend-разработчика. Описывает НОВЫЕ возможности и требования к клиенту.

Содержит два блока изменений:

• Управление видимостью цепочек заданий (поле isActive и новый админский эндпоинт).
• Тестовая проверка решения задания админом (флаг isTest и опциональные hiddenInstructions в /submit).

---

1. Управление видимостью цепочек заданий

1.1. Новое поле в модели цепочки

Поле isActive

• Тип: boolean
• По умолчанию: true
• Смысл: определяет, видна ли цепочка обычным пользователям в пользовательском списке.

В базе: поле уже есть в модели ChallengeChain, на фронте его нужно учитывать в админских интерфейсах.

---

1.2. Пользовательский список цепочек

GET /api/challenge/chains

• Назначение: список цепочек для студентов/обычных пользователей.
• Фильтрация на бэке: возвращаются только цепочки с isActive: true.
• Доступ: без специальных ролей.

Гарантии для фронтенда:

• Выключенные / черновые цепочки никогда не попадут в этот список.
• Можно строить каталог цепочек, не фильтруя по isActive на клиенте.

Упрощённая структура элемента:

{
  "id": "...",
  "name": "Основы программирования",
  "tasks": [
    {
      "id": "...",
      "title": "...",
      "description": "..."
      // Для не-преподавателей поля hiddenInstructions и creator отсутствуют
    }
  ],
  "isActive": true
}

Требования к фронтенду:

• Для пользовательских экранов достаточно этого эндпоинта, дополнительную фильтрацию по активности делать не нужно.

---

1.3. Админский список цепочек

GET /api/challenge/chains/admin

• Назначение: полный список цепочек (и включённых, и выключенных) для админских/преподавательских экранов.
• Фильтрации по активности нет — возвращаются все цепочки.
• Доступ: только роли teacher или challenge-author.
• Включает все данные по задачам, в т.ч. hiddenInstructions, creator.

Пример ответа (фрагмент):

{
  "error": null,
  "data": [
    {
      "id": "...",
      "name": "Основы программирования",
      "tasks": [
        {
          "id": "...",
          "title": "...",
          "description": "...",
          "hiddenInstructions": "...",
          "creator": { "sub": "...", "preferred_username": "teacher1" }
        }
      ],
      "isActive": true,
      "createdAt": "2023-10-29T12:00:00.000Z",
      "updatedAt": "2023-10-29T12:00:00.000Z"
    }
  ]
}

Требования к фронтенду (админский UI):

• Использовать этот эндпоинт для экранов управления цепочками.
• Показывать состояние активности (isActive) каждой цепочки (badge, тумблер и т.п.).
• При ошибке 403 (нет роли teacher / challenge-author) отображать сообщение об отсутствии доступа и, при необходимости, перенаправлять на пользовательский список.

---

1.4. Создание и обновление цепочек с учётом активности

POST /api/challenge/chain

Роли: teacher или challenge-author.

Тело запроса:

{
  "name": "Основы программирования",
  "taskIds": ["...", "..."],
  "isActive": true // опционально, по умолчанию true
}

• Если isActive не передан, цепочка создаётся активной.

Требования к фронтенду:

• На форме создания цепочки можно:
  • либо не показывать тумблер активности (все новые будут активными),
  • либо добавить переключатель «Активна» и передавать isActive: false для черновиков.

PUT /api/challenge/chain/:chainId

Роли: teacher или challenge-author.

Тело запроса (все поля опциональны):

{
  "name": "Новое имя",      
  "taskIds": ["..."],       
  "isActive": false          
}

• Если isActive передан, его значение меняет активность цепочки.
• Если isActive не передан, активность не меняется.

Сценарии:

• Включить цепочку: PUT /api/challenge/chain/:id с { "isActive": true }.
• Выключить цепочку (спрятать из пользовательского списка): { "isActive": false }.
• Переименовать / поменять задачи без изменения активности: отправлять только name / taskIds без поля isActive.

Требования к UI:

• На экране «управление цепочками» (данные из /chains/admin):
  • показывать isActive;
  • давать возможность включать/выключать цепочку (тумблер → вызов PUT /chain/:id с нужным isActive).

---

2. Тестовая проверка решения задания (без записи прогресса)

Добавлен режим тестовой проверки решения, который позволяет преподавателю/автору проверить ответ через LLM без создания попытки и без постановки в очередь.

2.1. Расширение эндпоинта отправки решения

POST /api/challenge/submit

К существующему API добавлены новые опциональные поля в теле запроса:

{
  "userId": "...",      
  "taskId": "...",      
  "result": "...",      
  "isTest": true,              // НОВОЕ: флаг тестового режима
  "hiddenInstructions": "..." // НОВОЕ: опциональные инструкции для проверки
}

2.2. Обычный режим (без isTest)

• Если isTest не передан или false — поведение НЕ изменилось:
  • проверяется существование пользователя по userId;
  • считается количество попыток;
  • создаётся ChallengeSubmission;
  • попытка ставится в очередь на проверку через LLM;
  • в ответе фронтенд получает queueId и submissionId.

2.3. Тестовый режим (isTest: true)

• Доступен только для ролей teacher / challenge-author (проверка через isTeacher(req, true)).
• Не создаётся запись ChallengeSubmission.
• Не используется очередь проверки.
• Проверяется только существование задания (taskId), пользователь по userId в этом режиме не ищется и не нужен (но поле всё ещё формально обязательно по схеме).
• Если переданы hiddenInstructions, они используются вместо task.hiddenInstructions при формировании промпта для LLM.
• Никакие изменения инструкций, переданные через hiddenInstructions, не сохраняются в базу — это чисто временная инструкция для одной тестовой проверки.

Пример запроса (тестовый режим):

POST /api/challenge/submit
Content-Type: application/json
Authorization: Bearer <keycloak_token_teacher_or_author>

{
  "userId": "any-or-dummy-id",   
  "taskId": "507f1f77bcf86cd799439012",
  "result": "function solve() { ... }",
  "isTest": true,
  "hiddenInstructions": "ВРЕМЕННЫЕ инструкции для проверки, не сохраняются"
}

Пример ответа (тестовый режим):

{
  "error": null,
  "data": {
    "isTest": true,
    "status": "accepted",          // или "needs_revision"
    "feedback": "Развёрнутый комментарий от LLM"
  }
}

При отсутствии прав (нет роли teacher / challenge-author) вернётся 403.

2.4. Требования к фронтенду

• Где использовать тестовый режим:
  • только в админских/преподавательских интерфейсах (например, экран настройки задания или предпросмотр проверки);
  • использовать флаг isTest: true, когда нужно получить мгновенный ответ от LLM без записи в историю;
  • при наличии UI-редактора скрытых инструкций использовать hiddenInstructions для передачи временного варианта, не сохраняя его.
• Где НЕ использовать:
  • в пользовательском флоу сдачи заданий студентами — там должен использоваться обычный режим без isTest.
• UI-ожидания:
  • показывать администратору статус (accepted / needs_revision) и feedback;
  • явно обозначить в интерфейсе, что это «тестовая проверка» и она не попадает в статистику / попытки, а переданные hiddenInstructions не сохраняются.

---

3. Краткое резюме

• Для цепочек:
  • пользовательский список: GET /api/challenge/chains → только активные (isActive: true);
  • админский список: GET /api/challenge/chains/admin → все цепочки + управление isActive через POST/PUT /chain.
• Для отправки решений:
  • обычный режим без isTest — всё как раньше (очередь, попытки, статистика);
  • тестовый режим с isTest: true + опциональные hiddenInstructions — только для teacher/challenge-author, без записи прогресса, сразу возвращает результат проверки с учётом временных инструкций.