Lichess Statistics Ecosystem

Полнофункциональная система для отслеживания статистики игроков Lichess.org с Telegram ботом и веб-интерфейсом.

🎯 Описание проекта

Система состоит из трех взаимосвязанных компонентов:

1. LichessWebServices - REST API для получения статистики игроков Lichess
2. LichessClientTG_bot - Telegram бот для управления подписками и уведомлений
3. LichessWebView - Веб-интерфейс для просмотра пользователей и их игроков

🏗️ Архитектура

┌─────────────────────────────────────────────────────────────┐
│                     Telegram Users                           │
│                                                              │
│  ┌────────────────────────────────────────────────────┐   │
│  │           LichessClientTG_bot                       │   │
│  │  (Управление подписками, уведомления)               │   │
│  └────────┬───────────────────────────────────────────┘   │
│           │                                                 │
│           ├──────────────────────┐                          │
│           │                      │                          │
│  ┌────────▼──────────┐   ┌──────▼──────────────┐          │
│  │ LichessWebServices │   │  LichessWebView    │          │
│  │                    │   │                    │          │
│  │  REST API для      │   │  Веб-интерфейс     │          │
│  │  получения         │   │  для просмотра     │          │
│  │  статистики        │   │  пользователей     │          │
│  └────────┬───────────┘   └────────────────────┘          │
│           │                                              │
└───────────┼──────────────────────────────────────────────┘
            │
            ▼
    ┌───────────────┐
    │  Lichess API  │
    └───────────────┘

🚀 Быстрый старт

Установка и запуск

# Клонируем репозиторий
git clone https://github.com/vrubelroman/LichessStatTgWeb.git
cd LichessStatTgWeb

# Запускаем все сервисы
./start.sh

Скрипт start.sh запустит все контейнеры в правильном порядке.

Доступные сервисы

После запуска доступны:

• API документация: http://localhost:8001/docs
• Веб-интерфейс: http://localhost:5000
• Telegram бот: работает в фоне

📦 Структура проекта

LichessStatTgWeb/
├── LichessWebServices/      # REST API сервис
│   ├── main.py              # FastAPI приложение
│   ├── stats_service.py     # Логика обработки статистики
│   ├── lichess_client.py   # Клиент для Lichess API
│   └── models.py           # Pydantic модели
│
├── LichessClientTG_bot/     # Telegram бот
│   ├── bot.py              # Основная логика бота
│   ├── database.py         # Работа с БД
│   ├── lichess_api.py     # API клиент
│   ├── formatters.py      # Форматирование ответов
│   └── config.py          # Конфигурация
│
├── LichessWebView/          # Веб-интерфейс
│   ├── app.py             # Flask приложение
│   └── templates/         # HTML шаблоны
│       └── index.html     # Главная страница
│
├── docker-compose.yml       # Общая конфигурация контейнеров
├── start.sh                 # Скрипт запуска всех сервисов
└── README.md               # Этот файл

🔧 Компоненты

1. LichessWebServices (API)

REST API для получения статистики игроков Lichess.

Возможности:

• Статистика за сегодня/вчера/неделю
• Статистика игр по режимам (Bullet, Blitz, Rapid)
• Статистика решения задач (puzzles)
• Получение игр за произвольный период

Endpoints:

• GET /stats/{username}/today - статистика за сегодня
• GET /stats/{username}/yesterday - статистика за вчера
• GET /stats/{username}/week - статистика за неделю
• GET /games/{username}/period - игры за период
• GET /puzzle/period - задачи за период (требует токен)

2. LichessClientTG_bot (Telegram бот)

Telegram бот для управления отслеживанием игроков Lichess.

Возможности:

• Добавление игроков для отслеживания (друзья, соперники, ученики)
• Выбор активного игрока
• Получение статистики по всем отслеживаемым игрокам (сегодня/вчера/неделя)
• Статистика за последний год или последние 1000 рейтинговых игр
• Статистика по режимам (Bullet, Blitz, Rapid, Classical, Correspondence)
• Статистика решения задач (puzzles)
• Настройка периодических уведомлений с гибкими интервалами (15 минут - 24 часа)
• Информативные сообщения о процессе обработки запросов
• Каждый пользователь имеет свой набор игроков
• Версионность бота (отображается в команде /support)
• Многоязычная поддержка: Русский и английский языки с автоматическим определением и ручным выбором через /set_lang
• Очередь запросов: Автоматическая задержка 7 секунд между запросами к Lichess API для периодических уведомлений

