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