# ✅ Telethon UserBot Microservice - CHECKLIST

## 🚀 Быстрый старт за 10 минут

### 1. Подготовка (2 мин)

- [ ] Откройте `.env` файл
- [ ] Найдите в `.env`:
  - `TELETHON_API_ID` - ваш Telegram API ID
  - `TELETHON_API_HASH` - ваш Telegram API Hash  
  - `TELETHON_PHONE` - номер телефона отдельного Telegram аккаунта (для UserBot)

```bash
# Если чего-то не хватает в .env:
TELETHON_API_ID=12345678
TELETHON_API_HASH=abcdef1234567890abcdef
TELETHON_PHONE=+1234567890
USE_TELETHON=true
```

### 2. Авторизация UserBot (3 мин)

```bash
# Способ 1: Автоматический скрипт (рекомендуется)
bash init_userbot.sh

# Способ 2: Вручную запустить
python userbot_service.py
```

**Что будет происходить:**
1. Приложение подключится к Telegram API
2. Запросит SMS код на указанный номер телефона
3. Введите SMS код
4. Сессия сохранится в `sessions/userbot_session.session`
5. Готово! ✅

### 3. Сборка Docker (3 мин)

```bash
# Пересобрать все контейнеры
docker-compose build

# Запустить сервисы
docker-compose up -d

# Проверить что все работает
docker-compose logs -f userbot
```

**Ожидаемый вывод:**
```
✅ UserBot initialized successfully
✅ Telethon client connected
✅ Ready to parse groups
```

### 4. Тестирование в боте (2 мин)

1. Откройте Telegram бота
2. Отправьте команду: `/sync_groups`
3. Бот должен ответить: "Syncing groups with UserBot..."
4. Нажмите кнопку "Sync" (если появится)
5. Ждите обновления данных

**Ожидаемый результат:**
```
✅ Groups synced successfully
👥 Members updated
💾 Data saved to database
```

### 5. Проверка БД (1 мин)

```bash
# Подключитесь к БД
docker-compose exec postgres psql -U admin -d tg_autoposter

# В psql выполните:
SELECT COUNT(*) as groups_count FROM groups;
SELECT COUNT(*) as members_count FROM group_members;
\q
```

---

## 🔍 Проверка каждого компонента

### ✅ Telethon UserBot Microservice

```bash
# Логи микросервиса
docker-compose logs -f userbot

# Проверить что процесс запущен
docker ps | grep userbot
```

**Должны увидеть:**
- Container name: `tg_autoposter_userbot`
- Status: `Up X minutes`
- Логи без ошибок

### ✅ PostgreSQL Database

```bash
# Проверить БД контейнер
docker-compose logs postgres | tail -20

# Проверить таблицы
docker-compose exec postgres psql -U admin -d tg_autoposter -c \
  "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';"
```

**Должны увидеть таблицы:**
- `groups`
- `group_members`
- `users`
- `messages`
- И другие...

### ✅ Redis Queue

```bash
# Проверить Redis
docker-compose logs redis | tail -10

# Проверить что Redis работает
docker-compose exec redis redis-cli PING
```

**Ожидаемый ответ:** `PONG`

### ✅ Celery Workers

```bash
# Логи Celery воркеров
docker-compose logs -f celery_worker

# Должны видеть:
# - [tasks] Registered workers
# - [*] Connected to redis://redis:6379/0
```

### ✅ Flower UI (Мониторинг)

```bash
# Откройте в браузере:
http://localhost:5555

# Проверьте:
- Workers tab: должны быть доступные воркеры
- Tasks tab: история выполненных задач
```

### ✅ Основной Telegram Bot

```bash
# Логи бота
docker-compose logs -f bot

# Отправьте /start в боте
# Должны появиться кнопки главного меню
```

---

## 🆘 Если что-то не работает

### ❌ "UserBot не авторизован"

```bash
# Решение: удалить сессию и авторизироваться заново
rm sessions/userbot_session.session*
python userbot_service.py
# Введите SMS код
```

### ❌ "FloodWait 3600"

Это НОРМАЛЬНО! Telegram ограничивает частые запросы.
- Парсер автоматически ждет и продолжает
- Просто дождитесь завершения

### ❌ "Connection refused"

```bash
# Проверить все контейнеры работают
docker-compose ps

# Если какой-то не работает, перезагрузить:
docker-compose restart postgres redis celery_worker userbot bot
```

### ❌ "Permission denied" (при выполнении bash скрипта)

