# 🚀 QIYANA AUTO-BUMP BOT для Lolz.live

Telegram бот для автоматического поднятия тем на форуме Lolz.live. Batch API, тикающий планировщик, динамические настройки (меняются на лету без перезапуска), персистентная статистика.

Клиент сверен с официальной спецификацией API (`forum.json` — Lolzteam Public API v1.1.44a).

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

- ➕ **Добавление тем** — через запятую, названия загружаются сразу через batch API
- 📥 **Мои темы** — выбор своих тем прямо с форума (пагинация, тап — добавить), без ручного ввода ID
- 🗑️ **Удаление тем** — через интерактивное меню
- 📋 **Список тем** — с названиями и датой последнего поднятия
- 🚀 **Ручное поднятие** — все темы немедленно через batch API
- 🔄 **Обновление названий** — синхронизация названий тем с форумом по кнопке
- ⏰ **Автоподнятие** — тикающий планировщик (каждые 60 секунд проверяет, какие темы «созрели»), настройки применяются без перезапуска
- 🛠️ **Динамические настройки** — интервал, batch size, автобамп меняются через меню
- 📊 **Статистика** — сохраняется в БД, не теряется при перезапуске
- 🔔 **Уведомления** — о результате каждого поднятия
- 🛡️ **Защита доступа** — ботом управляет только админ (по Telegram ID)
- ⚡ **Batch API** — до 10 тем за один запрос, обработка 429 и rate-limit заголовков

## 🎮 Интерфейс

```
┌──────────────────────────────────────┐
│  ➕ Add topics    │ 📥 My topics      │
│  📋 List of topics│ 🗑️ Delete topic   │
│  🚀 Bump topics   │ 🔄 Refresh        │
│  📊 Statistics    │ 🛠️ Settings       │
│  👤 Author                            │
└──────────────────────────────────────┘
```

## 📦 Установка

### Требования

- Python 3.12+
- pip

### 1. Клонируйте и установите зависимости

```bash
pip install -r requirements.txt
```

### 2. Получите токены

