bottohelp/README.md

Telegram Bot

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

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

Версия 1.5.0 (18 октября 2025) - Система модерации медиафайлов

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

🆕 Новая система модерации медиафайлов

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

🔧 Улучшения системы

• ✅ Расширенная обработка медиа - поддержка аудио, видео и документов
• ✅ Система метаданных - сохранение информации о файлах (длительность, размер, транскрипция)
• ✅ Уведомления пользователей - пользователи получают информацию об отклонении контента
• ✅ Гибкие настройки модерации - выбор между немедленной публикацией и отсрочкой

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

• ✅ Исправлена ошибка с повторяющимся сообщением о "первом сообщении" при вводе суммы доната
• ✅ Исправлена проблема с кодировкой 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 минуты
• 👥 Обработка нескольких пользователей (удаление старого, создание нового приветствия)
• 💰 Интеграция кнопок донатов прямо в приветственные сообщения
• 🎯 Быстрый доступ к помощи через приветственные кнопки

🤝 Интерактивные функции пользователей

• 👍 Автореакции - автоматическая реакция 🤝 на сообщения содержащие "+"
• 🔄 Отзывчивость - бот реагирует на положительные сообщения пользователей
• 📈 Вовлеченность - повышение активности в чате через интерактивные элементы

Система отчетов об ошибках и ИИ-анализа

• 🚨 Отчеты об ошибках - администраторы могут отправлять отчеты об ошибках бота
• 📊 Управление ошибками - просмотр, фильтрация и управление списком ошибок
• 🤖 ИИ-анализ - автоматический анализ ошибок с помощью OpenAI GPT
• 📝 Интеграция с TODO - автоматическое добавление обработанных ошибок в список задач разработки
• 🔔 Уведомления разработчика - мгновенные уведомления о новых ошибках и их статусе
• 🧠 Автоматизированная обработка - пакетная обработка ошибок ИИ и добавление в план разработки
• 🧪 Тестирование системы - встроенный тестовый скрипт для проверки функциональности

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

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
• OpenAI API Key: Зарегистрируйтесь на platform.openai.com для анализа ошибок ИИ

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

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

# Настройки уведомлений разработчика
DEVELOPER_CHAT_ID = -1001234567890  # ID чата для уведомлений об ошибках
ENABLE_DEVELOPER_NOTIFICATIONS = True
ENABLE_AI_ERROR_PROCESSING = True

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 [пользователь] - Понизить с модератора

Система отчетов об ошибках (только админы)

• /report_error <тип> <заголовок> [описание] - Отправить отчет об ошибке
• /admin_errors [статус] - Показать список ошибок с фильтрацией по статусу
• /analyze_error_ai <ID> - Проанализировать конкретную ошибку с помощью ИИ
• /process_all_errors_ai - Обработать все новые ошибки с помощью ИИ
• /add_error_to_todo <ID> [приоритет] - Добавить ошибку в TODO список
• /add_all_analyzed_to_todo - Добавить все проанализированные ошибки в TODO список

Типы ошибок для команды /report_error:

• bug - ошибка в работе бота (приоритет: medium)
• crash - критическая ошибка/падение (приоритет: critical)
• feature - предложение новой функции (приоритет: low)
• ui - проблема интерфейса (приоритет: medium)
• security - проблема безопасности (приоритет: high)
• improvement - предложение улучшения (приоритет: low)
• other - другое (приоритет: medium)

Интерактивные функции пользователей

• Автореакции - бот автоматически ставит 🤝 на сообщения содержащие "+"
• Отзывчивость - повышение вовлеченности пользователей через интерактивные элементы

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

• За каждое сообщение начисляется 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          # Локальная конфигурация с токенами и ключами API
├── config_template.py       # Шаблон для настройки API ключей
├── database_sqlite.py       # Работа с SQLite базой данных (+ таблица errors)
├── database.py              # Базовые функции работы с БД
├── scheduler.py             # Планировщик постов по расписанию
├── migrate_ranks.py         # Миграция системы рангов
├── messages.py              # Текстовые сообщения и константы бота
├── requirements.txt         # Зависимости Python (+ openai)
├── test_error_system.py     # Тестовый скрипт для проверки системы ошибок
├── TODO.md                  # Список задач разработки с интеграцией ошибок
├── .gitignore              # Игнорируемые файлы для Git
├── Dockerfile              # Конфигурация для Docker развертывания
├── docker-compose.yml      # Оркестрация контейнеров
├── .github/
│   ├── README.md          # Краткое описание для GitHub
│   └── workflows/
│       └── deploy.yml     # CI/CD pipeline для GitHub Actions
└── README.md               # Полная документация

База данных

База данных содержит следующие таблицы:

