МосПолиХелпер 🎓

Телеграм-бот для навигации по кампусам Московского Политехнического Университета

📋 Описание

МосПолиХелпер — это практическое решение реальной проблемы ориентирования в кампусах Московского Политехнического Университета. Бот разработан студентами для студентов и предоставляет интерактивные видео-маршруты до любого кабинета в пяти основных кампусах университета.

Проект создан в рамках проектной практики и демонстрирует применение современных технологий для решения повседневных задач студенческой жизни.

✨ Основные возможности

• 🗺️ Интерактивная навигация по 5 кампусам МосПолитеха
• 🎥 Динамические видео-маршруты от входа на территорию или от входа в корпус
• ⚡ Мгновенная отдача готовых маршрутов благодаря интеллектуальному кешированию
• 📱 Интуитивный интерфейс с адаптивными inline-кнопками
• 🔄 Автоматическая обработка видео с оптимизацией для Telegram (H.264, битрейт 1500k)
• 🚀 Высокая производительность — время отклика менее 5 секунд для кешированных маршрутов
• 📊 Умная валидация входных данных с подсказками пользователю

🏢 Поддерживаемые кампусы

Кампус	Код	Формат номера кабинета	Пример
Большая Семёновская	bs	[корпус][этаж]-[номер]	а1-01, б2-15
Павла Корчагина	pk	пк[корпус][этаж][номер]	пк1201, пк2315
Прянишникова	pr	пр[корпус][этаж][номер]	пр1101, пр2208
Михалковская	mi	м[корпус][этаж][номер]	м1205, м3110
Автозаводская	av	ав[корпус][этаж][номер]	ав2301, ав1105

📝 Важно: Указывайте номер кабинета точно в том формате, как он указан в личном кабинете или расписании

🚀 Быстрый старт

Команды бота

• /start — Приветствие и инструкции
• /help — Справка по командам
• /route — Построить маршрут до кабинета

Использование

1. Запустите бота командой /start
2. Выберите команду /route
3. Укажите кампус из предложенного списка
4. Введите номер кабинета в точном формате
5. Выберите тип маршрута (от территории или от входа в корпус)
6. Получите видео с маршрутом

🛠️ Архитектура и технический стек

🧩 Технологии

Компонент	Технология	Версия	Назначение
Backend	Python	3.10+	Основной язык разработки
Bot Framework	Aiogram	3.0.0	Асинхронная работа с Telegram Bot API
Video Processing	MoviePy	1.0.3	Обработка и монтаж видеофрагментов
Video Encoding	FFmpeg	latest	Кодирование и оптимизация видео
Data Storage	JSON	native	Хранение пользовательских сессий
State Management	MemoryStorage	aiogram	Управление состояниями пользователей

🏗️ Модульная архитектура

src/code/
├── bot.py            # 🚀 Точка входа и координация приложения
├── config.py         # ⚙️  Конфигурационные параметры
├── database.py       # 💾 Управление пользовательскими данными
├── handlers.py       # 🎛️  Обработчики команд и callback'ов
├── init.py           # 🔧 Инициализация компонентов бота
├── scripts.py        # 🎬 Обработка видео и формирование маршрутов
└── combine.py        # 🔄 Утилита для предварительной генерации кеша

Принципы проектирования:

• Single Responsibility — каждый модуль отвечает за конкретную задачу
• Dependency Injection — слабая связанность между компонентами
• Async/Await — асинхронная обработка для высокой производительности
• Error Handling — корректная обработка ошибок на всех уровнях

📁 Структура данных и файловая система

📦 mospoly-helper/
├── 📂 src/code/              # Исходный код
├── 📂 data/                  # Рабочие данные
│   ├── 📂 cache/             # Сгенерированные видеомаршруты
│   │   ├── 📄 *-all.mp4      # Полные маршруты (от территории)
│   │   └── 📄 *-small.mp4    # Короткие маршруты (от входа в корпус)
│   ├── 📂 users/             # JSON-файлы сессий пользователей
│   │   └── 📄 {user_id}.json # Данные конкретного пользователя
│   └── 📂 videos/            # Библиотека исходных видеофрагментов
│       ├── 📂 av/            # Автозаводская
│       │   ├── 📂 buildings/ # Видео от входа до корпуса
│       │   ├── 📂 floors/    # Видео по этажам
│       │   └── 📂 offices/   # Видео до конкретных кабинетов
│       ├── 📂 bs/            # Большая Семёновская
│       ├── 📂 mi/            # Михалковская
│       ├── 📂 pk/            # Павла Корчагина
│       └── 📂 pr/            # Прянишникова
└── 📂 logs/                  # Журналы работы (рекомендуется)

⚡ Установка и настройка

📋 Системные требования

• OS: Linux (Ubuntu 20.04+), macOS, Windows 10+
• Python: 3.10 или выше
• RAM: минимум 2 ГБ (рекомендуется 4 ГБ)
• Storage: минимум 10 ГБ для видеофрагментов и кеша
• Network: стабильное интернет-соединение

🔧 Установка зависимостей

1. Клонирование репозитория

git clone https://github.com/EDeev/mospoly-helper.git
cd mospoly-helper

2. Установка Python-зависимостей

pip install -r requirements.txt

3. Установка FFmpeg

Ubuntu/Debian:

