Lolz/Auto-Pump
4
0
Fork 1
mirror of https://github.com/qiyanaitsme/QIYANASAutoPumpLOLZ.git synced 2026-09-23 04:37:43 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f23944d4c5141cdc1bded9aa926555da15d61ff0
Auto-Pump/README.md
T
imletbruh 134fab488b Add files via upload
2026-09-06 09:42:56 +05:00

240 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🚀 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/)
---
**Приятного использования! 🚀**
Reference in New Issue View Git Blame Copy Permalink