TG_autoposter/docs/USERBOT_QUICKSTART.md

# Telethon UserBot Microservice - Краткая инструкция

## 🚀 Быстрый старт

### 1. Подготовка конфигурации

Добавьте в `.env`:

```bash
# Telethon Client Configuration
USE_TELETHON=true
TELETHON_API_ID=12345678                 # Получить на https://my.telegram.org
TELETHON_API_HASH=abcdef1234567890abcde  # Получить на https://my.telegram.org
TELETHON_PHONE=+1234567890               # Номер телефона UserBot
TELETHON_FLOOD_WAIT_MAX=60               # Макс время ожидания при flood
```

### 2. Первый запуск (Авторизация)

```bash
# Запустить интерактивно для авторизации
python userbot_service.py

# Следовать инструкциям - введите SMS код когда придет
# Сессия сохранится в sessions/userbot_session.session
```

### 3. Запуск в Docker

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

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

# Проверить логи userbot
docker-compose logs -f userbot
```

## 📊 Использование

### Через Telegram бот

Команда `/sync_groups` автоматически:
1. ✅ Инициализирует UserBot если нужно
2. 📊 Парсит всех участников групп
3. 💾 Сохраняет в PostgreSQL БД
4. ✏️ Обновляет информацию о группах

```
/sync_groups
⏳ Синхронизирую группы через UserBot парсер...
✅ Синхронизация завершена!
📊 Результаты:
• 🔄 Синхронизировано: 5 групп
```

### Через Celery задачи

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

# Парсить одну группу
parse_group_task.delay(chat_id=-1001234567890)

# Синхронизировать все группы
sync_all_groups_task.delay()

# Парсить участников с лимитом
parse_group_members_task.delay(chat_id=-1001234567890, limit=5000)
```

### Мониторинг в Flower

http://localhost:5555

## 📁 Структура файлов

```
app/userbot/
├── __init__.py           # Пакет
├── parser.py             # Основной парсер Telethon
└── tasks.py              # Celery задачи

app/handlers/
└── commands.py           # Команда /sync_groups (обновлена)

app/database/
├── repository.py         # GroupRepository.add_or_update_group()
└── member_repository.py  # GroupMemberRepository.add_or_update_member()

docker-compose.yml       # Добавлен сервис userbot
Dockerfile.userbot       # Dockerfile для userbot контейнера
userbot_service.py       # Точка входа микросервиса

docs/
└── USERBOT_MICROSERVICE.md  # Полная документация
```

## 🔄 Архитектура

```
┌─────────────────────────────────────────────────────────┐
│           Telegram Python-telegram-bot                   │
│                   (Основной бот)                         │
└────────────────┬────────────────────────────────────────┘
                 │
         /start, /sync_groups, /help
                 │
        ┌────────┴─────────────────────┐
        │                              │
        ▼                              ▼
  Callback Handlers              sync_groups_command
  (Управление UI)                  │
        │                           │
        │              ┌────────────┴──────┐
        │              │                   │
        ▼              ▼                   ▼
   Celery Tasks  PostgreSQL         UserBot Parser
        │              │              (telethon)
        │              │                   │
        ▼              ▼                   ▼
 Flower Monitor   Tables:        TelethonClient
  (http:5555)    - groups        (telethon_session)
                 - messages          │
                 - members           │
                                     ▼
                            Telegram UserBot
                            (@username от юзера)
```

## ⚡ Основные компоненты

### 1. UserbotParser (parser.py)

```python
# Методы:
await userbot_parser.initialize()           # Инициализировать
await userbot_parser.parse_group_info(cid)  # Получить информацию
await userbot_parser.parse_group_members()  # Получить участников
await userbot_parser.sync_group_to_db()     # Синхронизировать в БД
```

### 2. Celery Tasks (tasks.py)

```python
# Задачи:
initialize_userbot_task()        # Инициализировать при старте
parse_group_task(chat_id)        # Парсить одну группу
sync_all_groups_task()           # Синхронизировать все
parse_group_members_task(cid)    # Парсить участников
```

### 3. Database Models

```
Group
├── id (Primary Key)
├── chat_id (Telegram ID)
├── title
├── description
├── members_count
├── is_active
└── timestamps

GroupMember
├── id (Primary Key)
├── group_id (Foreign Key → Group)
├── user_id (Telegram User ID)
├── username
├── first_name / last_name
├── is_bot, is_admin, is_owner
└── timestamps
```

## 🔐 Безопасность

⚠️ **Важно!**

- ✅ Используйте **отдельный аккаунт Telegram** для UserBot
- ✅ **Никогда** не делитесь сессионным файлом `sessions/userbot_session.session`
- ✅ **Не коммитьте** API_ID и API_HASH в Git
- ✅ Храните в `.env.local` (добавлено в .gitignore)

## 📈 Производительность

| Размер группы | Рекомендуемый limit | Celery workers |
|---|---|---|
| < 1K | 1000 | 1-2 |
| 1K - 10K | 5000 | 2-4 |
| > 10K | 10000 | 4-8 |

## 🛠 Troubleshooting

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

```bash
# Удалить старую сессию
rm sessions/userbot_session.session

# Авторизироваться заново
python userbot_service.py
```

### "FloodWait 3600"

Это нормально - Telegram ограничивает быстрые запросы. Парсер автоматически ждет и продолжает.

### "Нет доступа к группе"

1. Убедитесь что UserBot добавлен в группу
2. Дайте администраторские права если нужно

## 📝 Примеры

### Пример 1: Синхронизировать все группы по расписанию

```python
# В celery_beat_schedule
from celery.schedules import crontab

app.conf.beat_schedule = {
    'sync-all-groups-daily': {
        'task': 'app.userbot.tasks.sync_all_groups',
        'schedule': crontab(hour=0, minute=0),  # Каждый день в 00:00
    },
}
```

### Пример 2: Получить количество ботов в группе

```python
from app.database.member_repository import GroupMemberRepository

async with AsyncSessionLocal() as session:
    repo = GroupMemberRepository(session)
    bot_count = await repo.get_bot_count(group_id=123)
    print(f"Ботов в группе: {bot_count}")
```

### Пример 3: Найти членов по имени

```python
members = await repo.search_members_by_name(group_id=123, keyword="John")
for member in members:
    print(f"{member.first_name} {member.last_name} (@{member.username})")
```

## 📚 Дополнительно

- Полная документация: [docs/USERBOT_MICROSERVICE.md](./USERBOT_MICROSERVICE.md)
- Исходный код: [app/userbot/](../app/userbot/)
- Логирование: `docker-compose logs -f userbot`

## ✅ Что реализовано

- ✅ Отдельный микросервис Telethon
- ✅ Парсинг групп и участников
- ✅ Сохранение в PostgreSQL
- ✅ Celery интеграция
- ✅ Flower мониторинг
- ✅ Docker контейнер
- ✅ Интеграция с основным ботом (`/sync_groups`)
- ✅ Обработка ошибок и FloodWait
- ✅ Полная документация

## 🎯 Следующие шаги

1. Авторизировать UserBot (python userbot_service.py)
2. Собрать и запустить Docker (docker-compose up -d)
3. Протестировать /sync_groups в Telegram боте
4. Проверить данные в PostgreSQL
5. Мониторить через Flower (http://localhost:5555)