sudo apt update && sudo apt install ffmpeg

macOS (с Homebrew):

brew install ffmpeg

Windows: Скачайте с официального сайта и добавьте в PATH

⚙️ Конфигурация

1. Создание Telegram бота

   • Перейдите к @BotFather
   • Создайте нового бота командой /newbot
   • Сохраните полученный токен

2. Настройка конфигурации

# config.py
BOT_TOKEN = "YOUR_BOT_TOKEN_HERE"  # Замените на ваш токен

3. Создание структуры каталогов

mkdir -p data/{cache,users,videos/{av,bs,mi,pk,pr}/{buildings,floors,offices}}
mkdir -p logs

🚀 Запуск

Основной режим:

cd src/code
python bot.py

С логированием:

python bot.py 2>&1 | tee ../../logs/bot.log

Предварительная генерация кеша (опционально):

python combine.py  # Генерирует кеш для всех доступных маршрутов

🎯 Алгоритмы и оптимизации

🎬 Обработка видео

Система обработки видео использует продвинутые техники оптимизации:

# Параметры кодирования (scripts.py)
full_clip.write_videofile(
    filename,
    fps=30,                    # Оптимальная частота кадров
    codec="libx264",           # Эффективный кодек H.264
    bitrate="1500k",           # Баланс качество/размер
    preset="fast",             # Быстрое кодирование
    ffmpeg_params=["-crf", "23"]  # Constant Rate Factor для качества
)

Применяемые оптимизации:

• ✂️ Удаление аудиодорожки — экономия 30-40% размера файла
• ⏩ Ускорение в 2 раза — сокращение времени просмотра
• 📐 Изменение разрешения до 400px — оптимизация для мобильных устройств
• 🗜️ CRF 23 — оптимальный баланс качества и размера файла

⚡ Система кеширования

Двухуровневое кеширование:

1. Полные маршруты (*-all.mp4) — от входа на территорию
2. Короткие маршруты (*-small.mp4) — от входа в корпус

Алгоритм проверки кеша:

# Проверка существования готового файла
cache_path = f"../data/cache/{route_id}-{'all' if full_route else 'small'}.mp4"
if os.path.exists(cache_path):
    return cache_path  # Мгновенная отдача
else:
    return await make_full_clip(video_segments)  # Генерация нового

📊 Производительность

Метрика	Кешированный маршрут	Новый маршрут
Время отклика	< 3 секунды	15-30 секунд
Размер файла	2-8 МБ	аналогично
Качество видео	400p, 30fps	аналогично
Нагрузка на CPU	минимальная	высокая

🧪 Оптимизации производительности

Компонент	До оптимизации	После оптимизации	Улучшение
Размер видео	15-25 МБ	2-8 МБ	🔻 70%
Время генерации	45-60 сек	15-30 сек	🔻 50%
Время отдачи (кеш)	N/A	< 3 сек	⚡ мгновенно
Использование RAM	200-300 МБ	100-150 МБ	🔻 40%

📦 combine.py — Пакетная генерация кеша

Утилита для предварительной генерации видеомаршрутов:

async def combine_all_videos():
    """
    Массовая генерация кеша для всех доступных маршрутов
    
    Обрабатывает:
    - Все корпуса: pr, pk, mi, av, bs
    - Полные и короткие маршруты для каждого кабинета
    - Пропускает несуществующие видеофрагменты
    """
    corpora = ["pr", "pk", "mi", "av", "bs"]
    
    for corpus in corpora:
        offices_path = f"../videos/{corpus}/offices"
        for video_file in os.listdir(offices_path):
            # Генерация полного маршрута
            await make_full_clip([building_path, floor_path, office_path])
            # Генерация короткого маршрута  
            await make_full_clip([floor_path, office_path])

Использование:

cd src/code
python combine.py  # Запуск в фоновом режиме для больших объемов

👨‍💻 Команда разработки

Проект создан в рамках проектной практики студентами группы 241-327 направления "Системная и программная инженерия":

Участник	Роль	Вклад	Контакты
Деев Егор Викторович	Tech Lead & Backend Developer	Архитектура системы, обработка видео, оптимизация производительности	@EDeev
Сапрыкин Пётр Иванович	Frontend & UX Developer	Пользовательский интерфейс, логика взаимодействия, тестирование	@PetrSaprykin
Старков Руслан Владимирович	DevOps & QA Engineer	Развертывание, мониторинг, обеспечение качества	@RayStar-k

Научное руководство:

• Куратор практики: Баринова Наталья Владимировна
• Кураторы проектной деятельности: Киреева Галина Ивановна, Будылина Евгения Александровна

📞 Поддержка и контакты

🆘 Получение помощи

Официальные каналы поддержки:

1. 📧 Email: support@new-devs.ru

   • Время ответа: 24-48 часов
   • Для технических вопросов и предложений

2. 🐙 GitHub Issues: Создать issue

   • Для сообщений об ошибках и feature requests
   • Публичное обсуждение и tracking

📄 Лицензия и правовая информация

Этот проект создан в учебных целях как работа по дисциплине "Проектной практики" в Московском Политехническом Университете, 2024-2025 учебный год.

---

_{МосПолиХелпер — делаем навигацию в университете простой и понятной! 🎓✨}

_{Создано с ❤️ студентами МосПолитеха для студенческого сообщества}