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

```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) - быстрый старт