# 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 │ └───────────────┘ ``` ## 🚀 Быстрый старт ### Установка и запуск ```bash # Клонируем репозиторий 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](about.md) ### 3. LichessWebView (Веб-интерфейс) Веб-интерфейс для просмотра пользователей и их игроков. **Возможности:** - Просмотр всех пользователей бота - Фильтрация пользователей по имени/никнейму - Отображение игроков каждого пользователя - Статистика по каждому пользователю - Отображение активных игроков и периодов - Отображение языка пользователя (🇷🇺 ru / 🇬🇧 en) - Статистика пользователей с русским языком (количество и процент) ## 🗄️ База данных Система использует SQLite базу данных с таблицами: - `telegram_users` - пользователи Telegram - `gamers` - игроки Lichess - `user_gamers` - связь пользователей с игроками и настройки **Структура:** - Каждый пользователь видит только своих игроков - У каждого пользователя свой активный игрок - Период отслеживания привязывается к паре пользователь-игрок ## 🐳 Docker Все компоненты запускаются в Docker контейнерах: ```bash # Запуск всех сервисов docker-compose up -d # Просмотр логов docker-compose logs -f # Остановка всех сервисов docker-compose down ``` ## 🔑 Конфигурация ### Telegram бот Токены ботов настраиваются в `LichessClientTG_bot/config.py`: ```python 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 - Примеры запросов и ответов ## 🛠️ Разработка ### Локальная разработка ```bash # API сервис cd LichessWebServices docker-compose up -d # Telegram бот cd LichessClientTG_bot docker-compose up -d # Веб-интерфейс cd LichessWebView docker-compose up -d ``` ### Логи ```bash # Логи API docker logs lichesswebservices_lichess-api_1 -f # Логи бота docker logs lichess-telegram-bot -f # Логи веб-интерфейса docker logs lichess-web-view -f ``` ## 📝 Лицензия MIT ## 👤 Автор Roman Vrubel ## 📖 Дополнительная информация - **[О боте](about.md)** - подробное описание функций бота, для кого он предназначен и примеры использования - **[История изменений](CHANGELOG.md)** - список всех изменений и обновлений проекта ## 🔗 Полезные ссылки - [Lichess API Documentation](https://lichess.org/api) - [Telegram Bot API](https://core.telegram.org/bots/api) - [FastAPI Documentation](https://fastapi.tiangolo.com/)