TG_autoposter/docs/USAGE_GUIDE.md

Руководство по использованию 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:
<b>Жирный текст</b>
<i>Курсив</i>
<u>Подчеркивание</u>
<code>Код</code>
<a href="https://example.com">Ссылка</a>

Результат в 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

# Создать сообщение через 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 (в терминале)

# Сообщения
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. Не добавляйте бота в приватные чаты (не будет работать)

Аварийные процедуры

Нужно обновить токен

1. Получить новый токен от @BotFather
2. Отредактировать .env
3. Перезапустить бота
4. Все работает!

Нужно перенести БД на другой сервер

1. Скопировать файл autoposter.db на новый сервер
2. Скопировать остальной код
3. Запустить бота
4. Все группы и сообщения на месте!

Нужно полностью сбросить и начать с нуля

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
• 🔗 Telegram Bot API
• 🔗 SQLAlchemy docs
• 🔗 @BotFather - создание ботов

---

Любые вопросы? Читайте документацию:

• 📖 README.md - полная информация
• 🔌 API.md - для разработчиков
• 🏗️ ARCHITECTURE.md - архитектура
• ⚡ QUICKSTART.md - быстрый старт