ChessCalcNextTour/README.md

# ♟️ chessCalc — калькулятор швейцарской жеребьёвки + авто-отслеживание игроков

Расчёт пар следующего тура шахматного турнира **до официальной публикации**
на chess-results.com. Плюс подписка на игрока по FIDE ID: бот сам находит
турниры, отслеживает результаты и присылает жеребьёвку с подсветкой игрока.

Два Telegram-бота: клиентский и админский.

---

## Возможности

### Клиентский бот

| Команда | Описание |
|---------|----------|
| `/addplayer` | Подписаться на игрока по FIDE ID — бот сам найдёт турнир на chess-results |
| `/myplayers` | Список активных подписок |
| `/removeplayer <N>` | Удалить подписку |
| `/cancel` | Отменить текущую операцию |
| `URL турнира` | Прислать ссылку chess-results.com — получить жеребьёвку следующего тура |

**Авто-отслеживание:**
- Каждые **5 минут** — проверка новых результатов подписанных игроков
- При завершении тура — расчёт и отправка жеребьёвки следующего тура (±5 пар вокруг игрока, `✅` зелёная галочка)
- Результат каждого тура: `♟ победа/ничья/поражение`

### Админский бот

- `/stat` — уникальные пользователи, всего запросов, запросов за сегодня

---

## Как запустить

```bash
# 1. Токены
cp .env.example .env   # отредактировать токены

# 2. Запуск
docker compose up -d
```

### CLI (отладка)

```bash
# Пары следующего тура
docker compose run --rm client-bot python3 -m swiss_calc 'URL'

# JSON
docker compose run --rm client-bot python3 -m swiss_calc --json 'URL'

# Положение
docker compose run --rm client-bot python3 -m swiss_calc --standings 'URL'
```

---

## Архитектура

```
chessCalc/
├── Dockerfile                  # python:3.11-slim + bbpPairings
├── docker-compose.yml          # client-bot + admin-bot + volume bot-data
├── .env.example                # шаблон токенов
├── .env                        # реальные токены (gitignored)
├── bbpPairings.exe             # FIDE-движок Dutch System (C++, 2.4 MB)
├── requirements.txt            # requests, bs4, python-telegram-bot, rich
├── swiss_calc/                 # Ядро — парсинг + расчёт
│   ├── __main__.py             # CLI entry point
│   ├── parser.py               # Парсинг chess-results.com (art=2/4/5)
│   ├── trf_generator.py        # Генерация TRF-16 для bbpPairings
│   ├── bbp_wrapper.py          # Вызов bbpPairings.exe через subprocess
│   ├── swiss.py                # Оркестрация + fallback Swiss-алгоритм
│   └── display.py              # Форматирование вывода (CLI)
├── bots/                       # Telegram-боты
│   ├── client_bot.py           # Клиентский бот
│   ├── admin_bot.py            # Админский бот (/stat)
│   ├── tracker.py              # Отслеживание игроков, кэш турниров, джобы
│   └── stats.py                # Статистика (SQLite)
└── TASKS.md                    # Журнал изменений
```

### Поток данных — жеребьёвка

```
URL турнира
      │
      ▼
┌─────────────────────────────────────────┐
│  parser.fetch_tournament()              │
│  1. art=4 — положение                   │
│  2. art=5 — стартовый список             │
│  3. Сопоставление имён → SNo             │
│  4. art=2&rd=1..N — пары каждого тура    │
└─────────────────────────────────────────┘
      │  tournament_data
      ▼
┌─────────────────────────────────────────┐
│  swiss.calculate_next_round()           │
│  1. Генерация TRF-16                    │
│  2. bbpPairings --dutch (FIDE 2025)     │
│     └→ fallback: упрощённый Swiss       │
└─────────────────────────────────────────┘
      │  пары (доски)
      ▼
┌─────────────────────────────────────────┐
│  format_pairings() → _render_chunks()   │
│  MarkdownV2 таблица в code-блоке        │
└─────────────────────────────────────────┘
```

### Поток данных — подписка на игрока

```
FIDE ID (напр. 55867510)
      │
      ▼
┌─────────────────────────────────────────┐
│  tracker.fetch_fide_player()            │
│  Парсинг ratings.fide.com/profile/{ID}  │
│  → имя, рейтинг, FED, каноничный FIDE ID│
└─────────────────────────────────────────┘
      │  player dict
      ▼
┌─────────────────────────────────────────┐
│  tracker.scan_for_player()              │
│  SQL-запрос к tnr_cache:                │
│  SELECT tnr FROM tnr_cache              │
│  WHERE players_json LIKE '%{fide_id}%'  │
│  → список TNR с этим игроком             │
└─────────────────────────────────────────┘
      │  tournaments list
      ▼
┌─────────────────────────────────────────┐
│  Авто-подписка + уведомление            │
│  → запись в subscriptions               │
│  → сообщение пользователю               │
└─────────────────────────────────────────┘
```

