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. Клонирование репозитория
```bash
git clone <repository-url>
cd telegram_bot
```

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

### 3. Настройка базы данных
База данных SQLite настраивается автоматически при первом запуске бота. Файл базы данных `telegram_bot.db` создается в корневой директории проекта.

### 4. Получение токенов API
- **Telegram Bot Token**: Получите от [@BotFather](https://t.me/botfather)
- **OpenWeatherMap API Key**: Зарегистрируйтесь на [openweathermap.org](https://openweathermap.org/api)
- **NewsAPI Key**: Зарегистрируйтесь на [newsapi.org](https://newsapi.org/)
- **OpenAI API Key**: Зарегистрируйтесь на [platform.openai.com](https://platform.openai.com/) для анализа ошибок ИИ

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

```python
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. Запуск бота
```bash
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. Запуск планировщика постов
Для работы постов по расписанию запустите планировщик в отдельном терминале:
```bash
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()`

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

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

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

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

```bash
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: Автореакция на положительные сообщения
```
Пользователь: Отличная работа! +
Бот: 🤝 (автоматически ставит реакцию рукопожатия)
```

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

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

#### Обычный запуск
```bash
# 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
```bash
# 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:
```ini
[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 для автоматического тестирования и развертывания:

```bash
# Настройте секреты в репозитории:
# 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 с критическими исправлениями и система отчетов об ошибках)*