VFS Poland Queue Bot

Telegram-бот краудсорсинг-статистики очереди на польскую визу в Беларуси (VFS Global). Сайт VFS не сообщает положение в очереди, поэтому участники делятся своими датами через анкету, а бот превращает их в статистику, графики и прогнозы.

Бот: @Visa_Poland_Info_Bot · Группа: «Виза в Польшу | VFS Беларусь — очередь и статистика» (форум: 9 городов × 4 типа визы + «Общение» и «Статистика»).

Что умеет

Анкета полного жизненного цикла (/report, диалог с кнопками в личке): город → тип визы (D Other / D Driver / D Work / C Other) → дата и время постановки в очередь → письмо-приглашение → доступные даты записи (список дат/периодов) → подача документов → получение паспорта → результат (✅/❌) → срок выданной визы. Все шаги после постановки — пропускаемые.

• одна анкета на пользователя раз в 14 дней; в любой момент можно дополнить свою (кнопки «➡️ Оставить» пролистывают неизменившиеся шаги);
• публикация в тему города с кнопками «Анкета · Статистика · Прогноз»;
• валидация дат + карантин аномалий: подозрительно короткое ожидание письма → переспрос, пометка «сомнительная» (вне статистики), карточка модерации владельцу (удалить / оставить / доверять).

Статистика и прогнозы (/stats, кеш 1 час со сбросом при новой анкете): медианное ожидание письма, скорость очереди с трендом, горизонт записи, «фронт очереди» по месяцам, постановки по месяцам/дням, «до кого дошли приглашения» (дата+время постановки последнего приглашённого), сроки паспорта и результаты. Текстовые шкалы ████░░ + альбом из 4 графиков (matplotlib). Ежедневная автосводка в тему «Статистика» (09:00 Минск) с рейтингом городов.

Персональное: /my — прогноз письма по своей анкете (сколько впереди, в т.ч. по времени внутри дня), /mine — своя анкета со ссылкой на публикацию, /list — анкеты по городу с пагинацией и статусами.

Прочее: капча для вступающих через заявки (проверка в личке, в группе тишина), телеметрия воронки анкеты (/funnel, только владелец), автоудаление сервисных сообщений о закрепах.

Структура

main.py               # запуск: роутеры, меню команд, ежедневная сводка
backup.py             # дамп БД: gzip, ротация 30 дн., отправка админу
src/
  report_flow.py      # анкета (FSM), публикации, модерация, /funnel
  stats.py            # расчёты, кеш, тексты, графики
  stats_flow.py       # /stats, /my, deep-link'и статистики
  browse_flow.py      # /list, /mine
  captcha.py          # заявки на вступление + капча в личке
  topic_logger.py     # обработчики группы, логгер ID тем
  db.py               # SQLite: анкеты, алерты, события воронки
config/topics.json    # карта тем форума (город × тип -> thread_id)
scripts/              # деплой, обслуживание группы, диагностика

Деплой

Прод — VPS (Ubuntu 22.04), systemd-служба vfsbot в /opt/vfsbot:

python scripts/deploy.py          # заливка файлов + venv (SSH-ключ .ssh/vfsbot_deploy)
python scripts/restart_remote.py  # рестарт службы + хвост журнала

Бэкапы: таймер vfsbot-backup.timer (00:30 UTC) — дамп в личку админа со сводкой здоровья сервера; на локальной машине задача Планировщика «VFSBot Backup Fetch» (00:00 UTC) выкачивает копии (c:\Work\TelegramBotBackupService).

Секреты — в .env (не в репозитории): BOT_TOKEN, CHAT_ID, ADMIN_CHAT_ID, ID тем.

Стек

Python 3.10+ · aiogram 3 · SQLite · matplotlib · paramiko (деплой).

Грабли Bot API, о которых стоит помнить

• Список тем форума получить нельзя — ID узнаются из сообщений (src/topic_logger.py пишет их в лог).
• Создание/правка тем жёстко рейт-лимитится (~10 подряд) — все скрипты обрабатывают 429 с retry_after.
• Право писать в личку подавшему заявку — разовое: до первого сообщения пользователя боту кнопки в DM должны быть deep-link'ами (?start=...), а не callback'ами.
• Иконки тем — только из бесплатного набора getForumTopicIconStickers.