175 lines
6.6 KiB
Markdown
175 lines
6.6 KiB
Markdown
# 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 # Системная статистика
|
||
├── 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` - общая системная статистика
|
||
- `GET /api/challenge/user/:userId/stats` - статистика пользователя (генерируется динамически)
|
||
|
||
### Submissions (Попытки)
|
||
- `GET /api/challenge/submissions` - все попытки
|
||
- `GET /api/challenge/user/:userId/submissions?taskId=xxx` - попытки пользователя (с опциональной фильтрацией по заданию)
|
||
|
||
## 📝 Формат ответов
|
||
|
||
Все ответы возвращаются в формате:
|
||
|
||
### Успешный ответ
|
||
```json
|
||
{
|
||
"success": true,
|
||
"body": <данные>
|
||
}
|
||
```
|
||
|
||
### Ошибка
|
||
```json
|
||
{
|
||
"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
|
||
|
||
## 🔄 Примеры запросов
|
||
|
||
### Создать задание
|
||
```bash
|
||
POST /api/challenge/task
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"title": "Новое задание",
|
||
"description": "# Описание\n\nТекст задания...",
|
||
"hiddenInstructions": "Проверь алгоритм..."
|
||
}
|
||
```
|
||
|
||
### Создать цепочку
|
||
```bash
|
||
POST /api/challenge/chain
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "Моя цепочка",
|
||
"tasks": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
|
||
}
|
||
```
|
||
|
||
### Получить статистику пользователя
|
||
```bash
|
||
GET /api/challenge/user/user001/stats
|
||
```
|
||
|
||
Ответ будет содержать динамически вычисленную статистику на основе всех попыток пользователя.
|
||
|
||
## ⚙️ Настройка задержки
|
||
|
||
По умолчанию все запросы имеют задержку 300ms для имитации сетевых запросов. Изменить можно в `index.js`:
|
||
|
||
```javascript
|
||
const timer = (time = 300) => (req, res, next) => setTimeout(next, time);
|
||
```
|
||
|
||
## 🚀 Использование
|
||
|
||
Стабы автоматически подключаются при запуске dev сервера:
|
||
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
Сервер будет доступен на `http://localhost:8099`
|
||
|
||
---
|
||
|
||
**Примечание:** Этот стабовый API предназначен только для разработки. В production окружении используйте реальный Challenge Service API.
|
||
|