Команды:

• /start - начало работы с ботом и добавление первого игрока
• /addgamer - добавить игрока Lichess (только имя пользователя)
• /addtoken - добавить игрока с токеном (для статистики по задачам)
• /getgamers - выбрать активного игрока
• /delgamer - удалить игрока из списка
• /today - статистика за сегодня по всем отслеживаемым игрокам с активностью
• /yesterday - статистика за вчера по всем отслеживаемым игрокам с активностью
• /week - статистика за неделю по всем отслеживаемым игрокам с активностью
• /lastYear_or_1000games - статистика за последний год или последние 1000 рейтинговых игр (по всем игрокам с активностью)
• /setperiod - настроить периодические уведомления для активного игрока
• /set_lang - выбрать язык бота (🇬🇧 English / 🇷🇺 Русский)
• /support - контактная информация для обратной связи с разработчиком

Подробнее о боте: см. about.md

3. LichessWebView (Веб-интерфейс)

Веб-интерфейс для просмотра пользователей и их игроков.

Возможности:

• Просмотр всех пользователей бота
• Фильтрация пользователей по имени/никнейму
• Отображение игроков каждого пользователя
• Статистика по каждому пользователю
• Отображение активных игроков и периодов
• Отображение языка пользователя (🇷🇺 ru / 🇬🇧 en)
• Статистика пользователей с русским языком (количество и процент)

🗄️ База данных

Система использует SQLite базу данных с таблицами:

• telegram_users - пользователи Telegram
• gamers - игроки Lichess
• user_gamers - связь пользователей с игроками и настройки

Структура:

• Каждый пользователь видит только своих игроков
• У каждого пользователя свой активный игрок
• Период отслеживания привязывается к паре пользователь-игрок

🐳 Docker

Все компоненты запускаются в Docker контейнерах:

# Запуск всех сервисов
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановка всех сервисов
docker-compose down

🔑 Конфигурация

Telegram бот

Токены ботов настраиваются в LichessClientTG_bot/config.py:

IS_PROD = False  # True для продакшн, False для тестовых токенов

# Production токены (используются при IS_PROD = True)
TELEGRAM_BOT_TOKEN_PROD = "YOUR_PROD_TOKEN"
ADMINPANEL_TELEGRAM_BOT_TOKEN_PROD = "YOUR_ADMIN_PROD_TOKEN"

# Test токены (используются при IS_PROD = False)
TELEGRAM_BOT_TOKEN_TEST = "YOUR_TEST_TOKEN"
ADMINPANEL_TELEGRAM_BOT_TOKEN_TEST = "YOUR_ADMIN_TEST_TOKEN"

Система автоматически выбирает нужные токены в зависимости от значения IS_PROD.

Lichess API

Для получения статистики по задачам нужен токен Lichess:

1. Зайдите на https://lichess.org/account/oauth/token/create
2. Создайте токен с правами на чтение
3. Используйте токен при добавлении игрока в боте

📊 API документация

Полная документация API доступна по адресу: http://localhost:8001/docs

Включает:

• Swagger UI для интерактивного тестирования
• Описание всех endpoints
• Примеры запросов и ответов

🛠️ Разработка

Локальная разработка

# API сервис
cd LichessWebServices
docker-compose up -d

# Telegram бот
cd LichessClientTG_bot
docker-compose up -d

# Веб-интерфейс
cd LichessWebView
docker-compose up -d

Логи

# Логи API
docker logs lichesswebservices_lichess-api_1 -f

# Логи бота
docker logs lichess-telegram-bot -f

# Логи веб-интерфейса
docker logs lichess-web-view -f

📝 Лицензия

MIT

👤 Автор

Roman Vrubel

📖 Дополнительная информация

• О боте - подробное описание функций бота, для кого он предназначен и примеры использования
• История изменений - список всех изменений и обновлений проекта

🔗 Полезные ссылки

• Lichess API Documentation
• Telegram Bot API
• FastAPI Documentation