bottohelp/.github/README.md

🚀 Telegram Bot с системой отчетов об ошибках и ИИ-анализом

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

🆕 Последние улучшения: Исправлены и оптимизированы форматтеры сообщений, добавлен CI/CD pipeline с автоматическим тестированием и тестами производительности!

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

🚀 Недавние улучшения (Версия 1.6.0)

• 🔧 Исправленные форматтеры - полная реализация с правильным HTML экранированием
• ⚡ Оптимизированная производительность - замеры показывают высокую скорость обработки
• 🎯 Таблица лидеров с медалями - визуальное выделение топ-3 пользователей (🥇🥈🥉)
• 🔄 CI/CD Pipeline - автоматическое тестирование и контроль качества
• 📊 Тесты производительности - проверка скорости критических функций

🤖 Система отчетов об ошибках с ИИ

• Умные отчеты - администраторы могут отправлять детальные отчеты об ошибках
• ИИ-анализ - автоматический анализ проблем с помощью OpenAI GPT
• Автоматическая интеграция - обработанные ошибки попадают в план разработки
• Уведомления разработчика - мгновенные оповещения о новых ошибках

🤝 Интерактивные функции

• Автореакции - автоматическая реакция 🤝 на сообщения с "+"
• Повышение вовлеченности - интерактивные элементы для активного общения

🎮 Игровые возможности

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

🤝 Интерактивные функции

• Автореакции - автоматическая реакция 🤝 на сообщения с "+"
• Повышение вовлеченности - интерактивные элементы для активного общения

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

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

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

• Модерация - бан, мут, кик, предупреждения пользователей
• Планировщик постов - автоматическая публикация по расписанию
• Импорт пользователей - загрузка данных из CSV файлов

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

• Погода - актуальная информация через OpenWeatherMap
• Новости - свежие новости через NewsAPI
• ИИ-анализ - интеллектуальная обработка ошибок через OpenAI

🚀 Быстрый старт

Предварительные требования

Python 3.10+
pip install -r requirements.txt

Настройка

1. Склонируйте репозиторий

   git clone <repository-url>
   cd telegram_bot
   

2. Настройте API ключи

   cp config_template.py config_local.py
   # Отредактируйте config_local.py с вашими ключами
   

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

   python bot.py
   

4. Протестируйте систему

   python test_error_system.py
   

📋 Команды администраторов

Система отчетов об ошибках

• /report_error <тип> <заголовок> [описание] - отправить отчет об ошибке
• /admin_errors [статус] - показать список ошибок
• /analyze_error_ai <ID> - проанализировать ошибку ИИ
• /add_error_to_todo <ID> - добавить в план разработки

Модерация

• /warn [пользователь] [причина] - выдать предупреждение
• /ban [пользователь] [причина] - заблокировать пользователя
• /mute [пользователь] [время] - временно заглушить

Управление контентом

• /schedule_post [время] [текст] - запланировать публикацию
• /list_posts - показать запланированные посты

🧪 Тестирование и качество кода

Проект включает комплексную систему тестирования для обеспечения надежности:

🚀 Автоматическое тестирование (CI/CD)

• GitHub Actions - автоматический запуск при каждом коммите
• Тесты безопасности - сканирование уязвимостей (bandit, safety)
• Тесты производительности - проверка скорости критических функций
• Валидация базы данных - контроль корректности данных

🧪 Локальное тестирование

# Тесты форматтеров (исправлены и оптимизированы)
python -m pytest test_utils/test_formatters.py -v

# Тесты производительности критических функций
python test_performance/test_critical_functions.py

# Тесты системы отчетов об ошибках
python test_error_system.py

📊 Показатели производительности

• Форматирование сообщений: < 1мс на операцию ⚡
• Таблица лидеров (1000 пользователей): < 10мс на операцию ⚡
• HTML экранирование: < 0.1мс на операцию ⚡
• Создание клавиатур: < 1мс на клавиатуру ⚡

Что тестируется:

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

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

telegram_bot/
├── bot.py                    # Основной файл бота
├── database_sqlite.py        # Работа с БД (+ таблица errors)
├── config_local.py          # Ваши API ключи (не публикуется)
├── config_template.py       # Шаблон для настройки
├── requirements.txt         # Зависимости Python
├── TODO.md                  # План разработки
├── utils/
│   ├── formatters.py       # 🔧 ФОРМАТТЕРЫ (исправлены и оптимизированы)
│   ├── __init__.py
│   ├── validators.py
│   └── helpers.py
├── test_utils/
│   └── test_formatters.py   # Тесты форматтеров (исправлены)
├── test_performance/
│   └── test_critical_functions.py # Тесты производительности ⚡
├── .github/
│   └── workflows/
│       └── ci.yml         # 🚀 CI/CD PIPELINE
├── test_error_system.py     # Тесты системы ошибок
├── README.md               # Полная документация
└── .gitignore              # Игнорируемые файлы

🔧 Настройка API ключей

Обязательные ключи:

• Telegram Bot Token - получите от @BotFather

Опциональные ключи:

• OpenWeatherMap API - для команды /weather
• NewsAPI - для команды /news
• OpenAI API - для анализа ошибок ИИ

Получение ключей:

1. Скопируйте config_template.py в config_local.py
2. Заполните реальными ключами API
3. Никогда не публикуйте config_local.py в открытый доступ

📊 База данных

Автоматически создается файл telegram_bot.db со следующими таблицами:

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

🤝 Как внести вклад

1. Сделайте форк проекта
2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)
3. Закоммитьте изменения (git commit -m 'Add amazing feature')
4. Отправьте в ветку (git push origin feature/amazing-feature)
5. Создайте Pull Request

📝 Лицензия

Этот проект распространяется под лицензией MIT - см. файл LICENSE для подробностей.

🙏 Поддержка проекта

Если вам нравится этот бот, вы можете поддержать разработку:

• ⭐ Поставьте звезду на GitHub
• 🐛 Сообщайте об ошибках через систему отчетов
• 💡 Предлагайте новые функции
• 🔄 Делайте форки и улучшайте код

---

📋 Быстрый запуск

1. Клонируйте репозиторий

   git clone <repository-url>
   cd telegram_bot
   

2. Настройте API ключи

   cp config_template.py config_local.py
   # Отредактируйте config_local.py
   

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

   pip install -r requirements.txt
   

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

   python bot.py
   

5. Протестируйте систему

   python test_error_system.py
   

🔧 Основные команды администраторов

Система отчетов об ошибках

• /report_error <тип> <заголовок> [описание] - отправить отчет
• /admin_errors [статус] - просмотреть ошибки
• /analyze_error_ai <ID> - проанализировать с ИИ
• /add_error_to_todo <ID> - добавить в план разработки

Типы ошибок

• bug - ошибка в работе бота
• crash - критическая ошибка/падение
• feature - предложение новой функции
• ui - проблема интерфейса
• security - проблема безопасности
• improvement - предложение улучшения

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

Docker (рекомендуется)

docker-compose up -d

Локальный запуск

# Основной бот
python bot.py

# Планировщик постов (в другом терминале)
python scheduler.py

Создано с ❤️ для сообщества Telegram ботов