bottohelp/README.md

# Telegram Bot

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

## Функции

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

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

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

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

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

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

### 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` - Запустить мини-игру

#### Посты по расписанию (только админы)
- `/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)
- Поддержка изображений в постах
- Автоматическая публикация через планировщик
- Управление постами только администраторами чата
- Все посты сохраняются в базе данных с историей публикаций

#### Примеры использования планировщика:
```
/schedule_post +1h Добро пожаловать в наш чат!
/schedule_post 2024-01-15 09:00 Ежедневное утреннее приветствие
/schedule_post +30m Важное объявление для всех участников
```

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

```
telegram_bot/
├── bot.py              # Основной файл бота
├── config.py           # Конфигурация (токены, настройки БД)
├── database_sqlite.py  # Работа с SQLite базой данных
├── scheduler.py        # Планировщик постов по расписанию
├── migrate_ranks.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 для подробностей.