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

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

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

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI/CD](https://img.shields.io/badge/CI%2FCD-GitHub%20Actions-green.svg)](https://github.com)
[![Performance](https://img.shields.io/badge/Performance-Tested-brightgreen.svg)](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 ботов**