LichessStatTgWeb/LichessWebServices/API_DOCUMENTATION.md

# 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