```bash
# Дать права на выполнение
chmod +x init_userbot.sh
bash init_userbot.sh
```

### ❌ "Cannot connect to database"

```bash
# Проверить PostgreSQL
docker-compose exec postgres psql -U admin -d postgres -c "SELECT 1;"

# Если не работает, переустановить:
docker-compose down postgres
docker volume rm tg_autoposter_postgres_data
docker-compose up -d postgres
```

---

## 📊 Мониторинг

### Реал-тайм логи

```bash
# UserBot логи (особенно важно)
docker-compose logs -f userbot

# Celery задачи
docker-compose logs -f celery_worker

# Бот
docker-compose logs -f bot

# Все логи сразу
docker-compose logs -f
```

### Web UI Flower

```bash
# Откройте в браузере
http://localhost:5555

# Смотрите:
# - Active tasks (выполняющиеся задачи)
# - Tasks history (история)
# - Worker pool (состояние воркеров)
# - Graphs (графики использования)
```

### Database Query Monitoring

```bash
# Подключиться к БД
docker-compose exec postgres psql -U admin -d tg_autoposter

# Получить статистику групп и участников
SELECT 
    g.title,
    COUNT(gm.id) as members_count,
    SUM(CASE WHEN gm.is_bot THEN 1 ELSE 0 END) as bots_count,
    SUM(CASE WHEN gm.is_admin THEN 1 ELSE 0 END) as admins_count
FROM groups g
LEFT JOIN group_members gm ON g.id = gm.group_id
GROUP BY g.id, g.title
ORDER BY members_count DESC;

# Выход из psql
\q
```

---

## 🧪 Примеры использования

### Вариант 1: Через Telegram бот

```
1. /start
2. Нажмите "Manage Groups"
3. Нажмите "Sync with UserBot"
4. Выберите группу для парсинга
5. Готово! ✅
```

### Вариант 2: Через Python код

```python
from app.userbot.parser import userbot_parser

# Инициализировать
await userbot_parser.initialize()

# Парсить
members = await userbot_parser.parse_group_members(chat_id=-1001234567890)

# Синхронизировать в БД
await userbot_parser.sync_group_to_db(chat_id=-1001234567890)

# Выключить
await userbot_parser.shutdown()
```

### Вариант 3: Через Celery задачи

```python
from app.userbot.tasks import parse_group_task

# Запустить асинхронно
task = parse_group_task.delay(chat_id=-1001234567890)

# Мониторить в Flower: http://localhost:5555
# Получить результат
result = task.get()
```

### Вариант 4: Интерактивный скрипт

```bash
python examples_userbot.py

# Выберите вариант из меню
# 1. Parse single group
# 2. Parse group members
# 3. Sync to database
# 4. Query from database
# 5. Search members
```

---

## 📈 Performance Optimization

Если парсинг идет медленно:

```bash
# Увеличить Celery воркеры в docker-compose.yml
celery_worker:
  environment:
    # ... других переменные ...
    CELERYD_CONCURRENCY: 8  # было 4, увеличили до 8
```

Потом пересобрать:
```bash
docker-compose build celery_worker
docker-compose up -d celery_worker
```

---

## ✨ Результаты

После выполнения всех шагов вы получите:

✅ Работающий Telethon UserBot микросервис  
✅ Парсинг групп и участников Telegram  
✅ Данные сохранены в PostgreSQL  
✅ Асинхронная обработка через Celery  
✅ Мониторинг через Flower UI  
✅ Логирование всех операций  
✅ Интеграция с основным ботом  

---

## 📞 Если нужна помощь

1. **Быстрый старт**: `docs/USERBOT_QUICKSTART.md`
2. **Полная документация**: `docs/USERBOT_MICROSERVICE.md`
3. **Примеры кода**: `examples_userbot.py`
4. **Logирование**: `docker-compose logs -f`
5. **Мониторинг**: http://localhost:5555 (Flower UI)

---

## 🎯 Финальная проверка

```bash
# Все компоненты должны быть в статусе Up

docker-compose ps

# NAME                           STATUS
# tg_autoposter_bot             Up X minutes
# tg_autoposter_userbot         Up X minutes  ← это новое!
# tg_autoposter_celery_worker   Up X minutes
# tg_autoposter_postgres        Up X minutes (healthy)
# tg_autoposter_redis           Up X minutes (healthy)
```

✅ **Все зеленое? Отлично! Вы готовы к использованию** 🚀

---

Создано: Phase 8 - Telethon UserBot Microservice  
Версия: 1.0  
Статус: Production Ready ✅