Auto-Pump/README.md

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

Production-ready Telegram бот для автоматического поднятия тем на форуме Lolz.live с современной архитектурой, batch API и полной типизацией.

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

• ➕ Добавление тем - через запятую (12345, 67890, 11111) с batch API
• 🗑️ Удаление тем - через интерактивное меню
• 📋 Список тем - с датой последнего поднятия
• 🚀 Ручное поднятие - поднять все темы немедленно через batch API
• ⏰ Автоподнятие - каждые N часов автоматически
• 📊 Статистика - успешность, количество поднятий, uptime
• 🔔 Уведомления - о каждом поднятии темы
• 🛡️ Обработка ошибок - rate limits, network failures, invalid tokens
• ⚡ Batch API - до 10 тем за один запрос (10x быстрее)

🎮 Интерфейс

┌─────────────────────────────────┐
│  ➕ Добавить темы  │ 📋 Список тем  │
│  🗑️ Удалить тему  │ 🚀 Поднять темы │
│  📊 Статистика    │ 👤 Автор       │
└─────────────────────────────────┘

📦 Установка

Требования

• Python 3.12+
• pip или uv

1. Установите зависимости

pip install -r requirements.txt

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

Telegram Bot Token:

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

Lolz API Token:

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

3. Настройте config.json

{
    "bot": {
        "api_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
        "img_url": "https://wallpapers-clan.com/wp-content/uploads/2024/04/dark-anime-girl-with-red-eyes-desktop-wallpaper-preview.jpg",
        "author_url": "https://lolz.live/kqlol/"
    },
    "api": {
        "base_url": "https://prod-api.lolz.live",
        "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
        "batch_size": 10
    },
    "database": {
        "path": "threads.db"
    },
    "scheduling": {
        "bump_interval_hours": 12,
        "bump_delay_seconds": 2,
        "enable_auto_bump": true
    }
}

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

python app.py

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

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

1. Нажмите ➕ Добавить темы
2. Введите ID через запятую: 12345, 67890, 11111
3. Бот автоматически получит названия тем через batch API (до 10 за запрос)

Пример:

Ввод: 9247920, 9247921, 9247922

Результат:
✅ 9247920 - Qiyanas steam idler
✅ 9247921 - Discord bot
✅ 9247922 - VPN service

Batch API преимущества:

• Добавление 10 тем = 1 batch запрос вместо 10 обычных
• Добавление 25 тем = 3 batch запроса вместо 25 обычных
• Экономия API лимитов в 10 раз

Удаление темы

1. Нажмите 🗑️ Удалить тему
2. Выберите тему из списка
3. Подтвердите удаление

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

1. Нажмите 🚀 Поднять темы
2. Бот поднимет все темы через batch API (до 10 за запрос)
3. Получите уведомление о каждой теме:

   [1/3] ✅ Тема 9247920 поднята успешно
   [2/3] ✅ Тема 9247921 поднята успешно
   [3/3] ✅ Тема 9247922 поднята успешно
   

Batch API преимущества:

• Поднятие 10 тем = 1 batch запрос (0.1 * 10 = 1 batch)
• Поднятие 50 тем = 5 batch запросов вместо 50 обычных
• Скорость выполнения увеличена в ~10 раз

Просмотр списка

Нажмите 📋 Список тем - покажет:

• ID темы
• Название темы
• Дату последнего поднятия

Статистика

Нажмите 📊 Статистика - покажет:

• Количество тем
• Готовые к поднятию
• Всего попыток
• Успешность (%)
• Настройки интервала
• Время работы бота

⚙️ Настройки

Интервал автоподнятия

В config.json измените bump_interval_hours:

Значение	Интервал
12	12 часов
6	6 часов
24	24 часа

Размер batch запросов

В config.json измените batch_size:

Значение	Описание
10	Максимум (рекомендуется) - 10 тем за запрос
5	Средний - 5 тем за запрос
1	Отключить batch - по 1 теме

Примечание: Batch API Lolz.live поддерживает до 10 запросов в одном batch. Каждый запрос = 0.1 batch, итого 10 запросов = 1 полный batch.

Тестовый режим (5 минут)

"scheduling": {
    "bump_interval_hours": 0.0833,
    "bump_delay_seconds": 1,
    "enable_auto_bump": true
}

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

1. Запускаете бота
2. Вручную поднимаете темы через 🚀 (первый раз)
3. Бот ждет указанный интервал (например, 12 часов)
4. Автоматически поднимает темы, у которых прошло 12+ часов
5. Повторяет каждые 12 часов

Пример:

00:00 - Запуск бота
00:05 - Вы вручную нажали "Поднять темы"
12:05 - Автоматическое поднятие
24:05 - Автоматическое поднятие
36:05 - Автоматическое поднятие

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

Модульная структура

app.py              # Main bot logic with FSM
config_manager.py   # Type-safe configuration
api_client.py       # Lolz batch API client with retry logic
database.py         # SQLite with connection pooling

Ключевые улучшения

• Batch API: До 10 тем за один запрос (10x эффективнее)
• Type Safety: Полная типизация с Python 3.12+ (PEP 695)
• SOLID Principles: Каждый модуль имеет одну ответственность
• Connection Pooling: Эффективное управление соединениями
• Error Handling: Специфичные исключения для каждого случая
• Async Context Managers: Автоматическая очистка ресурсов
• Immutable Config: Frozen dataclasses для безопасности
• Logging: Структурированные логи с rotation
• Graceful Shutdown: Корректное завершение всех задач

Batch API Implementation

Как работает:

# Старый способ (10 запросов):
for thread_id in [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]:
    POST /threads/{thread_id}/bump

# Новый способ (1 batch запрос):
POST /batch
[
  {"uri": "/threads/1/bump", "method": "POST"},
  {"uri": "/threads/2/bump", "method": "POST"},
  ...
  {"uri": "/threads/10/bump", "method": "POST"}
]

Преимущества:

• Экономия API лимитов в 10 раз
• Скорость выполнения увеличена в ~10 раз
• Меньше нагрузка на сеть
• Атомарная обработка результатов

Edge Cases

• Rate limiting от API (обработка в batch ответах)
• Network timeouts (retry для batch запросов)
• Invalid tokens (валидация перед batch)
• Partial batch failures (индивидуальная обработка каждого результата)
• Concurrent access (connection pooling)
• Database locks (async context managers)
• Memory leaks prevention (frozen dataclasses, proper cleanup)

📝 Логи

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

🔧 Технические детали

• Python: 3.12+
• aiogram: 3.4.1
• aiohttp: 3.10.0+
• aiosqlite: 0.20.0+
• База данных: SQLite с индексами
• API: https://prod-api.lolz.live
• Batch API: До 10 запросов за 1 batch (каждый = 0.1 batch)

🐛 Troubleshooting

Ошибка: "bot.api_token not configured"

Заполните config.json реальными токенами.

Ошибка: "Invalid API token"

Проверьте токен на zelenka.guru/account/api.

Ошибка: "Network error"

Проверьте интернет-соединение и доступность API.

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

1. Проверьте enable_auto_bump: true в config.json
2. Сделайте первое поднятие вручную через 🚀
3. Проверьте логи в bot.log

👤 Автор

QIYANA - создатель бота

---

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