mirror of
https://github.com/FerraSoft/bottohelp.git
synced 2026-08-06 21:55:03 +00:00
277 lines
13 KiB
Markdown
277 lines
13 KiB
Markdown
# 🚀 Telegram Bot с системой отчетов об ошибках и ИИ-анализом
|
|
|
|
Многофункциональный Telegram бот на Python с продвинутой системой ранжирования пользователей, играми и интеграцией с внешними API.
|
|
|
|
> **🆕 Последние улучшения:** Исправлены и оптимизированы форматтеры сообщений, добавлен CI/CD pipeline с автоматическим тестированием и тестами производительности!
|
|
|
|
[](https://python.org)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://github.com)
|
|
[](https://github.com)
|
|
|
|
## ✨ Основные возможности
|
|
|
|
### 🚀 Недавние улучшения (Версия 1.6.0)
|
|
- **🔧 Исправленные форматтеры** - полная реализация с правильным HTML экранированием
|
|
- **⚡ Оптимизированная производительность** - замеры показывают высокую скорость обработки
|
|
- **🎯 Таблица лидеров с медалями** - визуальное выделение топ-3 пользователей (🥇🥈🥉)
|
|
- **🔄 CI/CD Pipeline** - автоматическое тестирование и контроль качества
|
|
- **📊 Тесты производительности** - проверка скорости критических функций
|
|
|
|
### 🤖 Система отчетов об ошибках с ИИ
|
|
- **Умные отчеты** - администраторы могут отправлять детальные отчеты об ошибках
|
|
- **ИИ-анализ** - автоматический анализ проблем с помощью OpenAI GPT
|
|
- **Автоматическая интеграция** - обработанные ошибки попадают в план разработки
|
|
- **Уведомления разработчика** - мгновенные оповещения о новых ошибках
|
|
|
|
### 🤝 Интерактивные функции
|
|
- **Автореакции** - автоматическая реакция 🤝 на сообщения с "+"
|
|
- **Повышение вовлеченности** - интерактивные элементы для активного общения
|
|
|
|
### 🎮 Игровые возможности
|
|
- **Классические игры**: Камень-ножницы-бумага, Крестики-нолики, Викторина
|
|
- **Расширенные игры**: Морской бой, 2048, Тетрис, Змейка
|
|
- **Система достижений** - разблокировка значков и начисление очков
|
|
|
|
### 🤝 Интерактивные функции
|
|
- **Автореакции** - автоматическая реакция 🤝 на сообщения с "+"
|
|
- **Повышение вовлеченности** - интерактивные элементы для активного общения
|
|
|
|
### 📊 Система ранжирования
|
|
- **Военная иерархия** - от Рядового до Маршала
|
|
- **Рейтинговые таблицы** - топ пользователей по очкам
|
|
- **Достижения** - система значков и наград
|
|
|
|
### 🛠 Администрирование
|
|
- **Модерация** - бан, мут, кик, предупреждения пользователей
|
|
- **Планировщик постов** - автоматическая публикация по расписанию
|
|
- **Импорт пользователей** - загрузка данных из CSV файлов
|
|
|
|
### 🌐 Интеграция с API
|
|
- **Погода** - актуальная информация через OpenWeatherMap
|
|
- **Новости** - свежие новости через NewsAPI
|
|
- **ИИ-анализ** - интеллектуальная обработка ошибок через OpenAI
|
|
|
|
## 🚀 Быстрый старт
|
|
|
|
### Предварительные требования
|
|
```bash
|
|
Python 3.10+
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Настройка
|
|
1. **Склонируйте репозиторий**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd telegram_bot
|
|
```
|
|
|
|
2. **Настройте API ключи**
|
|
```bash
|
|
cp config_template.py config_local.py
|
|
# Отредактируйте config_local.py с вашими ключами
|
|
```
|
|
|
|
3. **Запустите бота**
|
|
```bash
|
|
python bot.py
|
|
```
|
|
|
|
4. **Протестируйте систему**
|
|
```bash
|
|
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)
|
|
- **Тесты производительности** - проверка скорости критических функций
|
|
- **Валидация базы данных** - контроль корректности данных
|
|
|
|
### 🧪 Локальное тестирование
|
|
```bash
|
|
# Тесты форматтеров (исправлены и оптимизированы)
|
|
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](https://t.me/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](LICENSE) для подробностей.
|
|
|
|
## 🙏 Поддержка проекта
|
|
|
|
Если вам нравится этот бот, вы можете поддержать разработку:
|
|
- ⭐ Поставьте звезду на GitHub
|
|
- 🐛 Сообщайте об ошибках через систему отчетов
|
|
- 💡 Предлагайте новые функции
|
|
- 🔄 Делайте форки и улучшайте код
|
|
|
|
---
|
|
|
|
## 📋 Быстрый запуск
|
|
|
|
1. **Клонируйте репозиторий**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd telegram_bot
|
|
```
|
|
|
|
2. **Настройте API ключи**
|
|
```bash
|
|
cp config_template.py config_local.py
|
|
# Отредактируйте config_local.py
|
|
```
|
|
|
|
3. **Установите зависимости**
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
4. **Запустите бота**
|
|
```bash
|
|
python bot.py
|
|
```
|
|
|
|
5. **Протестируйте систему**
|
|
```bash
|
|
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 (рекомендуется)
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Локальный запуск
|
|
```bash
|
|
# Основной бот
|
|
python bot.py
|
|
|
|
# Планировщик постов (в другом терминале)
|
|
python scheduler.py
|
|
```
|
|
|
|
**Создано с ❤️ для сообщества Telegram ботов** |