• users - информация о пользователях, рейтинги и достижения
• warnings - предупреждения пользователей
• games - игровые сессии
• scheduled_posts - запланированные посты
• achievements - достижения пользователей
• donations - история донатов
• errors - система отчетов об ошибках и их анализ

Структура таблицы errors:

• error_id - уникальный идентификатор ошибки (PRIMARY KEY)
• admin_id - ID администратора, отправившего отчет
• error_type - тип ошибки (bug, feature, crash, ui, security, etc.)
• title - краткое название ошибки
• description - подробное описание проблемы
• status - статус обработки (new, in_progress, resolved, rejected)
• priority - приоритет (low, medium, high, critical)
• created_at - время создания отчета
• updated_at - время последнего обновления
• ai_analysis - результат анализа ИИ (если выполнен)
• todo_added - флаг добавления в TODO список
• resolved_at - время решения (если решена)

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

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

python scheduler.py

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

Технологии

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

Разработка

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

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

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

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

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

Автоматическое тестирование системы отчетов об ошибках

Проект включает встроенный тестовый скрипт для проверки функциональности системы отчетов об ошибках:

cd telegram_bot
python test_error_system.py

Что тестирует скрипт:

• ✅ Подключение к базе данных SQLite
• ✅ Создание и структура таблицы ошибок
• ✅ Добавление и получение ошибок из базы данных
• ✅ Работа системы фильтрации ошибок
• ✅ Интеграция с ИИ (проверка наличия методов)
• ✅ Работа интеграции с TODO файлом
• ✅ Система уведомлений разработчика
• ✅ Проверка конфигурации

Результаты тестирования:

Тестовый скрипт предоставляет подробный отчет о состоянии системы с градацией результатов:

• SUCCESS - тест пройден успешно
• ERROR - критическая ошибка, требующая внимания
• WARNING - некритическая проблема или рекомендация

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

Пример 1: Отправка отчета об ошибке

Администратор: /report_error bug Не работает команда /weather Бот не показывает погоду при запросе команды
Бот: Отчет успешно отправлен! ID ошибки: 1
Разработчик: Получает уведомление в настроенном чате

Пример 2: Анализ ошибки ИИ

Администратор: /analyze_error_ai 1
Бот: Начинаю анализ ошибки #1 с помощью ИИ...
[Через некоторое время]
Бот: Анализ завершен! Предоставляет структурированный анализ с рекомендациями

Пример 3: Добавление в план разработки

Администратор: /add_error_to_todo 1 high
Бот: Ошибка #1 успешно добавлена в TODO список в раздел высокого приоритета

Пример 4: Автореакция на положительные сообщения

Пользователь: Отличная работа! +
Бот: 🤝 (автоматически ставит реакцию рукопожатия)

🚀 Развертывание

Локальное развертывание

Обычный запуск

# 1. Клонируйте репозиторий
git clone <repository-url>
cd telegram_bot

# 2. Установите зависимости
pip install -r requirements.txt

# 3. Настройте API ключи
cp config_template.py config_local.py
# Отредактируйте config_local.py

# 4. Запустите бота
python bot.py

# 5. В другом терминале запустите планировщик
python scheduler.py

Запуск с Docker

# 1. Соберите образ
docker build -t telegram-bot .

# 2. Создайте config_local.py с ключами API

# 3. Запустите бота
docker run -v $(pwd)/data:/app/data -v $(pwd)/config_local.py:/app/config_local.py telegram-bot

# Или с docker-compose
docker-compose up -d

Развертывание на сервере

Рекомендации для продакшена:

• Используйте виртуальное окружение Python
• Настройте supervisor или systemd для автозапуска
• Используйте reverse proxy (nginx) для безопасности
• Настройте логирование и мониторинг
• Регулярно создавайте резервные копии базы данных

Пример конфигурации systemd:

[Unit]
Description=Telegram Bot
After=network.target

[Service]
Type=simple
User=bot
WorkingDirectory=/path/to/telegram_bot
ExecStart=/path/to/venv/bin/python bot.py
Restart=always
Environment=PYTHONPATH=/path/to/telegram_bot

[Install]
WantedBy=multi-user.target

GitHub Actions (CI/CD)

Проект включает готовые workflows для автоматического тестирования и развертывания:

# Настройте секреты в репозитории:
# Settings > Secrets and variables > Actions
BOT_TOKEN=your_bot_token
OPENAI_API_KEY=your_openai_key
DEVELOPER_CHAT_ID=your_chat_id

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

• Проверка кода при каждом коммите
• Тестирование системы отчетов об ошибках
• Валидация базы данных и конфигурации

Автоматическое развертывание:

• Сборка Docker образа
• Деплой на сервер при обновлении main ветки
• Автоматическая настройка конфигурации

Лицензия

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

---

Последнее обновление: 16 октября 2025 (добавлена версия 1.4.0 с критическими исправлениями и система отчетов об ошибках)