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

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

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![Aiogram](https://img.shields.io/badge/Aiogram-3.0.0-green.svg)](https://aiogram.dev/)
[![MoviePy](https://img.shields.io/badge/MoviePy-1.0.3-red.svg)](https://moviepy.readthedocs.io/)
[![Bot](https://img.shields.io/badge/Telegram-@MosPoly__Helperbot-blue.svg)](https://t.me/MosPoly_Helperbot)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 📋 Описание

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

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

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

- 🗺️ **Интерактивная навигация** по 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. **Клонирование репозитория**
```bash
git clone https://github.com/EDeev/mospoly-helper.git
cd mospoly-helper
```

2. **Установка Python-зависимостей**
```bash
pip install -r requirements.txt
```

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

**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install ffmpeg
```

**macOS (с Homebrew):**
```bash
brew install ffmpeg
```

**Windows:**
Скачайте с [официального сайта](https://ffmpeg.org/download.html) и добавьте в PATH

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

1. **Создание Telegram бота**
   - Перейдите к [@BotFather](https://t.me/BotFather)
   - Создайте нового бота командой `/newbot`
   - Сохраните полученный токен

2. **Настройка конфигурации**
```python
# config.py
BOT_TOKEN = "YOUR_BOT_TOKEN_HERE"  # Замените на ваш токен
```

3. **Создание структуры каталогов**
```bash
mkdir -p data/{cache,users,videos/{av,bs,mi,pk,pr}/{buildings,floors,offices}}
mkdir -p logs
```

### 🚀 Запуск

**Основной режим:**
```bash
cd src/code
python bot.py
```

**С логированием:**
```bash
python bot.py 2>&1 | tee ../../logs/bot.log
```

**Предварительная генерация кеша (опционально):**
```bash
python combine.py  # Генерирует кеш для всех доступных маршрутов
```

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

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

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

```python
# Параметры кодирования (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`) — от входа в корпус

**Алгоритм проверки кеша:**
```python
# Проверка существования готового файла
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 — Пакетная генерация кеша

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

```python
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])
```

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

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

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

| Участник | Роль | Вклад | Контакты |
|----------|------|-------|----------|
| **[Деев Егор Викторович](https://github.com/EDeev)** | Tech Lead & Backend Developer | Архитектура системы, обработка видео, оптимизация производительности | [@EDeev](https://t.me/EDeev) |
| **[Сапрыкин Пётр Иванович](https://github.com/PetrSaprykin)** | Frontend & UX Developer | Пользовательский интерфейс, логика взаимодействия, тестирование | [@PetrSaprykin](https://github.com/PetrSaprykin) |
| **[Старков Руслан Владимирович](https://github.com/RayStar-k)** | DevOps & QA Engineer | Развертывание, мониторинг, обеспечение качества | [@RayStar-k](https://github.com/RayStar-k) |

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

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

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

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

1. **📧 Email**: [support@new-devs.ru](mailto:support@new-devs.ru)
   - Время ответа: 24-48 часов
   - Для технических вопросов и предложений

2. **🐙 GitHub Issues**: [Создать issue](https://github.com/EDeev/mospoly-helper/issues)
   - Для сообщений об ошибках и feature requests
   - Публичное обсуждение и tracking

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

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

---

<div align="center">

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

[![GitHub](https://img.shields.io/github/stars/EDeev/mospoly-helper?style=social)](https://github.com/EDeev/mospoly-helper)
[![Telegram](https://img.shields.io/badge/Попробовать-@MosPoly__Helperbot-blue)](https://t.me/MosPoly_Helperbot)

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

</div>