**Telegram Bot Token:**
1. Напишите [@BotFather](https://t.me/BotFather)
2. Создайте бота: `/newbot`
3. Скопируйте токен

**Lolz API Token:**
1. Перейдите на [lolz.live/account/api](https://lolz.live/account/api)
2. Создайте токен с правами (scopes) `read`, `post`
3. Скопируйте токен

**Ваш Telegram ID:**
1. Напишите [@userinfobot](https://t.me/userinfobot) и получите свой ID

### 3. Настройте `.env`

```env
# Telegram Bot
BOT_API_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
BOT_IMG_URL=https://wallpapers-clan.com/wp-content/uploads/2024/04/dark-anime-girl-with-red-eyes-desktop-wallpaper-preview.jpg
BOT_AUTHOR_URL=https://lolz.live/kqlol/

# Lolz API
# Официальные серверы: https://api.lolz.team, https://api.lolz.live, https://api.zelenka.guru
API_BASE_URL=https://api.lolz.live
API_AUTH_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGc...
API_BATCH_SIZE=10

# Database
DB_PATH=threads.db

# Scheduling
BUMP_INTERVAL_MINUTES=5
BUMP_DELAY_SECONDS=1
ENABLE_AUTO_BUMP=true
SCHEDULER_TICK_SECONDS=60

# Admin (ваш Telegram user ID)
ADMIN_USER_ID=123456789
```

> `BOT_IMG_URL` можно оставить пустым — бот отправит меню текстом.

### 4. Запустите бота

```bash
python app.py
```

На старте бот проверяет токен через `GET /users/me` и пишет в лог, от какого аккаунта работает.

## 📖 Использование

### Добавление тем

1. Нажмите **➕ Add topics**
2. Введите ID через запятую: `12345, 67890, 11111`
3. Бот загрузит названия через batch API и сохранит в БД

Либо нажмите **📥 My topics** — бот покажет ваши темы с форума (по `GET /threads?tab=mythreads`) с пагинацией; нажмите на тему, чтобы добавить её.

### Ручное поднятие

1. Нажмите **🚀 Bump topics**
2. Бот поднимет все темы через batch API
3. Получите уведомление о каждой теме:
   ```
   [1/3] ✅ Тема 9247920 поднята успешно
   [2/3] ✅ Тема 9247921 поднята успешно
   [3/3] ❌ Тема 9247922: нужно подождать
   ```

### Обновление названий (🔄 Refresh)

Бот загружает актуальные названия тем с форума. Полезно, если темы переименовали.

### Статистика

Нажмите **📊 Statistics** — покажет:
- Количество тем (всего / готовы к поднятию)
- Статистика поднятий (всего / успешно / %)
- Дата последнего бампа
- Текущие настройки
- Время работы бота

Статистика сохраняется в SQLite и не сбрасывается при перезапуске.

## ⚙️ Настройки (меняются на лету)

| Кнопка | Что меняет | Применяется |
|--------|-----------|-------------|
| ⏰ Set Interval | Интервал автобампа в минутах (`5`, `720`, …) | На следующем тике планировщика (до 60 с) |
| 📦 Set Batch Size | Размер batch (1–10) | Мгновенно для следующих запросов |
| 🔄 Toggle Auto-Bump | Включить/выключить автобамп | Мгновенно |

Настройки хранятся в БД и сохраняются между перезапусками.

## 🔄 Как работает автоподнятие

Планировщик **тикающий**: каждые `SCHEDULER_TICK_SECONDS` (по умолчанию 60 с) бот читает настройки из БД, находит темы, у которых прошёл интервал, и поднимает их. Плюсы:

- темы, добавленные позже, подхватываются в ближайший тик;
- смена интервала применяется без перезапуска и без «потери фазы»;
- бот бампает ровно по таймеру, без обращений к форуму перед бампом.

```
00:00 — Запуск бота (тик каждые 60с)
00:05 — Ручное поднятие
00:10 — Первый тик, где тема «созрела» → автоподнятие
```

## 🌐 Лимиты API (по спецификации)

| Эндпоинт | Лимит |
|----------|-------|
| GET-запросы | 300 / минуту |
| Не-GET (в т.ч. bump) | 30 / минуту |
| `/batch` | 20 / минуту (независимый бакет) |

При превышении API возвращает `429` и заголовки `X-RateLimit-*`. Бот читает их и ждёт сброса окна, а между batch-вызовами соблюдает паузу `BUMP_DELAY_SECONDS`.

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

```
app.py              # Бот: хендлеры, middleware аутентификации, тикающий авто-бамп
config_manager.py   # Загрузка и валидация .env
api_client.py       # Lolz batch API клиент: union-парсер ответов, rate-limit, retry
database.py         # SQLite: темы, настройки, статистика
```

### Что внутри БД (SQLite через aiosqlite)

| Таблица | Назначение |
|---------|-----------|
| `threads` | Темы: ID, название, дата последнего бампа |
| `settings` | Динамические настройки (интервал, batch_size, автобамп) |
| `bump_stats` | Персистентная статистика (всего/успешно/последний бамп) |

### Ключевые особенности

- **Batch API** — до 10 тем за запрос; job'ы ключуются явным `id` (по спецификации)
- **Union-парсер bump-ответов** — понимает и документированную форму `{status, message, system_info}`, и «пустой ответ = успех», и legacy `_job_result`
- **Тикающий планировщик** — настройки применяются без перезапуска
- **Ретраи только там, где есть смысл** — сеть/5xx/429; 4xx не ретраятся
- **Персистентная статистика** — не теряется при перезапуске
- **Аутентификация** — middleware проверяет Telegram ID админа
- **WAL-режим SQLite** — лучшая конкурентность

## 📝 Логи

- **Консоль** — основные события
- **bot.log** — детальные логи с traceback

## 🔧 Зависимости

- **Python**: 3.12+
- **aiogram**: 3.15.0
- **aiohttp**: bundled with aiogram
- **aiosqlite**: 0.20.0+
- **python-dotenv**: 1.0.0+

## 🐛 Troubleshooting

### Ошибка: «BOT_API_TOKEN not configured»

Проверьте `.env` — заполните `BOT_API_TOKEN` реальным токеном от @BotFather.

### Ошибка: «ADMIN_USER_ID not configured»

Укажите в `.env` ваш Telegram ID (получить через @userinfobot).

### Ошибка: «API_AUTH_TOKEN not configured»

Проверьте токен на [lolz.live/account/api](https://lolz.live/account/api). В логе при старте будет `API token validation failed`, если токен невалиден.

### Ошибка: «⛔ Доступ запрещён»

Ботом может управлять только пользователь, чей Telegram ID указан в `ADMIN_USER_ID`.

### Темы не поднимаются автоматически

1. Проверьте, что автобамп включён (🔄 Toggle Auto-Bump)
2. Сделайте первое поднятие вручную через 🚀
3. Проверьте логи в `bot.log` — ошибки от форума (например, «нужно подождать») видны по каждой теме

## 👤 Автор

[QIYANA](https://lolz.live/kqlol/)

---

**Приятного использования! 🚀**