challenge-admin-pl/stubs/api/README.md

Challenge Admin API Stubs

Стабовый API сервер для разработки и тестирования админской панели Challenge Service.

📁 Структура

stubs/api/
├── data/              # JSON файлы с тестовыми данными
│   ├── tasks.json     # Задания (5 шт.)
│   ├── chains.json    # Цепочки (3 шт.)
│   ├── users.json     # Пользователи (8 шт.)
│   ├── submissions.json  # Попытки (8 шт.)
│   ├── stats.json     # Системная статистика (v1)
│   └── stats-v2.json  # Детальная статистика (v2, 20 заданий)
├── index.js           # API роуты
└── README.md          # Эта документация

🔧 Реализованные endpoints

Tasks (Задания)

• GET /api/challenge/tasks - список всех заданий
• GET /api/challenge/task/:id - одно задание
• POST /api/challenge/task - создать задание
• PUT /api/challenge/task/:id - обновить задание
• DELETE /api/challenge/task/:id - удалить задание

Chains (Цепочки)

• GET /api/challenge/chains - список всех цепочек
• GET /api/challenge/chain/:id - одна цепочка
• POST /api/challenge/chain - создать цепочку
• PUT /api/challenge/chain/:id - обновить цепочку
• DELETE /api/challenge/chain/:id - удалить цепочку

Users (Пользователи)

• GET /api/challenge/users - список всех пользователей

Statistics (Статистика)

• GET /api/challenge/stats - общая системная статистика (v1)
• GET /api/challenge/stats/v2 - детальная статистика с таблицами и прогрессом (v2)
• GET /api/challenge/user/:userId/stats - статистика пользователя (генерируется динамически)

Submissions (Попытки)

• GET /api/challenge/submissions - все попытки
• GET /api/challenge/user/:userId/submissions?taskId=xxx - попытки пользователя (с опциональной фильтрацией по заданию)

📝 Формат ответов

Все ответы возвращаются в формате:

Успешный ответ

{
  "success": true,
  "body": <данные>
}

Ошибка

{
  "success": false,
  "body": null,
  "error": {
    "message": "Описание ошибки"
  }
}

💾 In-memory хранилище

Стабовый сервер использует in-memory хранилище:

• JSON файлы загружаются в память при первом запросе
• Все изменения (CREATE/UPDATE/DELETE) сохраняются только в памяти
• При перезапуске сервера все изменения сбрасываются
• Оригинальные JSON файлы не изменяются

🎯 Особенности

1. Автоматическое обновление статистики

При создании/удалении задания или цепочки автоматически обновляется системная статистика.

2. Динамическая генерация статистики пользователей

Endpoint /api/challenge/user/:userId/stats генерирует статистику на лету на основе:

• Попыток пользователя (submissions)
• Доступных цепочек
• Статуса заданий

3. Populate для цепочек

При создании/обновлении цепочки задания автоматически populated из списка заданий.

4. Валидация

Стабовый сервер включает базовую валидацию:

• Проверка обязательных полей
• Проверка существования ресурсов
• Возврат корректных HTTP статусов (404, 400)

📊 Тестовые данные

Задания (5 шт.)

1. Реализовать сортировку массива - с hiddenInstructions о сложности O(n log n)
2. Создать REST API endpoint - с требованием пагинации
3. Компонент React формы - с валидацией
4. SQL запрос с JOIN - без hiddenInstructions
5. Валидация формы - с проверкой edge cases

Цепочки (3 шт.)

1. Основы JavaScript - 2 задания
2. React разработка - 1 задание
3. Backend разработка - 2 задания

Пользователи (8 шт.)

• alex_student, maria_dev, ivan_coder, olga_js
• dmitry_react, anna_frontend, sergey_backend, elena_fullstack

Попытки (8 шт.)

Различные статусы:

• accepted (5) - принятые решения
• needs_revision (3) - требующие доработки
• Включают реалистичный feedback от LLM

🔄 Примеры запросов

Создать задание

POST /api/challenge/task
Content-Type: application/json

{
  "title": "Новое задание",
  "description": "# Описание\n\nТекст задания...",
  "hiddenInstructions": "Проверь алгоритм..."
}

Создать цепочку

POST /api/challenge/chain
Content-Type: application/json

{
  "name": "Моя цепочка",
  "tasks": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
}

Получить статистику пользователя

GET /api/challenge/user/user001/stats

Ответ будет содержать динамически вычисленную статистику на основе всех попыток пользователя.

Получить детальную статистику (v2)

GET /api/challenge/stats/v2

Ответ будет содержать:

• Базовую статистику (users, tasks, chains, submissions, queue)
• Таблицу заданий с детальной статистикой (20 заданий с попытками, успешностью, средними показателями)
• 6 активных участников с прогрессом по цепочкам
• Детальную матрицу прогресса по каждой из 2 цепочек (Backend разработка - 10 заданий, Frontend разработка - 10 заданий)

⚙️ Настройка задержки

По умолчанию все запросы имеют задержку 300ms для имитации сетевых запросов. Изменить можно в index.js:

const timer = (time = 300) => (req, res, next) => setTimeout(next, time);

🚀 Использование

Стабы автоматически подключаются при запуске dev сервера:

npm start

Сервер будет доступен на http://localhost:8099

---

Примечание: Этот стабовый API предназначен только для разработки. В production окружении используйте реальный Challenge Service API.