init commit

docs/USAGE_GUIDE.md

@@ -0,0 +1,313 @@
+# Руководство по использованию 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) - быстрый старт