Telegram-бот для подбора спортивных секций БГУИР с персонализированными рекомендациями на основе анкетирования и машинного обучения. Админ-панель собирает аналитику по откликам и помогает маркетинговой команде работать с данными в реальном времени.
- 1. О проекте
- 2. 🚀 Быстрый старт (5 минут)
- 3. Возможности
- 4. Архитектура
- 5. Разработка
- 6. Документация API
- 7. Тестирование
- 8. Roadmap
Проект объединяет Telegram-бота (Telegraf + TypeScript) и веб-панель администратора (React + Bun.serve). Бот сопровождает абитуриентов, студентов и сотрудников на пути к выбору спортивной секции, а аналитическая панель отображает срезы данных и агрегированные метрики вовлечённости.
Ключевые идеи:
- персонализация рекомендаций через векторную модель с косинусным сходством, учитывающую цели, формат, комфорт по интенсивности, контактность и интерес к соревнованиям;
- единая инфраструктура Bun.serve обслуживает и бота, и REST API для SPA;
- Prisma + PostgreSQL сохраняют анкеты, статистику, сессии пользователей и каталог секций;
- динамическое управление контентом через админ-панель (CRUD секций).
# 1. Клонируйте и установите зависимости
git clone https://github.com/kotru21/bsuir.git
cd bsuir
bun install
Note: after running `bun install` you will have `bun.lockb` in the project root — this is Bun's lockfile. Commit it to the repo to ensure reproducible installs.
# 2. Минимальная конфигурация окружения
Copy-Item .env.example .env
Add-Content .env "BOT_TOKEN=your_token"
Add-Content .env "DATABASE_URL=postgresql://user:pass@localhost:5432/bsuir"
Add-Content .env "ADMIN_JWT_SECRET=change_me_please"
# 3. Запустите разработку (бот + Bun HTTP сервер)
bun run devℹ️ Требуется Bun 1.3+ (см.
package.json→packageManager).
✅ Готово! Подключите бота в Telegram и откройте http://localhost:3000 для проверки живости API.
⚠️ Важно: замените демонстрационные значения в.envперед деплоем и не публикуйте токены в публичных репозиториях.
- интерактивный wizard с шагами: приветствие → возраст → пол → подготовка → комфорт по интенсивности → формат → цели → приоритет целей → контактность → интерес к соревнованиям;
- персонализированные карточки рекомендаций с пояснениями и изображениями;
- AI-пояснение подбора (при наличии Heroku Inference ключа) в дружелюбном тоне;
- команда
/sectionsдля просмотра каталога вне анкеты; - планируется логирование интереса и просмотров для последующей аналитики;
- fallback-сценарии, если подходящих секций не найдено.
- защищённый вход через httpOnly JWT-cookie и double-submit CSRF;
- дашборд KPI: количество анкет, динамика вовлечённости, распределения;
- таблица анкет с фильтрами и раскрытием рекомендаций;
- визуализация статистики через Chart.js (распределения, тренды по времени);
- live-обновление данных напрямую из Bun HTTP API.
Высокоуровневая схема отражает взаимодействие пользователя с ботом и админа с веб-панелью через общее Bun-приложение.
flowchart LR
subgraph Client
TG[Telegram]
Admin[Админ SPA]
end
subgraph Backend[Bun.serve + Telegраф]
Bot[Telegraf Bot]
API[REST API]
Static[Статика Vite]
end
DB[(PostgreSQL)]
Catalog[(sections.ts + images)]
TG --> Bot
Admin --> API
Admin -.-> Static
Bot --> DB
API --> DB
Bot --> Catalog
🔗 Подробные диаграммы, бизнес-процессы и ER-модель вынесены в
docs/ARCHITECTURE.md. Сложные схемы свёрнуты по умолчанию и сопровождаются пояснениями.
- Установите зависимости:
bun install. - Скопируйте
.env.example→.envи заполните ключевые переменные. При необходимости добавьтеINFERENCE_KEY,INFERENCE_MODEL_IDиINFERENCE_URL, чтобы включить AI-пояснение. - Примените схему данных:
bunx prisma migrate deploy. - Запустите сервер и бота:
bun run dev(используетtsx). - Для SPA админки — отдельный
bun run dev:admin(Vite). Для эксперимента можно собрать UI с помощью Bun bundler:
bun run build:admin:bun- Для продовой сборки:
bun run buildупакует серверную часть Bun-бандлером вdist/server.js, после чего запускайтеbun start. Фронтенд по-прежнему собирается через Vite (bun run build:admin).
💡 Подробные сценарии и рекомендации по деплою вынесены в
docs/DEPLOYMENT.md.
src/
├── bot/ # Telegram-бот, сцены, форматтеры, клавиатуры
├── admin/ # Bun HTTP API, роуты, сервисы, статическая раздача
├── services/ # Общая бизнес-логика (рекомендации, запись ответов)
├── data/ # Каталог секций и изображения
├── domain/ # Доменные значения и дефолты профиля
└── infrastructure/ # PrismaClient, инфраструктурные обёртки
admin/web/ # React SPA (Vite, TanStack Query, Chart.js)
prisma/ # schema.prisma и миграции
- Backend: Bun 1+, Telegraf, Bun.serve, Prisma, PostgreSQL.
- Frontend: React 19.2, Vite, TanStack Query, Chart.js.
- Инфраструктура: TypeScript (NodeNext/ESM), tsx, Bun.env, bun:test.
- Автоматизация: Bun scripts (
dev,dev:admin,build,start,test).
Основные эндпойнты расположены под /admin/api:
GET /health— проверка доступности;GET /csrf,POST /login,POST /logout— цикл аутентификации;GET /stats/overview,/stats/demographics,/stats/timeline— статистика;GET /submissions— пагинированный список анкет с рекомендациями.
Полное описание схем запросов и примеры ответов смотрите в docs/API.md.
- Юнит-тесты:
bun run test(bun test runner). - Проверка типов:
bunx tsc --noEmit. - ESLint:
bun run lint. - Ручной сценарий:
/start→ анкета → выдача рекомендаций →/sections→ проверка админ-панели.
💡 Тесты для onboarding-сцен и рекомендаций находятся в
test/.
Краткосрочно (Q4 2025):
- интеграция с CRM для отслеживания лидов;
- поддержка многоязычности интерфейса (RU/EN/BY);
- расширение аналитики: когортный анализ и A/B эксперименты.
Среднесрочно (Q1–Q2 2026):
- динамический каталог секций из внешних источников;
- интеграция оплаты и записи прямо в боте;
- система уведомлений и напоминаний.
Долгосрочно (2026+):
- AI-ассистент по тренировкам;
- нативные мобильные приложения;
- геймификация, рейтинги и челленджи.
💡 Контрибьюторские рекомендации и процессы описаны в
docs/CONTRIBUTING.md.