bottohelp/README.md

# Telegram Bot

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

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

### Версия 1.3.0 (16 октября 2025)
**Дата релиза:** 16.10.2025

#### 🐛 Исправления ошибок
- ✅ Исправлена ошибка с повторяющимся сообщением о "первом сообщении" при вводе суммы доната
- ✅ Исправлена проблема с кодировкой Unicode символов при запуске бота на Windows
- ✅ Исправлена система донатов - теперь корректно работает кнопка "Другая сумма"

#### ✨ Новые функции
- ✅ Добавлена команда `/donate` для поддержки проекта
- ✅ Добавлена информация о донатах в справку `/help`
- ✅ Улучшена система достижений - достижения разблокируются только один раз

#### 🔧 Технические улучшения
- ✅ Оптимизирована логика проверки достижений в базе данных
- ✅ Добавлена проверка существующих достижений перед разблокировкой
- ✅ Улучшена обработка ошибок в системе донатов

### Версия 1.2.0 (Предыдущая версия)
- 🚀 Добавлены расширенные игры: 2048, Тетрис, Змейка
- 🎯 Улучшена система достижений
- 📅 Расширенная система планировщика постов

## Функции

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

### Игровые элементы
- 🎮 Мини-игры: Камень-ножницы-бумага, Крестики-нолики, Викторина, Морской бой
- 🎯 Расширенные игры: 2048, Тетрис, Змейка
- 🧠 Система достижений и начисления очков
- Начисление дополнительных очков за участие в играх

### Администрирование чата
- ⚠️ Выдача предупреждений пользователям
- 🔇 Временное заглушение (mute)
- 🚫 Блокировка (ban) и кик пользователей
- 📊 Просмотр рейтинга и информации о пользователях

### Посты по расписанию
- ⏰ Планирование постов для автоматической публикации
- 📅 Гибкие форматы времени (абсолютное и относительное)
- 🖼 Поддержка изображений в постах
- 👥 Управление постами (только администраторы)
- 💾 Хранение всех постов в базе данных

### Интеграция с API
- 🌤️ Получение погоды (OpenWeatherMap)
- 📰 Последние новости (NewsAPI)
- 🌐 Перевод текста (Google Translate) - базовая реализация

### Система приветствий и донатов
- 🎉 Автоматическое приветствие новых пользователей с правилами группы
- ⏰ Автоматическое удаление приветственных сообщений через 2 минуты
- 👥 Обработка нескольких пользователей (удаление старого, создание нового приветствия)
- 💰 Интеграция кнопок донатов прямо в приветственные сообщения
- 🎯 Быстрый доступ к помощи через приветственные кнопки

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

### 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/)

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

```python
BOT_TOKEN = "your_bot_token_here"
OPENWEATHER_API_KEY = "your_weather_api_key_here"
NEWS_API_KEY = "your_news_api_key_here"
```

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

### Система ранжирования
- За каждое сообщение начисляется 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     # Локальная конфигурация с токенами
├── database_sqlite.py  # Работа с SQLite базой данных
├── database.py         # Базовые функции работы с БД
├── scheduler.py        # Планировщик постов по расписанию
├── migrate_ranks.py    # Миграция системы рангов
├── messages.py         # Текстовые сообщения и константы бота
├── requirements.txt    # Зависимости Python
└── README.md           # Эта документация
```

### 5. Запуск планировщика постов
Для работы постов по расписанию запустите планировщик в отдельном терминале:
```bash
python scheduler.py
```

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

## Технологии

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

## Разработка

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

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

## Лицензия

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