694 lines
24 KiB
Markdown
694 lines
24 KiB
Markdown
# API Статистики v2 - Документация для Frontend
|
||
|
||
## Обзор
|
||
|
||
Эндпоинт `/challenge/stats/v2` предоставляет расширенную статистику системы проверки заданий с детальными данными для построения таблиц и прогресс-баров.
|
||
|
||
## Эндпоинт
|
||
|
||
```
|
||
GET /challenge/stats/v2
|
||
```
|
||
|
||
### Аутентификация
|
||
|
||
Не требуется.
|
||
|
||
### Параметры запроса
|
||
|
||
| Параметр | Тип | Обязательный | Описание |
|
||
|----------|-----|--------------|----------|
|
||
| `chainId` | string | Нет | ID цепочки для фильтрации статистики. Если указан, возвращается статистика только по заданиям из этой цепочки |
|
||
|
||
#### Примеры использования
|
||
|
||
Получить полную статистику:
|
||
```
|
||
GET /challenge/stats/v2
|
||
```
|
||
|
||
Получить статистику только по одной цепочке:
|
||
```
|
||
GET /challenge/stats/v2?chainId=507f1f77bcf86cd799439031
|
||
```
|
||
|
||
## Структура ответа
|
||
|
||
```typescript
|
||
{
|
||
success: true,
|
||
body: {
|
||
// ========== БАЗОВАЯ СТАТИСТИКА (из v1) ==========
|
||
users: number, // Общее количество пользователей
|
||
tasks: number, // Общее количество заданий
|
||
chains: number, // Общее количество цепочек
|
||
submissions: {
|
||
total: number, // Всего попыток
|
||
accepted: number, // Принятых
|
||
rejected: number, // Отклоненных
|
||
pending: number, // Ожидающих проверки
|
||
inProgress: number // В процессе проверки
|
||
},
|
||
averageCheckTimeMs: number, // Среднее время проверки в мс
|
||
queue: {
|
||
queueLength: number,
|
||
waiting: number,
|
||
inProgress: number,
|
||
maxConcurrency: number,
|
||
currentlyProcessing: number
|
||
},
|
||
|
||
// ========== НОВЫЕ ДАННЫЕ V2 ==========
|
||
|
||
// Таблица заданий с детальной статистикой
|
||
tasksTable: Array<{
|
||
taskId: string,
|
||
title: string,
|
||
totalAttempts: number, // Всего попыток по всем пользователям
|
||
uniqueUsers: number, // Количество уникальных пользователей
|
||
acceptedCount: number, // Количество успешных прохождений
|
||
successRate: number, // Процент успешного прохождения (0-100)
|
||
averageAttemptsToSuccess: number // Среднее количество попыток до успеха
|
||
}>,
|
||
|
||
// Активные участники с прогрессом
|
||
activeParticipants: Array<{
|
||
userId: string,
|
||
nickname: string,
|
||
totalSubmissions: number, // Всего попыток пользователя
|
||
completedTasks: number, // Завершенных заданий
|
||
chainProgress: Array<{ // Прогресс по каждой цепочке
|
||
chainId: string,
|
||
chainName: string,
|
||
totalTasks: number, // Всего заданий в цепочке
|
||
completedTasks: number, // Завершено заданий
|
||
progressPercent: number // Процент прохождения (0-100)
|
||
}>
|
||
}>,
|
||
|
||
// Детальная информация по цепочкам
|
||
chainsDetailed: Array<{
|
||
chainId: string,
|
||
name: string,
|
||
totalTasks: number,
|
||
tasks: Array<{ // Список заданий в цепочке
|
||
taskId: string,
|
||
title: string,
|
||
description: string
|
||
}>,
|
||
participantProgress: Array<{ // Прогресс каждого участника
|
||
userId: string,
|
||
nickname: string,
|
||
taskProgress: Array<{ // Статус по каждому заданию
|
||
taskId: string,
|
||
taskTitle: string,
|
||
status: 'not_started' | 'pending' | 'in_progress' | 'needs_revision' | 'completed'
|
||
}>,
|
||
completedCount: number, // Завершено заданий
|
||
progressPercent: number // Процент прохождения (0-100)
|
||
}>
|
||
}>
|
||
}
|
||
}
|
||
```
|
||
|
||
## Пример ответа
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"body": {
|
||
"users": 34,
|
||
"tasks": 22,
|
||
"chains": 2,
|
||
"submissions": {
|
||
"total": 39,
|
||
"accepted": 16,
|
||
"rejected": 23,
|
||
"pending": 0,
|
||
"inProgress": 0
|
||
},
|
||
"averageCheckTimeMs": 2043,
|
||
"queue": {
|
||
"queueLength": 0,
|
||
"waiting": 0,
|
||
"inProgress": 0,
|
||
"maxConcurrency": 1,
|
||
"currentlyProcessing": 0
|
||
},
|
||
"tasksTable": [
|
||
{
|
||
"taskId": "507f1f77bcf86cd799439011",
|
||
"title": "Создание REST API",
|
||
"totalAttempts": 45,
|
||
"uniqueUsers": 12,
|
||
"acceptedCount": 8,
|
||
"successRate": 67,
|
||
"averageAttemptsToSuccess": 2.3
|
||
},
|
||
{
|
||
"taskId": "507f1f77bcf86cd799439012",
|
||
"title": "Работа с базой данных",
|
||
"totalAttempts": 38,
|
||
"uniqueUsers": 10,
|
||
"acceptedCount": 6,
|
||
"successRate": 60,
|
||
"averageAttemptsToSuccess": 3.1
|
||
}
|
||
],
|
||
"activeParticipants": [
|
||
{
|
||
"userId": "507f1f77bcf86cd799439021",
|
||
"nickname": "student1",
|
||
"totalSubmissions": 15,
|
||
"completedTasks": 5,
|
||
"chainProgress": [
|
||
{
|
||
"chainId": "507f1f77bcf86cd799439031",
|
||
"chainName": "Основы Backend",
|
||
"totalTasks": 10,
|
||
"completedTasks": 5,
|
||
"progressPercent": 50
|
||
},
|
||
{
|
||
"chainId": "507f1f77bcf86cd799439032",
|
||
"chainName": "Frontend разработка",
|
||
"totalTasks": 8,
|
||
"completedTasks": 0,
|
||
"progressPercent": 0
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"chainsDetailed": [
|
||
{
|
||
"chainId": "507f1f77bcf86cd799439031",
|
||
"name": "Основы Backend",
|
||
"totalTasks": 10,
|
||
"tasks": [
|
||
{
|
||
"taskId": "507f1f77bcf86cd799439011",
|
||
"title": "Создание REST API",
|
||
"description": "Создайте простой REST API с использованием Express.js"
|
||
},
|
||
{
|
||
"taskId": "507f1f77bcf86cd799439012",
|
||
"title": "Работа с базой данных",
|
||
"description": "Интегрируйте MongoDB в ваше приложение"
|
||
}
|
||
],
|
||
"participantProgress": [
|
||
{
|
||
"userId": "507f1f77bcf86cd799439021",
|
||
"nickname": "student1",
|
||
"taskProgress": [
|
||
{
|
||
"taskId": "507f1f77bcf86cd799439011",
|
||
"taskTitle": "Создание REST API",
|
||
"status": "completed"
|
||
},
|
||
{
|
||
"taskId": "507f1f77bcf86cd799439012",
|
||
"taskTitle": "Работа с базой данных",
|
||
"status": "needs_revision"
|
||
}
|
||
],
|
||
"completedCount": 1,
|
||
"progressPercent": 10
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Фильтрация по цепочке
|
||
|
||
При передаче параметра `chainId`:
|
||
|
||
1. **tasksTable** - содержит только задания из указанной цепочки
|
||
2. **activeParticipants** - включает только участников, которые делали попытки по заданиям этой цепочки. В `chainProgress` будет информация только об указанной цепочке
|
||
3. **chainsDetailed** - содержит информацию только об указанной цепочке
|
||
|
||
### Пример фильтрованного ответа
|
||
|
||
```bash
|
||
curl http://localhost:3000/challenge/stats/v2?chainId=507f1f77bcf86cd799439031
|
||
```
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"body": {
|
||
"users": 34,
|
||
"tasks": 22,
|
||
"chains": 2,
|
||
"submissions": {
|
||
"total": 39,
|
||
"accepted": 16,
|
||
"rejected": 23,
|
||
"pending": 0,
|
||
"inProgress": 0
|
||
},
|
||
"averageCheckTimeMs": 2043,
|
||
"queue": { ... },
|
||
"tasksTable": [
|
||
// Только задания из цепочки 507f1f77bcf86cd799439031
|
||
{
|
||
"taskId": "507f1f77bcf86cd799439011",
|
||
"title": "Создание REST API",
|
||
"totalAttempts": 45,
|
||
"uniqueUsers": 12,
|
||
"acceptedCount": 8,
|
||
"successRate": 67,
|
||
"averageAttemptsToSuccess": 2.3
|
||
}
|
||
],
|
||
"activeParticipants": [
|
||
// Только участники с попытками в этой цепочке
|
||
{
|
||
"userId": "507f1f77bcf86cd799439021",
|
||
"nickname": "student1",
|
||
"totalSubmissions": 10,
|
||
"completedTasks": 3,
|
||
"chainProgress": [
|
||
// Только одна цепочка
|
||
{
|
||
"chainId": "507f1f77bcf86cd799439031",
|
||
"chainName": "Основы Backend",
|
||
"totalTasks": 10,
|
||
"completedTasks": 3,
|
||
"progressPercent": 30
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"chainsDetailed": [
|
||
// Только указанная цепочка
|
||
{
|
||
"chainId": "507f1f77bcf86cd799439031",
|
||
"name": "Основы Backend",
|
||
"totalTasks": 10,
|
||
"tasks": [...],
|
||
"participantProgress": [...]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Использование в UI компонентах
|
||
|
||
### 1. Таблица заданий
|
||
|
||
Используйте `tasksTable` для отображения статистики по каждому заданию:
|
||
|
||
```tsx
|
||
// React пример
|
||
function TasksTable({ tasksTable }) {
|
||
return (
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Название задания</th>
|
||
<th>Попыток</th>
|
||
<th>Уникальных пользователей</th>
|
||
<th>Успешно завершено</th>
|
||
<th>% успеха</th>
|
||
<th>Среднее попыток до успеха</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
{tasksTable.map(task => (
|
||
<tr key={task.taskId}>
|
||
<td>{task.title}</td>
|
||
<td>{task.totalAttempts}</td>
|
||
<td>{task.uniqueUsers}</td>
|
||
<td>{task.acceptedCount}</td>
|
||
<td>{task.successRate}%</td>
|
||
<td>{task.averageAttemptsToSuccess.toFixed(1)}</td>
|
||
</tr>
|
||
))}
|
||
</tbody>
|
||
</table>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 2. Прогресс-бары участников
|
||
|
||
Используйте `activeParticipants` для отображения прогресса каждого участника:
|
||
|
||
```tsx
|
||
// React пример
|
||
function ParticipantProgress({ activeParticipants }) {
|
||
return (
|
||
<div>
|
||
{activeParticipants.map(participant => (
|
||
<div key={participant.userId} className="participant-card">
|
||
<h3>{participant.nickname}</h3>
|
||
<p>Завершено заданий: {participant.completedTasks}</p>
|
||
<p>Всего попыток: {participant.totalSubmissions}</p>
|
||
|
||
<div className="chain-progress">
|
||
{participant.chainProgress.map(chain => (
|
||
<div key={chain.chainId} className="chain-item">
|
||
<div className="chain-header">
|
||
<span>{chain.chainName}</span>
|
||
<span>{chain.completedTasks}/{chain.totalTasks}</span>
|
||
</div>
|
||
<div className="progress-bar">
|
||
<div
|
||
className="progress-fill"
|
||
style={{ width: `${chain.progressPercent}%` }}
|
||
/>
|
||
</div>
|
||
<span className="progress-text">{chain.progressPercent}%</span>
|
||
</div>
|
||
))}
|
||
</div>
|
||
</div>
|
||
))}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 3. Детальный прогресс по цепочкам
|
||
|
||
Используйте `chainsDetailed` для отображения детального прогресса всех участников в рамках каждой цепочки:
|
||
|
||
```tsx
|
||
// React пример
|
||
function ChainDetailedView({ chainsDetailed }) {
|
||
return (
|
||
<div>
|
||
{chainsDetailed.map(chain => (
|
||
<div key={chain.chainId} className="chain-detailed">
|
||
<h2>{chain.name}</h2>
|
||
<p>Заданий в цепочке: {chain.totalTasks}</p>
|
||
|
||
{/* Список заданий */}
|
||
<div className="tasks-list">
|
||
<h3>Задания:</h3>
|
||
{chain.tasks.map(task => (
|
||
<div key={task.taskId} className="task-item">
|
||
<h4>{task.title}</h4>
|
||
<p>{task.description}</p>
|
||
</div>
|
||
))}
|
||
</div>
|
||
|
||
{/* Прогресс участников */}
|
||
<div className="participants-progress">
|
||
<h3>Прогресс участников:</h3>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Участник</th>
|
||
{chain.tasks.map(task => (
|
||
<th key={task.taskId}>{task.title}</th>
|
||
))}
|
||
<th>Прогресс</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
{chain.participantProgress.map(participant => (
|
||
<tr key={participant.userId}>
|
||
<td>{participant.nickname}</td>
|
||
{participant.taskProgress.map(taskProg => (
|
||
<td key={taskProg.taskId}>
|
||
<StatusBadge status={taskProg.status} />
|
||
</td>
|
||
))}
|
||
<td>{participant.progressPercent}%</td>
|
||
</tr>
|
||
))}
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
))}
|
||
</div>
|
||
);
|
||
}
|
||
|
||
// Компонент для отображения статуса
|
||
function StatusBadge({ status }) {
|
||
const statusConfig = {
|
||
'not_started': { label: 'Не начато', color: 'gray' },
|
||
'pending': { label: 'Ожидает', color: 'yellow' },
|
||
'in_progress': { label: 'В процессе', color: 'blue' },
|
||
'needs_revision': { label: 'Доработка', color: 'orange' },
|
||
'completed': { label: 'Завершено', color: 'green' }
|
||
};
|
||
|
||
const config = statusConfig[status];
|
||
|
||
return (
|
||
<span className={`badge badge-${config.color}`}>
|
||
{config.label}
|
||
</span>
|
||
);
|
||
}
|
||
```
|
||
|
||
## Рекомендации по использованию
|
||
|
||
### Производительность
|
||
|
||
- Эндпоинт выполняет множество агрегаций, поэтому может работать медленно при большом количестве данных
|
||
- Рекомендуется кэшировать результат на клиенте на 30-60 секунд
|
||
- Используйте loading индикаторы во время загрузки данных
|
||
|
||
```tsx
|
||
// Пример с кэшированием
|
||
function useStatsV2(chainId?: string) {
|
||
const [data, setData] = useState(null);
|
||
const [loading, setLoading] = useState(false);
|
||
const [error, setError] = useState(null);
|
||
const lastFetch = useRef(0);
|
||
|
||
const fetchStats = async (force = false) => {
|
||
const now = Date.now();
|
||
// Кэш на 60 секунд
|
||
if (!force && data && (now - lastFetch.current) < 60000) {
|
||
return data;
|
||
}
|
||
|
||
setLoading(true);
|
||
try {
|
||
const url = chainId
|
||
? `/challenge/stats/v2?chainId=${chainId}`
|
||
: '/challenge/stats/v2';
|
||
const response = await fetch(url);
|
||
const result = await response.json();
|
||
if (result.success) {
|
||
setData(result.body);
|
||
lastFetch.current = now;
|
||
}
|
||
} catch (err) {
|
||
setError(err);
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
};
|
||
|
||
useEffect(() => {
|
||
fetchStats();
|
||
}, [chainId]); // Перезагружаем при смене цепочки
|
||
|
||
return { data, loading, error, refetch: () => fetchStats(true) };
|
||
}
|
||
|
||
// Использование
|
||
function ChainStatistics() {
|
||
const [selectedChainId, setSelectedChainId] = useState<string | undefined>();
|
||
const { data, loading } = useStatsV2(selectedChainId);
|
||
|
||
if (loading) return <div>Загрузка...</div>;
|
||
|
||
return (
|
||
<div>
|
||
<select
|
||
value={selectedChainId || ''}
|
||
onChange={(e) => setSelectedChainId(e.target.value || undefined)}
|
||
>
|
||
<option value="">Все цепочки</option>
|
||
{data?.chainsDetailed.map(chain => (
|
||
<option key={chain.chainId} value={chain.chainId}>
|
||
{chain.name}
|
||
</option>
|
||
))}
|
||
</select>
|
||
|
||
<TasksTable tasksTable={data?.tasksTable} />
|
||
<ParticipantProgress activeParticipants={data?.activeParticipants} />
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### Фильтрация и сортировка
|
||
|
||
Все массивы данных можно фильтровать и сортировать на клиенте:
|
||
|
||
```tsx
|
||
// Сортировка таблицы заданий по проценту успеха
|
||
const sortedTasks = [...tasksTable].sort((a, b) => b.successRate - a.successRate);
|
||
|
||
// Фильтрация активных участников с прогрессом > 50%
|
||
const activeStudents = activeParticipants.filter(p =>
|
||
p.chainProgress.some(c => c.progressPercent > 50)
|
||
);
|
||
|
||
// Поиск участника по имени
|
||
const searchParticipant = (query) =>
|
||
activeParticipants.filter(p =>
|
||
p.nickname.toLowerCase().includes(query.toLowerCase())
|
||
);
|
||
```
|
||
|
||
### Визуализация данных
|
||
|
||
Для построения графиков и диаграмм используйте библиотеки типа:
|
||
- **Chart.js** / **Recharts** - для графиков прогресса
|
||
- **AG Grid** / **TanStack Table** - для таблиц с сортировкой
|
||
- **React Progress Bar** - для прогресс-баров
|
||
|
||
```tsx
|
||
// Пример с Chart.js
|
||
import { Bar } from 'react-chartjs-2';
|
||
|
||
function TasksSuccessChart({ tasksTable }) {
|
||
const data = {
|
||
labels: tasksTable.map(t => t.title),
|
||
datasets: [{
|
||
label: 'Процент успеха',
|
||
data: tasksTable.map(t => t.successRate),
|
||
backgroundColor: 'rgba(75, 192, 192, 0.6)',
|
||
}]
|
||
};
|
||
|
||
return <Bar data={data} />;
|
||
}
|
||
```
|
||
|
||
## Когда использовать фильтрацию по цепочке
|
||
|
||
### Используйте `chainId` когда:
|
||
|
||
1. **Страница отдельной цепочки** - пользователь просматривает детали конкретной цепочки
|
||
```tsx
|
||
function ChainDetailsPage({ chainId }) {
|
||
const { data } = useStatsV2(chainId);
|
||
return <ChainDashboard data={data} />;
|
||
}
|
||
```
|
||
|
||
2. **Улучшение производительности** - когда нужны данные только по одной цепочке, фильтрация на сервере работает быстрее
|
||
|
||
3. **Фокус на конкретной программе** - преподаватель хочет видеть прогресс по конкретному курсу/модулю
|
||
|
||
### НЕ используйте `chainId` когда:
|
||
|
||
1. **Общий дашборд** - нужна статистика по всем цепочкам
|
||
2. **Сравнение цепочек** - нужно показать метрики по всем цепочкам одновременно
|
||
3. **Общая аналитика** - нужны агрегированные данные по всей системе
|
||
|
||
## Различия между v1 и v2
|
||
|
||
| Параметр | v1 (/stats) | v2 (/stats/v2) | v2 с chainId |
|
||
|----------|-------------|----------------|--------------|
|
||
| Базовая статистика | ✅ | ✅ | ✅ |
|
||
| Таблица заданий | ❌ | ✅ (все) | ✅ (фильтр) |
|
||
| Прогресс участников | ❌ | ✅ (все) | ✅ (фильтр) |
|
||
| Детальный прогресс по цепочкам | ❌ | ✅ (все) | ✅ (одна) |
|
||
| Статистика по попыткам | Общая | Детальная | Детальная (фильтр) |
|
||
| Скорость работы | Быстро | Медленнее | Средняя |
|
||
|
||
## Обработка ошибок
|
||
|
||
```tsx
|
||
async function fetchStatsV2(chainId?: string) {
|
||
try {
|
||
const url = chainId
|
||
? `/challenge/stats/v2?chainId=${chainId}`
|
||
: '/challenge/stats/v2';
|
||
const response = await fetch(url);
|
||
|
||
if (!response.ok) {
|
||
throw new Error(`HTTP error! status: ${response.status}`);
|
||
}
|
||
|
||
const data = await response.json();
|
||
|
||
if (!data.success) {
|
||
throw new Error(data.error?.message || 'Unknown error');
|
||
}
|
||
|
||
return data.body;
|
||
} catch (error) {
|
||
console.error('Failed to fetch stats v2:', error);
|
||
|
||
// Специальная обработка для неверного chainId
|
||
if (error.message.includes('Chain not found')) {
|
||
showNotification('Цепочка не найдена', 'error');
|
||
// Перенаправить на страницу всех цепочек
|
||
window.location.href = '/chains';
|
||
} else {
|
||
showNotification('Не удалось загрузить статистику', 'error');
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Типичные ошибки
|
||
|
||
| Ошибка | Причина | Решение |
|
||
|--------|---------|---------|
|
||
| `Chain not found` | Передан несуществующий `chainId` | Проверить ID цепочки, показать ошибку пользователю |
|
||
| `500 Internal Server Error` | Проблема на сервере | Показать общее сообщение об ошибке, повторить запрос |
|
||
| Timeout | Слишком много данных | Использовать фильтрацию по `chainId` для уменьшения объема данных |
|
||
|
||
## Дополнительные возможности
|
||
|
||
### Экспорт данных
|
||
|
||
Данные можно экспортировать в CSV или Excel для анализа:
|
||
|
||
```typescript
|
||
function exportToCSV(tasksTable) {
|
||
const headers = ['Название', 'Попыток', 'Пользователей', 'Успешно', '% успеха', 'Средние попытки'];
|
||
const rows = tasksTable.map(task => [
|
||
task.title,
|
||
task.totalAttempts,
|
||
task.uniqueUsers,
|
||
task.acceptedCount,
|
||
task.successRate,
|
||
task.averageAttemptsToSuccess
|
||
]);
|
||
|
||
const csv = [headers, ...rows]
|
||
.map(row => row.join(','))
|
||
.join('\n');
|
||
|
||
const blob = new Blob([csv], { type: 'text/csv' });
|
||
const url = window.URL.createObjectURL(blob);
|
||
const a = document.createElement('a');
|
||
a.href = url;
|
||
a.download = 'tasks-statistics.csv';
|
||
a.click();
|
||
}
|
||
```
|
||
|
||
## Заключение
|
||
|
||
Эндпоинт `/stats/v2` предоставляет все необходимые данные для построения информативных дашбордов с таблицами заданий и прогресс-барами участников. Комбинируйте различные части данных для создания удобных UI компонентов.
|
||
|
||
Для дополнительной информации см. также:
|
||
- [CHALLENGE_FRONTEND_GUIDE.md](./CHALLENGE_FRONTEND_GUIDE.md) - общее руководство по работе с Challenge API
|
||
- [CHALLENGE_REACT_EXAMPLE.md](./CHALLENGE_REACT_EXAMPLE.md) - примеры React компонентов
|
||
|