133 lines
5.6 KiB
Markdown
133 lines
5.6 KiB
Markdown
|
# Архитектура проекта 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`)
|
|||
|
|
|