---

## Локальный кэш турниров (`tnr_cache`)

Таблица SQLite с полным списком игроков каждого турнира:

```
tnr_cache
├── tnr          INTEGER PRIMARY KEY   — номер турнира на chess-results
├── name         TEXT                   — название турнира
├── start_date   TEXT                   — дата начала
├── end_date     TEXT                   — дата окончания
└── players_json TEXT                   — JSON: {fide_id: {sno, name, rating, fed}}
```

- При первом фетче art=0 страницы турнира данные сохраняются в кэш
- **1979+ турниров** в кэше (1.4M кластер, 2025-2026)
- Поиск игрока — **один SQL LIKE-запрос, ~0.015 секунды**, без HTTP

### Прогрев кэша (`warmup_cache`)

- При старте: полный скан кластера 1.4M с шагом 1 (~50 минут)
- Сохраняет прогресс в `tnr_state` — при перезапуске продолжает
- После завершения (`warmup_tnr = done`) — пропускает, если кэш > 1000 записей
- Каждые 6 часов — перепроверка кластера

---

## Фоновые задачи

| Задача | Интервал | Что делает |
|--------|----------|------------|
| `check_all_subscriptions` | **5 мин** | Проверяет новые результаты, считает и отправляет жеребьёвку |
| `rescan_new_tournaments` | **1 час** | Ищет новые TNR > `max_tnr_seen`, авто-подписывает |
| `rescan_existing_tournaments` | **2 часа** | Рефетчит art=0 для всех TNR (мимо кэша), находит новых игроков |
| `warmup_cache` | **6 часов** | Обновляет tnr_cache (если нужен) |

---

## База данных (SQLite)

Таблицы в `/app/data/tournaments.db` (Docker volume `bot-data`):

| Таблица | Назначение |
|---------|------------|
| `subscriptions` | Активные подписки: user_id, fide_id, player_name, tournament_url, ... |
| `tnr_cache` | Кэш турниров: tnr, name, players_json |
| `tnr_state` | Состояние: max_tnr_seen, warmup_tnr, warmup progress |
| `users` / `requests` | Статистика использования (админский бот) |

Авто-миграция схемы: недостающие колонки добавляются при каждом `_get_conn()`.

---

## Источники данных

| Источник | URL | Что даёт |
|----------|-----|----------|
| FIDE профиль | `ratings.fide.com/profile/{ID}` | Имя, рейтинг, федерация, каноничный FIDE ID |
| chess-results art=0 | `chess-results.com/tnr{N}.aspx?lan=11&art=0` | Список всех игроков турнира с FIDE ID |
| chess-results art=4 | `…&art=4` | Положение (имена, очки, тайбрейки) |
| chess-results art=5 | `…&art=5` | Стартовый список (SNo, рейтинги) |
| chess-results art=2 | `…&art=2&rd=N` | Пары тура N |

Парсер поддерживает 12-колоночный (новые турниры) и 10-колоночный (старые) форматы.

---

## Движок жеребьёвки

**Основной:** [bbpPairings](https://github.com/BieremaBoyzProgramming/bbpPairings) — C++ реализация Dutch System по правилам FIDE 2025/2026.

**Резервный:** упрощённый швейцарский алгоритм на Python (fold + перебор offset).

---

## Точность жеребьёвки

Проверено на турнирах Первенства России (2026):

| Турнир | Уч. | Точность |
|--------|-----|----------|
| 1393121 | 39 | **100%** |
| 1393124 | 93 | **100%** |
| 1393133 | 96 | **100%** |
| 1393137 | 14 | **100%** |
| 1393131 | 112 | **85%** * |

\* Расхождения только в нижних досках из-за ручных bye/forfeit-ов.

---

## Ограничения

1. **Ручные bye/forfeit-ы** — решение арбитра, алгоритм не предсказывает
2. **10-колоночный формат** — старые турниры без SNo, точность ~80%
3. **Круговые турниры** — не поддерживаются
4. **TNR-пространство не сплошное** — кластеры с пропусками, требуется кэш
5. **Латиница/кириллица** — имена на chess-results могут отличаться от FIDE, матчинг по SNo