Создание единого проекта Lichess Statistics Ecosystem
- Объединены три проекта в один репозиторий - LichessWebServices - REST API для статистики - LichessClientTG_bot - Telegram бот с поддержкой множества пользователей - LichessWebView - Веб-интерфейс для просмотра пользователей и игроков - Добавлен общий docker-compose.yml для запуска всех сервисов - Добавлен скрипт start.sh для удобного запуска - Добавлен README с полным описанием проекта
This commit is contained in:
vrubelroman
commit
a08fc8c962
32 changed files with 4990 additions and 0 deletions
388
LichessWebServices/API_DOCUMENTATION.md
Normal file
388
LichessWebServices/API_DOCUMENTATION.md
Normal file
|
|
@ -0,0 +1,388 @@
|
|||
# Lichess Statistics API - Документация
|
||||
|
||||
## Описание
|
||||
|
||||
Lichess Statistics API предоставляет REST API для получения детальной статистики игроков платформы Lichess. API позволяет получать информацию о играх, рейтингах и решении задач (пазлов) за различные периоды времени.
|
||||
|
||||
## Возможности
|
||||
|
||||
- 📊 **Статистика игр** по режимам (Bullet, Blitz, Rapid)
|
||||
- 🧩 **Статистика решения задач** (пазлов)
|
||||
- 📅 **Статистика за разные периоды** (сегодня, вчера, неделя)
|
||||
- 🎯 **Отслеживание изменений рейтинга**
|
||||
- 📈 **Подробная аналитика результатов игр**
|
||||
|
||||
## Режимы игр
|
||||
|
||||
- **Bullet**: Быстрые игры (1-3 минуты)
|
||||
- **Blitz**: Блиц игры (3-10 минут)
|
||||
- **Rapid**: Рапид игры (10+ минут)
|
||||
|
||||
## Базовый URL
|
||||
|
||||
```
|
||||
http://localhost:8001
|
||||
```
|
||||
|
||||
## Эндпоинты
|
||||
|
||||
### 1. Информация об API
|
||||
|
||||
#### GET /
|
||||
Возвращает основную информацию об API и доступных эндпоинтах.
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"message": "Lichess Statistics API",
|
||||
"version": "1.0.0",
|
||||
"description": "REST API для получения статистики игроков Lichess",
|
||||
"endpoints": {
|
||||
"today": "/stats/{username}/today",
|
||||
"yesterday": "/stats/{username}/yesterday",
|
||||
"week": "/stats/{username}/week"
|
||||
},
|
||||
"documentation": "/docs",
|
||||
"openapi_schema": "/openapi.json"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Health Check
|
||||
|
||||
#### GET /health
|
||||
Проверка состояния сервиса.
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"service": "Lichess Statistics API"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Статистика за сегодня
|
||||
|
||||
#### GET /stats/{username}/today
|
||||
Получает статистику игрока за сегодняшний день.
|
||||
|
||||
**Параметры:**
|
||||
- `username` (string, обязательный) - имя пользователя на Lichess
|
||||
|
||||
**Пример запроса:**
|
||||
```bash
|
||||
curl http://localhost:8001/stats/magnus/today
|
||||
```
|
||||
|
||||
**Пример ответа:**
|
||||
```json
|
||||
{
|
||||
"message": "Статистика за сегодняшний день",
|
||||
"data": {
|
||||
"username": "magnus",
|
||||
"tasks": {
|
||||
"total": 15,
|
||||
"solved": 12,
|
||||
"unsolved": 3
|
||||
},
|
||||
"games": {
|
||||
"bullet": {
|
||||
"games_played": 8,
|
||||
"rating_change": 15,
|
||||
"final_rating": 2850,
|
||||
"wins": 5,
|
||||
"losses": 2,
|
||||
"draws": 1
|
||||
},
|
||||
"blitz": {
|
||||
"games_played": 3,
|
||||
"rating_change": -5,
|
||||
"final_rating": 2750,
|
||||
"wins": 1,
|
||||
"losses": 2,
|
||||
"draws": 0
|
||||
},
|
||||
"rapid": {
|
||||
"games_played": 0,
|
||||
"rating_change": 0,
|
||||
"final_rating": 0,
|
||||
"wins": 0,
|
||||
"losses": 0,
|
||||
"draws": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Статистика за вчера
|
||||
|
||||
#### GET /stats/{username}/yesterday
|
||||
Получает статистику игрока за вчерашний день.
|
||||
|
||||
**Параметры:**
|
||||
- `username` (string, обязательный) - имя пользователя на Lichess
|
||||
|
||||
**Пример запроса:**
|
||||
```bash
|
||||
curl http://localhost:8001/stats/magnus/yesterday
|
||||
```
|
||||
|
||||
### 5. Статистика за неделю
|
||||
|
||||
#### GET /stats/{username}/week
|
||||
Получает агрегированную статистику игрока за последние 7 дней.
|
||||
|
||||
**Параметры:**
|
||||
- `username` (string, обязательный) - имя пользователя на Lichess
|
||||
|
||||
**Пример запроса:**
|
||||
```bash
|
||||
curl http://localhost:8001/stats/magnus/week
|
||||
```
|
||||
|
||||
### 6. Статистика игр за период
|
||||
|
||||
#### GET /games/{username}/period
|
||||
Получает детальную статистику игр пользователя за указанный период времени.
|
||||
|
||||
**Параметры:**
|
||||
- `username` (string, обязательный) - имя пользователя на Lichess
|
||||
- `since` (integer, обязательный) - начало периода (Unix timestamp в миллисекундах)
|
||||
- `until` (integer, обязательный) - конец периода (Unix timestamp в миллисекундах)
|
||||
- `rated_only` (boolean, опциональный) - только рейтинговые игры (по умолчанию true - рекомендуется)
|
||||
|
||||
**Пример запроса:**
|
||||
```bash
|
||||
# Статистика за последние 7 дней
|
||||
curl "http://localhost:8001/games/magnus/period?since=1640995200000&until=1641081600000"
|
||||
|
||||
# Только рейтинговые игры
|
||||
curl "http://localhost:8001/games/magnus/period?since=1640995200000&until=1641081600000&rated_only=true"
|
||||
|
||||
# Все игры (включая нерейтинговые)
|
||||
curl "http://localhost:8001/games/magnus/period?since=1640995200000&until=1641081600000&rated_only=false"
|
||||
```
|
||||
|
||||
**Пример ответа:**
|
||||
```json
|
||||
{
|
||||
"message": "Статистика игр за период",
|
||||
"username": "magnus",
|
||||
"period_start": 1640995200000,
|
||||
"period_end": 1641081600000,
|
||||
"games_count": 25,
|
||||
"data": {
|
||||
"bullet": {
|
||||
"games_played": 10,
|
||||
"wins": 6,
|
||||
"losses": 3,
|
||||
"draws": 1,
|
||||
"rating_change": 15
|
||||
},
|
||||
"blitz": {
|
||||
"games_played": 8,
|
||||
"wins": 5,
|
||||
"losses": 2,
|
||||
"draws": 1,
|
||||
"rating_change": 12
|
||||
},
|
||||
"rapid": {
|
||||
"games_played": 5,
|
||||
"wins": 3,
|
||||
"losses": 1,
|
||||
"draws": 1,
|
||||
"rating_change": 8
|
||||
},
|
||||
"classical": {
|
||||
"games_played": 2,
|
||||
"wins": 1,
|
||||
"losses": 1,
|
||||
"draws": 0,
|
||||
"rating_change": 0
|
||||
},
|
||||
"correspondence": {
|
||||
"games_played": 0,
|
||||
"wins": 0,
|
||||
"losses": 0,
|
||||
"draws": 0,
|
||||
"rating_change": 0
|
||||
},
|
||||
"total": {
|
||||
"games_played": 25,
|
||||
"wins": 15,
|
||||
"losses": 7,
|
||||
"draws": 3,
|
||||
"rating_change": 35
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Статистика решения задач за период
|
||||
|
||||
#### GET /puzzle/period
|
||||
Получает статистику решения задач (пазлов) за указанный период времени. Требует авторизации через Bearer токен.
|
||||
|
||||
**Параметры:**
|
||||
- `since` (integer, обязательный) - начало периода (Unix timestamp в миллисекундах)
|
||||
- `until` (integer, обязательный) - конец периода (Unix timestamp в миллисекундах)
|
||||
- `max` (integer, опциональный) - максимальное количество задач для получения (по умолчанию 50, максимум 1000)
|
||||
- `Authorization` (header, обязательный) - Bearer токен авторизации
|
||||
|
||||
**Важно:** Параметр `max` ограничивает количество активностей, получаемых от Lichess API. Если в указанном периоде было больше задач, чем указано в `max`, то будут показаны только последние N активностей. Для получения полной статистики рекомендуется увеличить значение `max` или использовать значение по умолчанию (50).
|
||||
|
||||
**Пример запроса:**
|
||||
```bash
|
||||
# Статистика за последние 7 дней
|
||||
curl -H "Authorization: Bearer your_token_here" \
|
||||
"http://localhost:8001/puzzle/period?since=1640995200000&until=1641081600000"
|
||||
|
||||
# Больше задач
|
||||
curl -H "Authorization: Bearer your_token_here" \
|
||||
"http://localhost:8001/puzzle/period?since=1640995200000&until=1641081600000&max=100"
|
||||
```
|
||||
|
||||
**Пример ответа:**
|
||||
```json
|
||||
{
|
||||
"message": "Статистика решения задач за период",
|
||||
"period_start": 1640995200000,
|
||||
"period_end": 1641081600000,
|
||||
"max_puzzles": 50,
|
||||
"puzzles_in_period": 15,
|
||||
"data": {
|
||||
"total_attempts": 15,
|
||||
"solved": 12,
|
||||
"failed": 3,
|
||||
"success_rate": 80.0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Получение токена:**
|
||||
1. Зайдите на https://lichess.org/account/oauth/token/create
|
||||
2. Создайте новый токен с правами на чтение активности
|
||||
3. Используйте токен в заголовке Authorization
|
||||
|
||||
## Модели данных
|
||||
|
||||
### TaskStats
|
||||
Статистика решения задач (пазлов):
|
||||
```json
|
||||
{
|
||||
"total": 15, // Общее количество решенных задач
|
||||
"solved": 12, // Количество правильно решенных задач
|
||||
"unsolved": 3 // Количество нерешенных или неправильно решенных задач
|
||||
}
|
||||
```
|
||||
|
||||
### GameModeStats
|
||||
Статистика игр для конкретного режима:
|
||||
```json
|
||||
{
|
||||
"games_played": 8, // Общее количество сыгранных игр
|
||||
"rating_change": 15, // Изменение рейтинга (может быть отрицательным)
|
||||
"final_rating": 2850, // Текущий рейтинг игрока
|
||||
"wins": 5, // Количество побед
|
||||
"losses": 2, // Количество поражений
|
||||
"draws": 1 // Количество ничьих
|
||||
}
|
||||
```
|
||||
|
||||
### GamesStats
|
||||
Статистика игр по всем режимам:
|
||||
```json
|
||||
{
|
||||
"bullet": { /* GameModeStats */ },
|
||||
"blitz": { /* GameModeStats */ },
|
||||
"rapid": { /* GameModeStats */ }
|
||||
}
|
||||
```
|
||||
|
||||
### UserStats
|
||||
Полная статистика пользователя:
|
||||
```json
|
||||
{
|
||||
"username": "magnus",
|
||||
"tasks": { /* TaskStats */ },
|
||||
"games": { /* GamesStats */ }
|
||||
}
|
||||
```
|
||||
|
||||
### ActivityResponse
|
||||
Ответ API с результатами запроса:
|
||||
```json
|
||||
{
|
||||
"message": "Статистика за сегодняшний день",
|
||||
"data": { /* UserStats или null */ }
|
||||
}
|
||||
```
|
||||
|
||||
## Коды ошибок
|
||||
|
||||
- **200** - Успешный запрос
|
||||
- **404** - Пользователь не найден или неактивен
|
||||
- **500** - Внутренняя ошибка сервера
|
||||
|
||||
## Примеры ошибок
|
||||
|
||||
### Пользователь не найден
|
||||
```json
|
||||
{
|
||||
"message": "Пользователь magnus не найден или неактивен"
|
||||
}
|
||||
```
|
||||
|
||||
### Внутренняя ошибка сервера
|
||||
```json
|
||||
{
|
||||
"detail": "Внутренняя ошибка сервера: Connection timeout"
|
||||
}
|
||||
```
|
||||
|
||||
## Swagger UI
|
||||
|
||||
Интерактивная документация доступна по адресу:
|
||||
```
|
||||
http://localhost:8001/docs
|
||||
```
|
||||
|
||||
## OpenAPI Schema
|
||||
|
||||
Схема OpenAPI доступна по адресу:
|
||||
```
|
||||
http://localhost:8001/openapi.json
|
||||
```
|
||||
|
||||
## Запуск в Docker
|
||||
|
||||
```bash
|
||||
# Сборка и запуск
|
||||
docker compose up --build -d
|
||||
|
||||
# Проверка статуса
|
||||
docker compose ps
|
||||
|
||||
# Просмотр логов
|
||||
docker compose logs
|
||||
|
||||
# Остановка
|
||||
docker compose down
|
||||
```
|
||||
|
||||
## Разработка
|
||||
|
||||
### Установка зависимостей
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Запуск в режиме разработки
|
||||
```bash
|
||||
uvicorn main:app --host 0.0.0.0 --port 8001 --reload
|
||||
```
|
||||
|
||||
## Лицензия
|
||||
|
||||
MIT License
|
||||
Loading…
Add table
Add a link
Reference in a new issue