LichessStatTgWeb/README.md

# 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/)