FunPay Hunter

Телеграм-бот и фоновый воркер для мониторинга предложений на FunPay с сохранением истории в Supabase/Postgres.

Сейчас проект уже умеет:

• парсить каталоги FunPay по HTTP;
• тянуть детали оффера и классифицировать тип доступа;
• нормализовать валюты в рубли через ЦБ РФ;
• сохранять текущий срез, историю цен и ранжирование;
• показывать горячие предложения в виде одного сообщения-слайдера;
• настраивать слежения в Telegram и присылать уведомления по cooldown.

Что важно знать

• Текущая рабочая схема БД пока остаётся на таблицах catalogs, targets, watchlists, listings_current, listing_history, target_matches.
• Это совместимый MVP-слой. Полный refactor на categories / monitored_items / user_watches / offers / price_history пока не делался, чтобы не ломать живой пайплайн.
• Пользовательский интерфейс бота и уведомления должны оставаться на русском.

Структура

.
|-- sql/
|   |-- 001_init.sql
|   |-- 002_seed_catalogs.sql
|   |-- 003_add_original_price_fields.sql
|   `-- 004_localize_seed_names.sql
|-- src/funpay_hunter/
|   |-- bot/
|   |-- parsing/
|   |-- services/
|   |-- storage/
|   `-- ...
|-- .env.example
`-- pyproject.toml

Подготовка Supabase

В SQL Editor выполни по порядку:

1. 001_init.sql
2. 002_seed_catalogs.sql
3. 003_add_original_price_fields.sql
4. 004_localize_seed_names.sql

Если база уже была поднята раньше, шаги 003 и 004 особенно важны: они добавляют поля оригинальной цены и переводят названия товаров в БД на русский формат.

Настройка окружения

1. Скопируй .env.example в .env.
2. Заполни:
   • DATABASE_URL
   • TELEGRAM_BOT_TOKEN
3. Создай виртуальное окружение и установи пакет.

Git Bash:

py -3.12 -m venv .venv
./.venv/Scripts/pip.exe install -e .

Быстрый bootstrap:

./scripts/bootstrap.sh

Основные переменные

• SCAN_INTERVAL_SECONDS: интервал фонового цикла.
• FUNPAY_MAX_OFFERS_PER_CATALOG: сколько офферов брать максимум из одного каталога.
• CURRENCY_RATES_URL: источник курсов валют.
• CURRENCY_RATES_FALLBACK_URL: резервный источник курсов, если ЦБ режет запросы по 403.
• CURRENCY_RATE_CACHE_SECONDS: кеш курсов.
• DEFAULT_NOTIFY_FREQUENCY_MINUTES: частота уведомлений по умолчанию для новых слежений.

Проверка

Git Bash:

./.venv/Scripts/funpay-hunter.exe doctor

Команда проверяет:

• доступность Postgres/Supabase;
• наличие ключевых таблиц;
• валидность Telegram bot token.

Запуск

Один проход парсинга:

./.venv/Scripts/funpay-hunter.exe scan-once

Фоновый цикл:

./.venv/Scripts/funpay-hunter.exe scan-loop

Telegram-бот:

./.venv/Scripts/funpay-hunter.exe bot

Деплой на Linux-сервер

Из текущего репозитория можно выкатывать релиз на VPS по SSH. Скрипт:

• загружает текущие tracked-файлы репозитория;
• отдельно копирует локальный .env;
• при необходимости ставит python3-venv и python3-pip;
• создаёт релиз в /opt/funpay-hunter/releases/<timestamp>;
• обновляет symlink /opt/funpay-hunter/current;
• поднимает systemd-сервисы funpay-hunter-bot и funpay-hunter-scan.

Проверка сервера:

./.venv/Scripts/python.exe scripts/deploy_server.py --host <IP> --user root --password '<PASSWORD>' preflight

Деплой:

./.venv/Scripts/python.exe scripts/deploy_server.py --host <IP> --user root --password '<PASSWORD>' deploy

Если .env уже лежит на сервере в /opt/funpay-hunter/shared/.env, можно не заливать его повторно:

./.venv/Scripts/python.exe scripts/deploy_server.py --host <IP> --user root --password '<PASSWORD>' --use-existing-env deploy

Проверка сервисов:

./.venv/Scripts/python.exe scripts/deploy_server.py --host <IP> --user root --password '<PASSWORD>' status
./.venv/Scripts/python.exe scripts/deploy_server.py --host <IP> --user root --password '<PASSWORD>' logs
./.venv/Scripts/python.exe scripts/deploy_server.py --host <IP> --user root --password '<PASSWORD>' doctor
./.venv/Scripts/python.exe scripts/deploy_server.py --host <IP> --user root --password '<PASSWORD>' restart

Автодеплой из GitHub

Есть workflow deploy.yml:

• на каждый push в main он выкатывает новую версию на сервер;
• из вкладки Actions можно вручную запустить deploy, restart, status или doctor.

Нужно добавить GitHub Secrets:

• FUNPAY_SSH_HOST
• FUNPAY_SSH_USER
• FUNPAY_SSH_PASSWORD
• FUNPAY_SSH_PORT — опционально, если не 22

Workflow использует --use-existing-env, поэтому сервер должен уже хранить рабочий .env в /opt/funpay-hunter/shared/.env.

Проверка конкретного каталога:

./.venv/Scripts/funpay-hunter.exe debug-catalog claude-subscriptions

Что уже есть в боте

• 🔥 Горячие предложения
• 🎯 Настроить слежение
• 📋 Мои слежения
• просмотр лучших офферов по одному товару через слайдер;
• настройка лимита цены, типа аккаунта, рейтинга, отзывов и частоты уведомлений;
• редактирование частоты по сохранённому слежению;
• персональные уведомления с кнопками Открыть лот, Пропустить, Отключить слежение.

Замечания по качеству

• Нормализация цен идёт через официальный XML ЦБ РФ.
• Если официальный XML ЦБ из окружения недоступен, используется резервный XML-источник без падения всего скана.
• Для валют с scientific notation уже есть обработка.
• Если в каталоге цена не в рублях, в БД сохраняются:
  • оригинальная строка;
  • числовое значение;
  • код валюты;
  • пересчитанная цена в рублях.
• Причины классификации и совпадения теперь формируются на русском, чтобы кнопка объяснения не показывала внутренний техтекст.

Ближайшие незакрытые пункты

• полноценный refactor схемы под v2-таблицы;
• inline-действие Добавить в избранное;
• self-audit отчёт как отдельный артефакт;
• живой прогон всех callback-веток руками в Telegram после перезапуска бота.