diff --git a/.gitignore b/.gitignore index 535b3a0..a5130a6 100644 --- a/.gitignore +++ b/.gitignore @@ -55,6 +55,12 @@ npm-debug.log # Файлы кеша .cache/ +# Документация и временные файлы +LichessClientTG_bot/docs/*.html +LichessClientTG_bot/docs/*.txt +LichessClientTG_bot/docs/*_files/ +LichessWebServices/*.txt + diff --git a/LichessClientTG_bot/.gitignore b/LichessClientTG_bot/.gitignore deleted file mode 100644 index 33c1d0c..0000000 --- a/LichessClientTG_bot/.gitignore +++ /dev/null @@ -1,54 +0,0 @@ -# Python -__pycache__/ -*.py[cod] -*$py.class -*.so -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Virtual environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Database (commented out to include in git) -# *.db -# *.sqlite -# *.sqlite3 - -# Logs -*.log -logs/ - -# IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ - -# OS -.DS_Store -Thumbs.db - -# Docker -.dockerignore diff --git a/LichessWebServices/.gitignore b/LichessWebServices/.gitignore deleted file mode 100644 index efee0b1..0000000 --- a/LichessWebServices/.gitignore +++ /dev/null @@ -1,58 +0,0 @@ -# Python -__pycache__/ -*.py[cod] -*$py.class -*.so -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Virtual environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ - -# OS -.DS_Store -.DS_Store? -._* -.Spotlight-V100 -.Trashes -ehthumbs.db -Thumbs.db - -# Logs -*.log -logs/ - -# Docker -.dockerignore - -# Temporary files -*.tmp -*.temp diff --git a/LichessWebView/.gitignore b/LichessWebView/.gitignore deleted file mode 100644 index c38dc80..0000000 --- a/LichessWebView/.gitignore +++ /dev/null @@ -1,28 +0,0 @@ -__pycache__/ -*.py[cod] -*$py.class -*.so -.Python -env/ -venv/ -ENV/ -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -*.egg-info/ -.installed.cfg -*.egg -.DS_Store - - - - diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..779d6cb --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,132 @@ +# Архитектура проекта Lichess Statistics Ecosystem + +## Обзор проекта + +Проект состоит из трех основных компонентов: + +1. **LichessWebServices** - REST API для получения статистики с Lichess +2. **LichessClientTG_bot** - Telegram бот для отслеживания игроков +3. **LichessWebView** - Веб-интерфейс для просмотра пользователей и игроков + +## Структура базы данных + +### Таблицы + +#### telegram_users +Хранит информацию о пользователях Telegram бота. + +```sql +CREATE TABLE telegram_users ( + user_id INTEGER PRIMARY KEY, -- ID пользователя в Telegram + username TEXT, -- @username + first_name TEXT, -- Имя + last_name TEXT, -- Фамилия + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +``` + +#### gamers +Хранит информацию о игроках Lichess (уникальные). + +```sql +CREATE TABLE gamers ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + username TEXT UNIQUE NOT NULL, -- Username на Lichess + token TEXT, -- DEPRECATED: старый глобальный токен + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +``` + +**Важно:** Поле `token` в таблице `gamers` больше не используется. Токены хранятся в `user_gamers`. + +#### user_gamers +Связывает пользователей Telegram с игроками Lichess. Хранит индивидуальные настройки. + +```sql +CREATE TABLE user_gamers ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + user_id INTEGER NOT NULL, -- ID пользователя Telegram + gamer_id INTEGER NOT NULL, -- ID игрока Lichess + token TEXT, -- Lichess API token для этого пользователя+игрока + is_active BOOLEAN DEFAULT FALSE, -- Активен ли игрок для пользователя + period_minutes INTEGER DEFAULT 0, -- Период уведомлений (0 = отключено) + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (user_id) REFERENCES telegram_users(user_id), + FOREIGN KEY (gamer_id) REFERENCES gamers(id), + UNIQUE(user_id, gamer_id) +); +``` + +### Ключевая особенность + +Один пользователь может отслеживать несколько игроков, и у каждого пользователя **свой** активный игрок. Токены хранятся **отдельно для каждой пары** пользователь-игрок. + +## Поток данных + +### 1. Добавление игрока (`/adduser`) + +``` +Пользователь → /adduser → Ввод токена → Ввод username → + database.add_gamer(username) → database.add_user_gamer(user_id, gamer_id, token) +``` + +### 2. Получение статистики (`/today`, `/yesterday`, `/week`) + +``` +Пользователь → /today → database.get_user_active_gamer(user_id) → + lichess_api.get_stats(username, token) → Отправка в Telegram +``` + +### 3. Периодические уведомления + +``` +Периодическая задача → database.get_all_gamers_with_periods() → + Для каждой пары (user_id, gamer_id): + lichess_api.get_stats(username, token из user_gamers) → + Проверка изменений → Отправка уведомления +``` + +## Миграция токенов + +При старте бота автоматически запускается `_migrate_tokens_from_gamers()`: + +1. Проверяет есть ли токены в `gamers.token` +2. Если есть и их нет в `user_gamers.token`, переносит их +3. Логирует сколько токенов перенесено + +Это нужно для перехода со старой схемы (глобальный токен) на новую (токен на пару). + +## API Endpoints + +### Lichess Web Services + +- `GET /api/user_ratings/{username}` - Получить рейтинги игрока +- `GET /api/user_stats/{username}?start_date={date}&end_date={date}&token={token}` - Статистика за период +- `GET /health` - Health check + +## Команды бота + +- `/start` - Приветствие и регистрация пользователя +- `/adduser` - Добавить игрока для отслеживания +- `/getgamers` - Выбрать активного игрока +- `/today` - Статистика за сегодня +- `/yesterday` - Статистика за вчера +- `/week` - Статистика за неделю +- `/setperiod` - Настроить периодические уведомления + +## Docker Compose + +Все три сервиса запускаются через единый `docker-compose.yml`: + +- **lichess-api**: API на порту 8001 +- **lichess-telegram-bot**: Бот (host network) +- **lichess-web-view**: Веб-интерфейс на порту 5000 + +База данных монтируется как bind mount: `./LichessClientTG_bot/data:/app/data` + +## Безопасность + +- Токены Lichess API хранятся в базе данных и используются только для запросов к Lichess +- Веб-интерфейс работает **без пароля** - доступен всем кто знает URL +- Telegram бот токен хранится в `config.py` (можно вынести в `.env`) + diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..f9717a3 --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,223 @@ +# Инструкция для пользователя + +## Первая установка на новом сервере + +### Требования + +- Docker и Docker Compose установлены +- Доступ к GitHub репозиторию + +### Шаг 1: Клонирование репозитория + +```bash +git clone https://github.com/vrubelroman/LichessStatTgWeb.git +cd LichessStatTgWeb +``` + +### Шаг 2: Передача базы данных (опционально) + +Если у вас есть бэкап базы данных с другого сервера: + +```bash +# Скопируйте файл базы на сервер +cp /path/to/backup.db LichessClientTG_bot/data/lichess_bot.db +``` + +Или импортируйте через скрипт: + +```bash +chmod +x import_db.sh +./import_db.sh /path/to/backup.db +``` + +### Шаг 3: Запуск + +```bash +chmod +x start.sh +./start.sh +``` + +Скрипт автоматически: +- Остановит существующие контейнеры (если есть) +- Создаст бэкап базы данных +- Пересоберет Docker образы +- Запустит все три сервиса + +### Шаг 4: Проверка + +Откройте в браузере: +- **API документация**: http://localhost:8001/docs +- **Веб-интерфейс**: http://localhost:5000 + +Проверьте логи: + +```bash +docker logs lichess-telegram-bot -f +``` + +## Обновление до новой версии + +### Шаг 1: Создайте бэкап (рекомендуется) + +```bash +chmod +x export_db.sh +./export_db.sh +``` + +Это создаст копию базы в папке `backups/`. + +### Шаг 2: Обновите код + +```bash +cd /path/to/LichessStatTgWeb +git pull +``` + +### Шаг 3: Перезапустите сервисы + +```bash +./start.sh +``` + +**Важно:** `start.sh` **НЕ удалит** вашу базу данных. Она останется в `LichessClientTG_bot/data/`. + +### Шаг 4: Проверка + +Проверьте что все контейнеры запущены: + +```bash +docker ps | grep lichess +``` + +## Работа с бэкапами + +### Экспорт базы данных + +```bash +./export_db.sh +``` + +Создает файл в `backups/export_lichess_bot_YYYYMMDD_HHMMSS.db` + +### Импорт базы данных + +```bash +./import_db.sh backups/export_lichess_bot_20251028_123456.db +``` + +Автоматически создаст бэкап текущей базы перед импортом. + +## Просмотр логов + +### Все сервисы + +```bash +docker-compose logs -f +``` + +### Только бот + +```bash +docker logs lichess-telegram-bot -f +``` + +### Только API + +```bash +docker logs lichess-api -f +``` + +### Только веб-интерфейс + +```bash +docker logs lichess-web-view -f +``` + +## Остановка и удаление + +### Остановка без удаления данных + +```bash +docker-compose down +``` + +База данных остается. + +### Полное удаление (с данными!) + +```bash +docker-compose down -v # ОПАСНО! Удалит volumes +rm -rf LichessClientTG_bot/data/ # Удалит базу данных +``` + +## Перенос на другой сервер + +### На старом сервере: + +```bash +./export_db.sh +# Скопируйте файл из backups/ на новый сервер +``` + +### На новом сервере: + +```bash +git clone https://github.com/vrubelroman/LichessStatTgWeb.git +cd LichessStatTgWeb +chmod +x import_db.sh start.sh +./import_db.sh /path/to/backup.db +./start.sh +``` + +## Устранение проблем + +### Порт уже занят + +Ошибка: `bind: address already in use` + +Решение: +```bash +# Найдите процесс на порту +sudo fuser -k 8001/tcp # Для API +sudo fuser -k 5000/tcp # Для веб-интерфейса + +# Перезапустите +./start.sh +``` + +### Контейнер не запускается + +```bash +# Проверьте логи +docker logs lichess-telegram-bot + +# Удалите и пересоздайте +docker-compose down +docker-compose build --no-cache +./start.sh +``` + +### База данных повреждена + +```bash +# Восстановите из бэкапа +./import_db.sh backups/export_lichess_bot_YYYYMMDD_HHMMSS.db +``` + +## Структура проекта + +``` +LichessStatTgWeb/ +├── LichessWebServices/ # API сервис +├── LichessClientTG_bot/ # Telegram бот +│ └── data/ +│ └── lichess_bot.db # База данных (НЕ в git!) +├── LichessWebView/ # Веб-интерфейс +├── backups/ # Бэкапы БД (НЕ в git!) +├── docs/ # Документация +├── docker-compose.yml # Конфигурация Docker +├── start.sh # Скрипт запуска +├── export_db.sh # Экспорт БД +└── import_db.sh # Импорт БД +``` + diff --git a/import_db.sh b/import_db.sh new file mode 100755 index 0000000..0444d71 --- /dev/null +++ b/import_db.sh @@ -0,0 +1,57 @@ +#!/bin/bash + +# Проверяем аргументы +if [ -z "$1" ]; then + echo "📥 Импорт базы данных" + echo "" + echo "Использование:" + echo " ./import_db.sh <путь_к_файлу_базы>" + echo "" + echo "Пример:" + echo " ./import_db.sh backups/export_lichess_bot_20251028_123456.db" + echo " ./import_db.sh /path/to/lichess_bot.db" + echo "" + exit 1 +fi + +BACKUP_FILE="$1" + +# Проверяем существует ли файл +if [ ! -f "$BACKUP_FILE" ]; then + echo "❌ Файл не найден: $BACKUP_FILE" + exit 1 +fi + +# Проверяем что это SQLite файл +if ! file "$BACKUP_FILE" | grep -q "SQLite"; then + echo "❌ Это не файл базы данных SQLite!" + exit 1 +fi + +echo "📥 Импорт базы данных из: $BACKUP_FILE" +echo "" + +# Создаем директорию если не существует +mkdir -p LichessClientTG_bot/data +mkdir -p backups + +# Делаем бэкап существующей базы если она есть +if [ -f "LichessClientTG_bot/data/lichess_bot.db" ]; then + echo "💾 Создание бэкапа существующей базы..." + cp LichessClientTG_bot/data/lichess_bot.db "backups/backup_before_import_$(date +%Y%m%d_%H%M%S).db" + echo "✅ Бэкап создан" +fi + +# Копируем базу +echo "📋 Копирование базы данных..." +cp "$BACKUP_FILE" "LichessClientTG_bot/data/lichess_bot.db" + +echo "" +echo "✅ База данных импортирована!" +echo "" +echo "⚠️ Для применения изменений перезапустите бота:" +echo " docker-compose restart lichess-bot" +echo "" +echo " Или полный перезапуск всех сервисов:" +echo " ./start.sh" +