Lichess Statistics Ecosystem

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

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

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

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

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

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

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

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

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

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

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

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

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

• API документация: http://localhost:8001/docs
• 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          # Конфигурация
│
├── 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

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

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

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

Структура:

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

🐳 Docker

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

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

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

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

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

Telegram бот

Токены ботов задаются переменными окружения в .env (см. .env.example):

TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
ADMINPANEL_TELEGRAM_BOT_TOKEN=YOUR_ADMIN_BOT_TOKEN

LichessClientTG_bot/config.py читает их через os.getenv(...). Разделение на тестовый и продакшн стенды обеспечивается не флагом в коде, а раздельными .env на каждом окружении: на локальном/тестовом стенде — тестовые токены, на проде — свои, боевые.

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

Логи

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

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

📝 Лицензия

MIT

👤 Автор

Roman Vrubel

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

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

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

• Lichess API Documentation
• Telegram Bot API
• FastAPI Documentation