Profticket To Telegram — бот театральной афиши и аналитики

Русская документация. For English version see README.en.md.

Содержание

• Назначение
• Возможности
• Архитектура
• Требования
• Установка
• Переменные окружения
• Docker
• Тесты и линтинг
• Команды и меню
• Логи
• Вклад
• Дорожная карта
• Лицензия и контакты

Назначение

Telegram‑бот для показа спектаклей/событий из Profticket и оперативной аналитики продаж. Поддерживает персональные фильтры пользователей (по артистам) и админ‑панель с метриками.

Возможности

• Главное меню: выбор месяца, персональный фильтр «👤Выбрать актёра/актрису», переход в «📊 Аналитика».
• Персональные показы: расписание только с участием выбранного артиста.
• Аналитика:
  • 🏆 Топ продаж (спектакли) — валовые/чистые продажи;
  • ⚡️ Топ скорости (спектакли) — текущий темп продаж;
  • ⏳ Прогноз Sold Out — ближайшие sold out;
  • 🎭 Топ продаж (артисты);
  • 📅 Календарь продаж — по датам;
  • 🔄 Топ по возвратам и 📉 Топ по % возвратов.
• Длинные ответы разбиваются на части («чанки») — не упираются в лимиты Telegram.
• Админ‑панель (🛠 Админка):
  • 📈 Статистика — сводка/топы, выбранный артист у пользователей;
  • 👥 Пользователи — активность, роли, топы по запросам/троттлингу;
  • 🎭 Предпочтения — топ выбранных артистов, примеры пользователей, список без выбора;
  • 🗄 База (шоу) — метрики по shows/истории мест, свежесть данных.

Админка доступна ADMIN_ID и пользователям с User.admin=True.

Архитектура

• main.py — запуск, middlewares, фоновое обновление данных.
• telegram/ — хендлеры, клавиатуры, фильтры, middlewares, утилиты.
• services/profticket/ — клиент и аналитика Profticket.
• alembic/ — миграции БД; alembic.ini — конфиг Alembic.
• tests/ — pytest‑тесты для аналитики и утилит.

Требования

• Python 3.11
• PostgreSQL 14+

Источник афиши Ермоловой

Для постоянного прямого выхода через российский сервер без SSH-туннеля подготовлены HTTPS-прокси и инструкция подключения. Бот подключается через docker-compose.mosbilet.yml; собственный сертификат прокси задаётся через MOSBILET_PROXY_CA_FILE и не меняет доверие к сайту.

По умолчанию SCHEDULE_SOURCE=ermolova: расписание и составы берутся с официального сайта театра, остатки билетов — из API «Мосбилета». Для прежнего загрузчика можно явно установить SCHEDULE_SOURCE=profticket.

На сервере вне России для «Мосбилета» может потребоваться российский выход. Настройте MOSBILET_PROXY_URL в .env, например:

SCHEDULE_SOURCE=ermolova
MOSBILET_PROXY_URL=socks5h://127.0.0.1:18080

Для локальной проверки можно использовать SSH SOCKS-туннель к своему российскому серверу, доступному по настроенному SSH alias:

ssh -N -D 127.0.0.1:18080 -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 ru-server

Туннель должен работать всё время, пока используется этот адрес прокси. Для Docker укажите адрес прокси, достижимый из контейнера: 127.0.0.1 внутри контейнера не является loopback хоста. Прокси должен быть закрыт от посторонних клиентов. Поддерживаются HTTP CONNECT и SOCKS5; эта настройка используется только для «Мосбилета», Telegram и сайт театра идут напрямую. Проверка TLS-сертификатов включена. URL прокси с паролем не храните в Git.

Месяцы показываются при наличии расписания, в том числе до начала продаж. Неизвестный остаток ведёт на сайт и не записывается в историю как ноль. Ошибка API, неполный разбор или неподтверждённая пустая афиша сохраняют последний успешный месячный снимок. После трёх ошибок одного месяца администратор получает одно уведомление до следующего успешного обновления.

События нового источника имеют отдельные строковые ID с префиксом ermolova:; ID спектаклей — отрицательные ID страниц театра. История Profticket остаётся под прежними ID и не объединяется с новыми событиями. Миграция БД не нужна: используются существующие nullable-поля. Новая аналитика накапливается после первых успешных снимков; ранее отсутствовавшую историю восстановить нельзя. Состав на сайте может включать нескольких исполнителей одной роли, поэтому персональный фильтр не подтверждает конкретный состав на выбранную дату.

Установка

1. Создайте окружение и установите зависимости:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. Скопируйте .env.example в .env и заполните:

cp .env.example .env

3. (Опционально) Примените миграции:

alembic upgrade head

4. Запустите бота:

python main.py

Переменные окружения

См. .env.example. Минимально нужны: BOT_TOKEN/TEST_BOT_TOKEN, ADMIN_ID, DB_URL, COM_ID, DEFAULT_TIMEZONE. Для запуска в Docker установите IN_DOCKER=true — тогда используется BOT_TOKEN.

Docker

Быстрый старт:

docker-compose up -d

Поднимет Postgres и бот. Проверьте переменные окружения.

Тесты и линтинг

pytest -q
ruff format . && ruff check --fix .

Тесты быстрые, сетевые вызовы замоканы.

Команды и меню

• Нативное меню (см. telegram/keyboards/native_menu.py): /start, /help, /set_actor, /analytics.
• Тексты кнопок — telegram/lexicon/lexicon_ru.py.

Логи

Настраиваются в telegram/utils/startup.py (setup_logging), выводятся в stdout через coloredlogs на уровне INFO.

Вклад

Перед PR проверьте локально:

• ruff format . && ruff check --fix .
• pytest -q
• Соблюдайте Conventional Commits (например: feat(telegram): ...).
• Не включайте секреты в коммиты; используйте .env.

Дорожная карта

• Пагинация в админ‑отчётах и аналитике.
• Экспорт CSV для предпочтений/топов.
• Поиск пользователя (id/username) и быстрая карточка.
• Управление ролями/баном из админ‑меню.

Лицензия и контакты

Лицензия — MIT (см. LICENSE). Вопросы: см. ADMIN_USERNAME в .env.