# Руководство по использованию TG Autoposter
## Сценарий 1: Первое использование
```
Шаг 1: Подготовка
├─ Получить токен от @BotFather
├─ Установить зависимости: pip install -r requirements.txt
├─ Создать .env файл с токеном
└─ Запустить бота: python main.py
Шаг 2: Добавить бота в группу
├─ Найти бота в Telegram (по username)
├─ Открыть группу
├─ Нажать "Добавить участника"
├─ Выбрать вашего бота
└─ Бот автоматически обнаружит группу и сохранит информацию
Шаг 3: Первое сообщение
├─ В личном чате с ботом отправить /start
├─ Нажать "📨 Сообщения"
├─ Нажать "➕ Новое сообщение"
├─ Ввести название: "Мое первое сообщение"
├─ Ввести текст: "Привет, это работает!"
├─ Выбрать группу (нажать на неё)
├─ Нажать "✔️ Готово"
└─ Нажать "📤 Отправить" для отправки
Результат: Сообщение отправлено в группу! ✅
```
## Сценарий 2: Рассылка в несколько групп
```
Шаг 1: Добавить боты в несколько групп
├─ Повторить процесс добавления для каждой группы
├─ Бот сохранит все группы в БД
└─ Вы сможете видеть все в меню "👥 Группы"
Шаг 2: Создать сообщение
├─ /start → "📨 Сообщения" → "➕ Новое сообщение"
├─ Название: "Важное объявление"
├─ Текст: "Сервис будет на обслуживании"
├─ Выбрать группы: ✅ Группа 1, ✅ Группа 2, ✅ Группа 3
├─ "✔️ Готово"
└─ Нажать "📤 Отправить"
Результат: Одно сообщение отправлено в 3 группы! ✅
```
## Сценарий 3: Сообщения с форматированием
```
Текст с HTML:
Жирный текст
Курсив
Подчеркивание
Код
Ссылка
Результат в Telegram:
**Жирный текст**
_Курсив_
Подчеркивание
`Код`
[Ссылка](https://example.com)
```
## Сценарий 4: Работа с Slow Mode
```
Группа имеет slow mode = 5 секунд (настройка группы в Telegram)
Шаг 1: Создать 2 сообщения
├─ Сообщение 1: "Первое"
└─ Сообщение 2: "Второе"
Шаг 2: Отправить оба в одну группу
├─ Выбрать обе сообщения для одной группы
└─ Нажать "📤 Отправить"
Процесс отправки:
├─ Отправляется сообщение 1
├─ ⏳ Бот ждет 5 секунд (slow mode)
├─ Отправляется сообщение 2
├─ Готово!
└─ ✅ Успешно: 2, ❌ Ошибок: 0
Бот автоматически учитывает задержку! ✅
```
## Сценарий 5: Управление через CLI
```bash
# Создать сообщение через CLI
python cli.py message create
# → Название: "CLI сообщение"
# → Текст: "Создано через CLI"
# Список всех сообщений
python cli.py message list
# Список всех групп
python cli.py group list
# Сброс БД (осторожно!)
python cli.py db reset
# Запустить бота
python cli.py run
```
## Статус отправки
### При успешной отправке:
```
✅ Сообщение успешно отправлено
Статистика:
- ✅ Отправлено: 3
- ❌ Ошибок: 0
- Время ожидания: 10s (из-за slow mode)
```
### При ошибке:
```
⚠️ При отправке произошла ошибка
Статистика:
- ✅ Отправлено: 2
- ❌ Ошибок: 1 (бот не имеет прав на отправку)
Решение:
1. Убедитесь что бот добавлен в группу
2. Проверьте права на отправку сообщений
3. Попробуйте снова
```
## Обновление информации о группе
```
Боту нужно обновить информацию о slow mode?
Способ 1: Удалить из группы и добавить снова
├─ Удалить бота из группы
├─ Добавить бота обратно
└─ Информация обновится автоматически
Способ 2: Через CLI
├─ python cli.py db reset (осторожно!)
└─ Добавить бота в группы снова
```
## Устранение проблем
### Бот не видит группы
```
Проблема: Добавил бота в группу, но она не появляется
Решение:
1. Проверить что бот добавлен (смотреть участников группы)
2. Перезапустить бота
3. Добавить бота еще раз (удалить и добавить)
4. Проверить логи: cat logs/bot_*.log
```
### Сообщение не отправляется
```
Проблема: Нажал "Отправить", но сообщение не дошло
Решение:
1. Проверить что сообщение создано (список сообщений)
2. Проверить что группа добавлена (список групп)
3. Проверить права на отправку в группе
4. Проверить логи для деталей ошибки
Примеры ошибок:
- "Бот заблокирован в группе" → добавьте его снова
- "Нет прав на отправку" → дайте права администратора
- "Группа удалена" → удалите из БД: python cli.py group list
```
### БД ошибка
```
Проблема: "table groups not found" или подобное
Решение:
python migrate_db.py
# Выбрать опцию 1 (создать/обновить таблицы)
```
## Шпаргалка команд
### Telegram (в личных сообщениях с ботом)
- `/start` - Главное меню
- `/help` - Справка
### Меню (нажимаем кнопки)
- 📨 Сообщения → ➕ Новое → создание сообщения
- 📨 Сообщения → 📜 Список → просмотр/отправка
- 👥 Группы → 📜 Список → просмотр групп
- ⬅️ Назад → вернуться в меню
### CLI (в терминале)
```bash
# Сообщения
python cli.py message create # Создать
python cli.py message list # Список
python cli.py message delete # Удалить
# Группы
python cli.py group list # Список
# БД
python cli.py db init # Инициализировать
python cli.py db reset # Сбросить
# Запуск
python cli.py run # Запустить бота
python main.py # Или просто так
```
## Лучшие практики
### ✅ Делайте так:
1. Давайте краткие, понятные названия сообщениям
2. Пишите текст сообщения без ошибок
3. Тестируйте сначала в одной группе
4. Проверяйте логи при проблемах
5. Регулярно делайте бэкапы БД
### ❌ Не делайте так:
1. Не отправляйте спам
2. Не давайте боту токен кому-то другому
3. Не удаляйте БД файл без бэкапа
4. Не обновляйте slow mode через БД напрямую
5. Не добавляйте бота в приватные чаты (не будет работать)
## Аварийные процедуры
### Нужно обновить токен
```bash
1. Получить новый токен от @BotFather
2. Отредактировать .env
3. Перезапустить бота
4. Все работает!
```
### Нужно перенести БД на другой сервер
```bash
1. Скопировать файл autoposter.db на новый сервер
2. Скопировать остальной код
3. Запустить бота
4. Все группы и сообщения на месте!
```
### Нужно полностью сбросить и начать с нуля
```bash
1. python cli.py db reset
2. Выбрать "yes" для подтверждения
3. Все таблицы пересозданы
4. Добавить бота в группы снова
5. Создать сообщения заново
```
## Примеры реальных сценариев
### Сценарий A: Рассылка новостей
```
1. Группа 1: IT новости
2. Группа 2: Развитие
3. Группа 3: Проекты
Каждый день в 10:00 (подойти через cron):
- python send_message.py "новости_дня"
- Отправляется в 3 группы
- Каждой группе по 5 сек ожидания
- Все готово за 10 секунд
```
### Сценарий B: Критические алерты
```
1. БД падает
2. Скрипт отправляет алерт через бота
3. python cli.py message create "ALERT"
4. Выбираем группу "DevOps"
5. Отправляем немедленно
6. Алерт приходит в группу
```
### Сценарий C: Еженедельный отчет
```
1. Каждый понедельник в 09:00
2. Скрипт готовит отчет
3. Отправляет через бота в группу "Руководство"
4. Автоматическая рассылка
5. Никакого ручного вмешательства
```
## Полезные ссылки
- 🔗 [python-telegram-bot docs](https://python-telegram-bot.readthedocs.io/)
- 🔗 [Telegram Bot API](https://core.telegram.org/bots/api)
- 🔗 [SQLAlchemy docs](https://docs.sqlalchemy.org/)
- 🔗 [@BotFather](https://t.me/botfather) - создание ботов
---
Любые вопросы? Читайте документацию:
- 📖 [README.md](README.md) - полная информация
- 🔌 [API.md](API.md) - для разработчиков
- 🏗️ [ARCHITECTURE.md](ARCHITECTURE.md) - архитектура
- ⚡ [QUICKSTART.md](QUICKSTART.md) - быстрый старт