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+

Установка

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.