bottohelp/README.md

Telegram Bot

Многофункциональный Telegram бот на Python с системой ранжирования пользователей, играми и интеграцией с внешними API.

Функции

Основные возможности

• ✅ Отвечать на сообщения пользователей предопределенными ответами
• ✅ Обрабатывать инлайновые запросы и команды
• ✅ Система ранжирования пользователей за участие в чате (хранение в PostgreSQL)
• ✅ Приветствие новых пользователей при добавлении в группу

Игровые элементы

• 🎮 Мини-игры: Угадай число, Камень-ножницы-бумага
• 🧠 Викторина с вопросами
• Начисление дополнительных очков за участие в играх

Администрирование чата

• ⚠️ Выдача предупреждений пользователям
• 🔇 Временное заглушение (mute)
• 🚫 Блокировка (ban) и кик пользователей
• 📊 Просмотр рейтинга и информации о пользователях

Посты по расписанию

• ⏰ Планирование постов для автоматической публикации
• 📅 Гибкие форматы времени (абсолютное и относительное)
• 🖼 Поддержка изображений в постах
• 👥 Управление постами (только администраторы)
• 💾 Хранение всех постов в базе данных

Интеграция с API

• 🌤️ Получение погоды (OpenWeatherMap)
• 📰 Последние новости (NewsAPI)
• 🌐 Перевод текста (Google Translate) - базовая реализация

Установка и настройка

1. Клонирование репозитория

git clone <repository-url>
cd telegram_bot

2. Установка зависимостей

pip install -r requirements.txt

3. Настройка базы данных

База данных SQLite настраивается автоматически при первом запуске бота. Файл базы данных telegram_bot.db создается в корневой директории проекта.

4. Получение токенов API

• Telegram Bot Token: Получите от @BotFather
• OpenWeatherMap API Key: Зарегистрируйтесь на openweathermap.org
• NewsAPI Key: Зарегистрируйтесь на newsapi.org

Обновите config.py с вашими ключами:

BOT_TOKEN = "your_bot_token_here"
OPENWEATHER_API_KEY = "your_weather_api_key_here"
NEWS_API_KEY = "your_news_api_key_here"

5. Запуск бота

python bot.py

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

Команды бота

Основные команды

• /start - Начать работу с ботом
• /help - Показать справку
• /rank - Ваш текущий рейтинг
• /ranks_info - Информация о системе рангов
• /leaderboard - Топ-10 участников
• /info - Информация о вас

Информация и сервисы

• /weather [город] - Погода в городе
• /news - Последние новости
• /translate [текст] [язык] - Перевод текста

Игры

• /play_game - Запустить мини-игру

Посты по расписанию (только админы)

• /schedule_post [время] [текст] - Запланировать пост
• /list_posts - Показать запланированные посты
• /delete_post [ID] - Удалить пост по расписанию
• /publish_now [ID] - Опубликовать пост немедленно

Модерация (только админы)

• /warn [пользователь] [причина] - Выдать предупреждение
• /mute [пользователь] [время] - Заглушить пользователя
• /unmute [пользователь] - Снять заглушку
• /ban [пользователь] [причина] - Забанить пользователя
• /unban [пользователь] - Разбанить пользователя
• /kick [пользователь] [причина] - Кикнуть пользователя
• /promote [пользователь] - Повысить до модератора
• /demote [пользователь] - Понизить с модератора

Система ранжирования

• За каждое сообщение начисляется 1 очко
• За выигрыш в мини-игре начисляются дополнительные очки
• Военная иерархия званий от Рядового до Маршала
• Рейтинг сохраняется в SQLite базе данных

Посты по расписанию

• Планирование публикации постов в указанное время
• Гибкие форматы времени: абсолютное (2024-01-15 14:30) и относительное (+2h, +30m)
• Поддержка изображений в постах
• Автоматическая публикация через планировщик
• Управление постами только администраторами чата
• Все посты сохраняются в базе данных с историей публикаций

Примеры использования планировщика:

/schedule_post +1h Добро пожаловать в наш чат!
/schedule_post 2024-01-15 09:00 Ежедневное утреннее приветствие
/schedule_post +30m Важное объявление для всех участников

Структура проекта

telegram_bot/
├── bot.py              # Основной файл бота
├── config.py           # Конфигурация (токены, настройки БД)
├── database_sqlite.py  # Работа с SQLite базой данных
├── scheduler.py        # Планировщик постов по расписанию
├── migrate_ranks.py    # Миграция системы рангов
├── requirements.txt    # Зависимости Python
└── README.md           # Эта документация

5. Запуск планировщика постов

Для работы постов по расписанию запустите планировщик в отдельном терминале:

python scheduler.py

Рекомендуется запускать бота и планировщик одновременно для полной функциональности.

Технологии

• Python 3.10+
• python-telegram-bot - библиотека для работы с Telegram API
• sqlite3 - встроенная поддержка SQLite базы данных
• requests - HTTP запросы для API
• asyncio - асинхронное программирование
• SQLite - база данных для хранения рейтинга и постов

Разработка

Добавление новых функций

1. Добавьте логику в соответствующие методы класса TelegramBot
2. Обновите базу данных при необходимости (методы в database.py)
3. Добавьте новые команды в setup_handlers()

Тестирование

Запустите бота локально и протестируйте все функции в тестовом чате.

Лицензия

MIT License - см. файл LICENSE для подробностей.