WebJesus SEO Bot — обзор и архитектура
Telegram-бот на Python для SEO-анализа: пользователь присылает список пар "URL + запрос" (файлом .txt или Excel), бот прогоняет каждый запрос через один из пяти парсеров выдачи, списывает баланс за каждый запрос и возвращает CSV с результатами. Реальный коммерческий продукт с платящими пользователями, не учебный проект — приватный репозиторий Mentigen/webjesus-seo.
Архитектурная схема (archify) →
Пять парсеров, не два
Первое, что стоит поправить в собственном представлении о проекте: это не "парсер Google + парсер Yandex". PARSER_PRICING в tariffs.py перечисляет пять типов: yandex, google, perplexity, gemini, gpt — у каждого своя цена за запрос, настраиваемая через конфиг (config.GOOGLE_COST_PER_QUERY и так далее), а не захардкоженная.
Выбор конкретного парсера инкапсулирован в ParserFactory — паттерн Фабрика, единая точка входа get_parser(type).fetch(), за которой прячутся пять независимых адаптеров. Хендлеру бота не важно, к какому именно внешнему API идёт запрос — он просто вызывает фабрику с типом парсера и получает единый по форме результат.
Поток "файл → парсинг → CSV"
Пользователь присылает .txt (построчно URL query) или Excel (.xlsx/.xls, две колонки — URL и запрос, парсится через openpyxl). Бот проверяет баланс относительно тарифа выбранного парсера, для каждой строки вызывает ParserFactory.get_parser(type).fetch(url, query), копит результаты и формирует CSV-отчёт с позициями.
Middleware при первом обращении пользователя создаёт запись в таблице users и начисляет приветственный бонус — welcome_bonus_received/channel_bonus_received в модели User следят, чтобы бонус не начислялся повторно.
Технологический стек
Python 3.8+, aiogram 3.0+ (Telegram-бот, middlewares/ для сквозной логики вроде создания юзера), SQLAlchemy 2.0+ (async, три модели: User, Transaction, ProcessingStatus-задачи), Alembic (миграции), openpyxl (Excel), Postgres/SQLite (оба поддержаны движком SQLAlchemy без смены кода), T-Bank API и Lava.top — два независимых платёжных провайдера одновременно.
Мультиязычность и структура
localization.py — отдельный модуль на ~28 КБ, интерфейс на русском и английском. Структура: google_ai_scrapper/ (handlers/middlewares/models/parsers/services/bot.py — основной Python-модуль бота), yandex-search-api-parser/ (отдельный модуль конвертации в CSV с поддержкой Excel), alembic/ (миграции), docs/ (инструкции по установке и деплою).