🚀 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. Клонируйте и установите зависимости

pip install -r requirements.txt

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

Telegram Bot Token:

1. Напишите @BotFather
2. Создайте бота: /newbot
3. Скопируйте токен

Lolz API Token:

1. Перейдите на lolz.live/account/api
2. Создайте токен с правами (scopes) read, post
3. Скопируйте токен

Ваш Telegram ID:

1. Напишите @userinfobot и получите свой ID

3. Настройте .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. Запустите бота

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. В логе при старте будет API token validation failed, если токен невалиден.

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

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

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

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

👤 Автор

QIYANA

---

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