bottohelp/README.md

Telegram Bot

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

📋 История версий

Версия 1.4.0 (16 октября 2025) - Критические исправления

Дата релиза: 16.10.2025

🚨 Критические исправления безопасности и стабильности

• ✅ Исправлена система рангов - синхронизированы поля очков и репутации в базе данных
• ✅ Улучшена обработка ошибок внешних API - добавлены таймауты, детальная обработка HTTP-ошибок
• ✅ Добавлена валидация входящих данных - защита от некорректных данных и злоупотреблений
• ✅ Улучшена обработка исключений в БД - валидация параметров, автоматический rollback транзакций

Исправления ошибок

• ✅ Исправлена ошибка с повторяющимся сообщением о "первом сообщении" при вводе суммы доната
• ✅ Исправлена проблема с кодировкой Unicode символов при запуске бота на Windows
• ✅ Исправлена система донатов - теперь корректно работает кнопка "Другая сумма"

✨ Новые функции

• ✅ Добавлена команда /donate для поддержки проекта
• ✅ Добавлена информация о донатах в справку /help
• ✅ Улучшена система достижений - достижения разблокируются только один раз

🔧 Технические улучшения

• ✅ Оптимизирована логика проверки достижений в базе данных
• ✅ Добавлена проверка существующих достижений перед разблокировкой
• ✅ Улучшена обработка ошибок в системе донатов
• ✅ Создан тестовый скрипт для проверки корректности рангов
• ✅ Добавлена защита от само-действий в командах модерации

Версия 1.3.0 (Предыдущая версия)

• ✅ Исправления ошибок донатной системы и кодировки Unicode
• ✅ Улучшения системы достижений

Версия 1.2.0 (Предыдущая версия)

• 🚀 Добавлены расширенные игры: 2048, Тетрис, Змейка
• 🎯 Улучшена система достижений
• 📅 Расширенная система планировщика постов

Функции

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

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

Безопасность и надежность

• 🔒 Валидация входящих данных - все команды проверяют корректность параметров
• 🛡️ Защита от злоупотреблений - ограничения на длину текстов, ID пользователей
• ⚡ Обработка ошибок API - таймауты, повторные попытки, детальные сообщения об ошибках
• 💾 Надежность базы данных - валидация запросов, автоматический rollback транзакций
• 🚫 Предотвращение само-действий - пользователи не могут модерировать сами себя

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

• 🎮 Мини-игры: Камень-ножницы-бумага, Крестики-нолики, Викторина, Морской бой
• 🎯 Расширенные игры: 2048, Тетрис, Змейка
• 🧠 Система достижений и начисления очков
• Начисление дополнительных очков за участие в играх

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

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

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

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

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

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

Система приветствий и донатов

• 🎉 Автоматическое приветствие новых пользователей с правилами группы
• ⏰ Автоматическое удаление приветственных сообщений через 2 минуты
• 👥 Обработка нескольких пользователей (удаление старого, создание нового приветствия)
• 💰 Интеграция кнопок донатов прямо в приветственные сообщения
• 🎯 Быстрый доступ к помощи через приветственные кнопки

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

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 - Запустить мини-игру
• Доступные игры: Камень-ножницы-бумага, Крестики-нолики, Викторина, Морской бой, 2048, Тетрис, Змейка

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

• /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)
• Поддержка изображений в постах
• Автоматическая публикация через планировщик
• Управление постами только администраторами чата
• Все посты сохраняются в базе данных с историей публикаций

Автоматическая система приветствий

• Приветствие новых пользователей с подробными правилами группы
• Автоматическое удаление приветствий через 2 минуты для чистоты чата
• Интеллектуальная обработка нескольких пользователей одновременно
• Интеграция донатов и быстрого доступа к помощи в приветственных сообщениях

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

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

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

telegram_bot/
├── bot.py              # Основной файл бота
├── config.py           # Конфигурация (токены, настройки БД)
├── config_local.py     # Локальная конфигурация с токенами
├── database_sqlite.py  # Работа с SQLite базой данных
├── database.py         # Базовые функции работы с БД
├── scheduler.py        # Планировщик постов по расписанию
├── migrate_ranks.py    # Миграция системы рангов
├── messages.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 для подробностей.