75e62b57a1
All checks were successful
CI/CD Pipeline / build-and-deploy (push) Successful in 43s
Unused component that also carried several security issues (default admin credentials, hardcoded Flask secret key, debug mode, plaintext passwords). Cleaned up compose files, CI/CD pipeline, and docs accordingly; also dropped the stale IS_PROD config docs in favor of the current .env-based setup. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
240 lines
11 KiB
Markdown
240 lines
11 KiB
Markdown
# Lichess Statistics Ecosystem
|
||
|
||
Полнофункциональная система для отслеживания статистики игроков Lichess.org с Telegram ботом.
|
||
|
||
## 🎯 Описание проекта
|
||
|
||
Система состоит из двух взаимосвязанных компонентов:
|
||
|
||
1. **LichessWebServices** - REST API для получения статистики игроков Lichess
|
||
2. **LichessClientTG_bot** - Telegram бот для управления подписками и уведомлений
|
||
|
||
## 🏗️ Архитектура
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Telegram Users │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────────┐ │
|
||
│ │ LichessClientTG_bot │ │
|
||
│ │ (Управление подписками, уведомления) │ │
|
||
│ └────────┬───────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────▼───────────┐ │
|
||
│ │ LichessWebServices │ │
|
||
│ │ │ │
|
||
│ │ REST API для │ │
|
||
│ │ получения │ │
|
||
│ │ статистики │ │
|
||
│ └────────┬────────────┘ │
|
||
│ │ │
|
||
└───────────┼──────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌───────────────┐
|
||
│ Lichess API │
|
||
└───────────────┘
|
||
```
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### Установка и запуск
|
||
|
||
```bash
|
||
# Клонируем репозиторий
|
||
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](about.md)
|
||
|
||
## 🗄️ База данных
|
||
|
||
Система использует SQLite базу данных с таблицами:
|
||
|
||
- `telegram_users` - пользователи Telegram
|
||
- `gamers` - игроки Lichess
|
||
- `user_gamers` - связь пользователей с игроками и настройки
|
||
|
||
**Структура:**
|
||
- Каждый пользователь видит только своих игроков
|
||
- У каждого пользователя свой активный игрок
|
||
- Период отслеживания привязывается к паре пользователь-игрок
|
||
|
||
## 🐳 Docker
|
||
|
||
Все компоненты запускаются в Docker контейнерах:
|
||
|
||
```bash
|
||
# Запуск всех сервисов
|
||
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
|
||
- Примеры запросов и ответов
|
||
|
||
## 🛠️ Разработка
|
||
|
||
### Локальная разработка
|
||
|
||
```bash
|
||
# API сервис
|
||
cd LichessWebServices
|
||
docker-compose up -d
|
||
|
||
# Telegram бот
|
||
cd LichessClientTG_bot
|
||
docker-compose up -d
|
||
```
|
||
|
||
### Логи
|
||
|
||
```bash
|
||
# Логи API
|
||
docker logs lichesswebservices_lichess-api_1 -f
|
||
|
||
# Логи бота
|
||
docker logs lichess-telegram-bot -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/)
|
||
|
||
|
||
|
||
|