TG_autoposter/USERBOT_README.md

# 🤖 Telethon UserBot Microservice

**Отдельный микросервис для парсинга Telegram групп и участников от имени пользователя (UserBot)**

## 📋 Содержание

- [Обзор](#обзор)
- [Быстрый старт](#быстрый-старт)
- [Архитектура](#архитектура)
- [Структура проекта](#структура-проекта)
- [Примеры использования](#примеры-использования)
- [Документация](#документация)

## 📖 Обзор

### Что это?

Telethon UserBot Microservice - это **отдельный микросервис**, который работает **независимо** от основного Python-Telegram-Bot и позволяет:

✅ Парсить информацию о Telegram группах и каналах  
✅ Получать список участников группы  
✅ Сохранять данные в PostgreSQL БД  
✅ Работать асинхронно через Celery  
✅ Мониторить через Flower UI  

### Почему отдельный микросервис?

1. **Независимость** - UserBot работает отдельно от основного бота
2. **Масштабируемость** - можно запустить несколько инстансов для разных групп
3. **Надежность** - сбой парсера не влияет на основной бот
4. **Гибкость** - легко отключить/включить парсинг
5. **Производительность** - асинхронная обработка Celery задач

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

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

```bash
# Скопировать пример конфигурации
cp .env.example .env

# Отредактировать .env и добавить:
TELETHON_API_ID=12345678
TELETHON_API_HASH=abcdef1234567890
TELETHON_PHONE=+1234567890
USE_TELETHON=true
```

### 2️⃣ Авторизация UserBot

```bash
# Запустить скрипт инициализации (или вручную)
bash init_userbot.sh

# Или авторизироваться вручную:
python userbot_service.py
```

При запуске приложение запросит SMS код - введите его для авторизации.

### 3️⃣ Запуск в Docker

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

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

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

### 4️⃣ Тестирование

```bash
# В Telegram боте:
/sync_groups

# В Flower UI:
http://localhost:5555
```

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

```
┌──────────────────────────────────────────────────────────┐
│                 Telegram API                              │
└─────────────────────┬──────────────────────────────────────┘
                      │
     ┌────────────────┴──────────────────┐
     │                                   │
     ▼                                   ▼
┌─────────────────┐              ┌──────────────────┐
│ Python-Telegram │              │ Telethon UserBot │
│      Bot        │              │   Microservice   │
│                 │              │                  │
│ /sync_groups───────────────────→ Parser           │
│ Callback UI     │              │ (async)          │
└────────┬────────┘              │                  │
         │                       │ Telethon Client  │
         │                       │ (telethon_session│
         │                       └────────┬─────────┘
         │                                │
         └────────────────┬───────────────┘
                          │
                  ┌───────▼────────┐
                  │   Celery Tasks  │
                  │  (async jobs)   │
                  └────────┬────────┘
                           │
                  ┌────────▼─────────┐
                  │  PostgreSQL DB   │
                  │                  │
                  │ Tables:          │
                  │ - groups         │
                  │ - group_members  │
                  │ - messages       │
                  └──────────────────┘

Мониторинг:
http://localhost:5555 (Flower)
docker-compose logs -f userbot
```

## 📁 Структура проекта

```
TG_autoposter/
├── app/
│   ├── userbot/                    # 🆕 UserBot микросервис
│   │   ├── __init__.py
│   │   ├── parser.py               # Основной парсер
│   │   └── tasks.py                # Celery задачи
│   │
│   ├── handlers/
│   │   └── commands.py             # Обновлена /sync_groups
│   │
│   ├── database/
│   │   ├── repository.py           # Обновлен GroupRepository
│   │   └── member_repository.py    # Обновлен GroupMemberRepository
│   │
│   └── models/
│       ├── group.py
│       └── group_members.py        # GroupMember модель
│
├── docs/
│   ├── USERBOT_MICROSERVICE.md     # 📚 Полная документация
│   └── USERBOT_QUICKSTART.md       # ⚡ Краткая инструкция
│
├── userbot_service.py              # 🆕 Точка входа микросервиса
├── Dockerfile.userbot              # 🆕 Docker для userbot
├── docker-compose.yml              # Обновлен (добавлен userbot)
├── init_userbot.sh                 # 🆕 Скрипт инициализации
└── examples_userbot.py             # 🆕 Примеры использования
```

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

### Пример 1: Использование через Telegram бот

```bash
# Отправить в боте:
/sync_groups

# Результат в БД:
✅ Информация о группах обновлена
👥 Списки участников синхронизированы
💾 Данные сохранены в PostgreSQL
```

### Пример 2: Programmatic использование

```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)
```

### Пример 3: Celery задачи

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

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

# Мониторить в Flower: http://localhost:5555
```

### Пример 4: Запросы к БД

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

async with AsyncSessionLocal() as session:
    repo = GroupMemberRepository(session)
    
    # Получить всех участников
    members = await repo.get_members_by_group(group_id=1)
    
    # Найти администраторов
    admins = [m for m in members if m.is_admin]
    
    # Найти ботов
    bots = [m for m in members if m.is_bot]
```

## 📚 Документация

### Основные файлы документации:

1. **[USERBOT_QUICKSTART.md](./docs/USERBOT_QUICKSTART.md)** ⚡
   - Быстрый старт за 5 минут
   - Основные команды
   - Примеры использования

2. **[USERBOT_MICROSERVICE.md](./docs/USERBOT_MICROSERVICE.md)** 📖
   - Полная документация
   - API справка
   - Troubleshooting
   - Производительность
   - Безопасность

### Примеры кода:

```bash
# Интерактивные примеры
python examples_userbot.py
```

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

### UserbotParser (app/userbot/parser.py)

```python
# Основной класс для парсинга

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

### Celery Tasks (app/userbot/tasks.py)

```python
# Асинхронные задачи

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

### Database моделе

```python
# GroupMember модель
class GroupMember:
    id: int
    group_id: int  # Foreign Key
    user_id: str   # Telegram User ID
    username: str
    first_name: str
    last_name: str
    is_bot: bool
    is_admin: bool
    is_owner: bool
    joined_at: datetime
    created_at: datetime
    updated_at: datetime
```

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

⚠️ **Важные рекомендации:**

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

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

### Через логи

```bash
docker-compose logs -f userbot | grep "✅\|❌\|⏳"
```

### Через Flower

http://localhost:5555

Отслеживайте:
- Active tasks
- Task history
- Worker statistics
- Pool information

### Метрики

```bash
# Подключиться к БД и получить статистику
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;
```

## 🚀 Развертывание в production

### Docker Compose

```yaml
userbot:
  build:
    context: .
    dockerfile: Dockerfile.userbot
  environment:
    USE_TELETHON: true
    TELETHON_API_ID: ${TELETHON_API_ID}
    TELETHON_API_HASH: ${TELETHON_API_HASH}
    # ... остальные переменные
  depends_on:
    - postgres
    - redis
  restart: unless-stopped
```

### Kubernetes

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tg-autoposter-userbot
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tg-autoposter-userbot
  template:
    metadata:
      labels:
        app: tg-autoposter-userbot
    spec:
      containers:
      - name: userbot
        image: tg-autoposter-userbot:latest
        env:
        - name: TELETHON_API_ID
          valueFrom:
            secretKeyRef:
              name: telegram-secrets
              key: api_id
```

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

| Параметр | Значение |
|---|---|
| Макс участников на группу | 100K+ |
| Параллельные задачи Celery | 4-8 воркеров |
| Лимит rate (Telegram) | ~33 req/sec |
| Типичное время парсинга 5K группы | ~2-3 минуты |
| Использование памяти | ~200-500 MB |

## 🆘 Troubleshooting

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

```bash
# Удалить сессию и авторизироваться заново
rm sessions/userbot_session.session*
python userbot_service.py
```

### ⏳ "FloodWait 3600"

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

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

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

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

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

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

1. ✅ Авторизировать UserBot: `bash init_userbot.sh`
2. ✅ Собрать Docker: `docker-compose build`
3. ✅ Запустить сервисы: `docker-compose up -d`
4. ✅ Протестировать `/sync_groups` в боте
5. ✅ Проверить данные в PostgreSQL
6. ✅ Мониторить через Flower: `http://localhost:5555`

## 📞 Поддержка

Проблемы и вопросы?

- 📖 Полная документация: [docs/USERBOT_MICROSERVICE.md](./docs/USERBOT_MICROSERVICE.md)
- ⚡ Быстрый старт: [docs/USERBOT_QUICKSTART.md](./docs/USERBOT_QUICKSTART.md)
- 💻 Примеры: `python examples_userbot.py`
- 🔍 Логи: `docker-compose logs -f userbot`

## 📝 Лицензия

Внутренний микросервис проекта TG Autoposter

---

**Создано для масштабируемого парсинга Telegram групп 🚀**