Telegram Analysis Bot — демо-портфолио

Коммерческий Telegram-бот для AI-анализа переписок: пользователь присылает текст или скриншоты диалога, бот распознаёт их (OCR/vision), структурирует и выдаёт персональный отчёт через LLM. Часть результата бесплатна, полный отчёт — после оплаты.

⚠️ Это демо-проект для портфолио. Код написан с нуля специально как пример архитектуры. Платёжный шлюз в демо имитируется (мок), реальный эквайринг (ЮKassa/ЛАВА/Робокасса) подключается через адаптер. Никакой клиентский код и данные не используются.

Возможности

• Команды: /start, /help, /analyze, /myanalyses, /referral, /support, /privacy, /terms, /delete
• FSM-меню: выбор способа загрузки (текст / скриншоты / TXT / PDF)
• Распознавание скриншотов через vision-LLM с сохранением структуры: участники, порядок, время, эмодзи, пунктуация
• Уточнение участников, если их не удалось определить автоматически
• Двухпроходный AI-анализ:
  1. структурированный анализ в JSON (взаимность 0–100, инициативность, вовлечённость, баланс, динамика, паттерны, рекомендации)
  2. генерация пользовательского отчёта на основе JSON
• Бесплатная часть результата → paywall → полный отчёт после оплаты
• Реферальная система t.me/bot?start=ref_<id> с защитой от саморефералов
• Аналитика ключевых событий в отдельной таблице
• PostgreSQL (SQLAlchemy async + Alembic), Redis, Docker Compose, деплой на Linux/VPS

Архитектура

┌─────────────────────── Telegram (aiogram 3) ───────────────────────┐
│  handlers/  FSM  keyboards  middleware  texts (i18n-ready)         │
└──────────────┬─────────────────────────────────────────────────────┘
               │
┌──────────────▼─────────────────────────────────────────────────────┐
│                        application services                        │
│  loaders (text / files / screenshots) → OCR → structured messages  │
│  analyzer (LLM JSON) → report builder (LLM text)                   │
│  payments (adapter: mock / YooKassa / Lava / Robokassa)            │
│  referrals, analytics, pricing (из БД)                              │
└──────────────┬─────────────────────────────────────────────────────┘
               │
┌──────────────▼──────────────┐   ┌──────────────────────────────────┐
│  PostgreSQL (async SQLAlch.)│   │  Redis (кэш, rate limit, очереди)│
│  users, analyses, payments, │   │                                  │
│  referrals, analytics_events│   │                                  │
└─────────────────────────────┘   └──────────────────────────────────┘

Смена AI/OCR-провайдера — через адаптер (LLMProvider, OCRProvider), без переписывания бизнес-логики.

Стек

• Python 3.11+, aiogram 3.x, SQLAlchemy 2 async, asyncpg, Alembic
• Redis (redis-py asyncio)
• FastAPI — приём вебхуков от платёжного сервиса (в демо — мок-эндпоинт)
• Docker / Docker Compose, Nginx (опционально)
• LLM API: OpenAI-совместимые (DeepSeek и др.), vision для OCR скриншотов

Быстрый старт (Docker)

cp .env.example .env
# заполнить: BOT_TOKEN, LLM_API_KEY, DATABASE_URL, REDIS_URL
docker compose up --build

Применение миграций: docker compose exec bot alembic upgrade head.

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

telegram-analysis-demo-bot/
├── bot/
│   ├── main.py               # точка входа aiogram
│   ├── config.py             # pydantic-settings
│   ├── db/
│   │   ├── base.py           # Base, get_session
│   │   ├── models.py         # User, Analysis, Payment, Referral, AnalyticsEvent
│   │   └── repository.py     # слой доступа к данным
│   ├── handlers/             # /start, /analyze, FSM, /myanalyses, /referral, ...
│   ├── keyboards/            # Reply/Inline клавиатуры
│   ├── services/
│   │   ├── loader.py         # приём текста/файлов
│   │   ├── ocr.py            # адаптер OCR (vision-LLM)
│   │   ├── analyzer.py       # AI-анализ (JSON) + генератор отчёта
│   │   ├── payments.py       # адаптер платежей (mock/yookassa/lava/robokassa)
│   │   ├── referrals.py      # реферальная логика
│   │   └── analytics.py      # события аналитики
│   ├── texts.py              # шаблоны сообщений
│   └── utils/
├── web/                      # FastAPI-приложение для webhook'ов платежей
├── alembic/                  # миграции
├── tests/                    # pytest
├── docker-compose.yml
├── Dockerfile
├── .env.example
└── README.md

Лицензия

MIT — демо-проект для портфолио. Реальные коммерческие боты клиентов не публикуются (NDA).