diff --git a/README.md b/README.md index 98278b8..796aba3 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,318 @@ -# Проектная (учебная) практика +# МосПолиХелпер 🎓 -## Участники +**Телеграм-бот для навигации по кампусам Московского Политехнического Университета** -| ФИО | Учебная группа | Код направления подготовки | Профиль образовательной программы | -|-|-|-|-| -| Деев Егор Викторович | 241-327 | 09.03.01 | Системная и программная инженерия | -| Сапрыкин Пётр Иванович | 241-327 | 09.03.01 | Системная и программная инженерия | -| Старков Руслан Владимирович | 241-327 | 09.03.01 | Системная и программная инженерия | +[![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) -## Задание +## 📋 Описание -Задание размещено в папке **task** в файле [README.md](task/README.md). +МосПолиХелпер — это практическое решение реальной проблемы ориентирования в кампусах Московского Политехнического Университета. Бот разработан студентами для студентов и предоставляет интерактивные видео-маршруты до любого кабинета в пяти основных кампусах университета. -## Вариативная часть задания +Проект создан в рамках проектной практики и демонстрирует применение современных технологий для решения повседневных задач студенческой жизни. -**Практическая реализация технологии: "МосПолиХелпер" - Телеграм-бот навигации по кампусу МосПолитеха** +### ✨ Основные возможности -В рамках вариативной части реализован бот для Telegram, помогающий студентам и преподавателям ориентироваться на территории Московского Политехнического Университета, предоставляя видео-маршруты до нужного кабинета. Проект основан на стеке Python/Aiogram и включает: -- Систему навигации по различным корпусам университета -- Модуль обработки видео с помощью библиотеки MoviePy -- Интерактивный интерфейс на основе Telegram Bot API -- Хранение данных о маршрутах и пользовательских запросах +- 🗺️ **Интерактивная навигация** по 5 кампусам МосПолитеха +- 🎥 **Динамические видео-маршруты** от входа на территорию или от входа в корпус +- ⚡ **Мгновенная отдача** готовых маршрутов благодаря интеллектуальному кешированию +- 📱 **Интуитивный интерфейс** с адаптивными inline-кнопками +- 🔄 **Автоматическая обработка видео** с оптимизацией для Telegram (H.264, битрейт 1500k) +- 🚀 **Высокая производительность** — время отклика менее 5 секунд для кешированных маршрутов +- 📊 **Умная валидация** входных данных с подсказками пользователю -Исходный код проекта размещен в директории [src/code/](src/code/). +### 🏢 Поддерживаемые кампусы -В качестве базового руководства по разработке Telegram-ботов на Python использована статья [How to Create a Telegram Bot using Python](https://www.freecodecamp.org/news/how-to-create-a-telegram-bot-using-python/), которая послужила отправной точкой для реализации более сложного функционала, включающего обработку видео и реализацию интерактивных элементов интерфейса. +| Кампус | Код | Формат номера кабинета | Пример | +|--------|-----|------------------------|---------| +| **Большая Семёновская** | `bs` | [корпус][этаж]-[номер] | `а1-01`, `б2-15` | +| **Павла Корчагина** | `pk` | пк[корпус][этаж][номер] | `пк1201`, `пк2315` | +| **Прянишникова** | `pr` | пр[корпус][этаж][номер] | `пр1101`, `пр2208` | +| **Михалковская** | `mi` | м[корпус][этаж][номер] | `м1205`, `м3110` | +| **Автозаводская** | `av` | ав[корпус][этаж][номер] | `ав2301`, `ав1105` | -## Ответственный по проектной (учебной) практике +> 📝 **Важно**: Указывайте номер кабинета точно в том формате, как он указан в личном кабинете или расписании -Куратор **Баринова Наталья Владимировна** +## 🚀 Быстрый старт -## Проектная деятельность +### Команды бота -Проектная (учебная) практика проводилась в связке с выполнением проекта «**EasyAccess. Браузерное расширение для повышения доступности веб-сайтов**» по дисциплине «Проектная деятельность». +- `/start` — Приветствие и инструкции +- `/help` — Справка по командам +- `/route` — Построить маршрут до кабинета -В рамках проектной (учебной) практики разработан сайт-визитка проекта EasyAccess, размещенный по адресу [easy-access.new-devs.ru](https://easy-access.new-devs.ru). Сайт содержит информацию о проекте, команде разработчиков, ходе выполнения работ и полезные ресурсы. +### Использование -Кураторы **Киреева Галина Ивановна** и **Будылина Евгения Александровна** +1. Запустите бота командой `/start` +2. Выберите команду `/route` +3. Укажите кампус из предложенного списка +4. Введите номер кабинета в точном формате +5. Выберите тип маршрута (от территории или от входа в корпус) +6. Получите видео с маршрутом -## Период проведения +## 🛠️ Архитектура и технический стек -С 03 февраля 2025 г. по 24 мая 2025 г. +### 🧩 Технологии -## Структура репозитория +| Компонент | Технология | Версия | Назначение | +|-----------|------------|---------|------------| +| **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 | Управление состояниями пользователей | + +### 🏗️ Модульная архитектура ``` -/ -├── README.md # Основная информация о проекте -├── docs/ # Документация проекта -│ ├── README.md # Основная документация -│ ├── practice_documentation.md # Документация по практике -│ └── ... -├── reports/ # Отчеты по практике -│ ├── README.md # Описание отчетов -│ ├── report.docx # Отчет в формате DOCX -│ ├── report.pdf # Отчет в формате PDF -│ └── practice_report_template.docx # Шаблон отчета -├── site/ # Файлы статического сайта -│ ├── index.html # Главная страница -│ ├── css/ # Стили CSS -│ ├── js/ # JavaScript файлы -│ └── images/ # Изображения -├── src/ # Исходный код проектов -│ ├── code/ # Код телеграм-бота -│ │ ├── bot.py # Основной файл бота -│ │ ├── handlers.py # Обработчики команд -│ │ ├── scripts.py # Вспомогательные скрипты -│ │ └── ... # Прочие модули -├── task/ # Задание на практику -│ ├── README.md # Текст задания -│ ├── git_structure.md # Структура репозитория -│ └── terms.md # Сроки выполнения -└── .gitignore # Файлы, исключенные из репозитория +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 учебный год. + +--- + +
+ +**МосПолиХелпер** — делаем навигацию в университете простой и понятной! 🎓✨ + +[![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) + +*Создано с ❤️ студентами МосПолитеха для студенческого сообщества* + +
\ No newline at end of file diff --git a/practice_README.md b/practice_README.md new file mode 100644 index 0000000..98278b8 --- /dev/null +++ b/practice_README.md @@ -0,0 +1,75 @@ +# Проектная (учебная) практика + +## Участники + +| ФИО | Учебная группа | Код направления подготовки | Профиль образовательной программы | +|-|-|-|-| +| Деев Егор Викторович | 241-327 | 09.03.01 | Системная и программная инженерия | +| Сапрыкин Пётр Иванович | 241-327 | 09.03.01 | Системная и программная инженерия | +| Старков Руслан Владимирович | 241-327 | 09.03.01 | Системная и программная инженерия | + +## Задание + +Задание размещено в папке **task** в файле [README.md](task/README.md). + +## Вариативная часть задания + +**Практическая реализация технологии: "МосПолиХелпер" - Телеграм-бот навигации по кампусу МосПолитеха** + +В рамках вариативной части реализован бот для Telegram, помогающий студентам и преподавателям ориентироваться на территории Московского Политехнического Университета, предоставляя видео-маршруты до нужного кабинета. Проект основан на стеке Python/Aiogram и включает: +- Систему навигации по различным корпусам университета +- Модуль обработки видео с помощью библиотеки MoviePy +- Интерактивный интерфейс на основе Telegram Bot API +- Хранение данных о маршрутах и пользовательских запросах + +Исходный код проекта размещен в директории [src/code/](src/code/). + +В качестве базового руководства по разработке Telegram-ботов на Python использована статья [How to Create a Telegram Bot using Python](https://www.freecodecamp.org/news/how-to-create-a-telegram-bot-using-python/), которая послужила отправной точкой для реализации более сложного функционала, включающего обработку видео и реализацию интерактивных элементов интерфейса. + +## Ответственный по проектной (учебной) практике + +Куратор **Баринова Наталья Владимировна** + +## Проектная деятельность + +Проектная (учебная) практика проводилась в связке с выполнением проекта «**EasyAccess. Браузерное расширение для повышения доступности веб-сайтов**» по дисциплине «Проектная деятельность». + +В рамках проектной (учебной) практики разработан сайт-визитка проекта EasyAccess, размещенный по адресу [easy-access.new-devs.ru](https://easy-access.new-devs.ru). Сайт содержит информацию о проекте, команде разработчиков, ходе выполнения работ и полезные ресурсы. + +Кураторы **Киреева Галина Ивановна** и **Будылина Евгения Александровна** + +## Период проведения + +С 03 февраля 2025 г. по 24 мая 2025 г. + +## Структура репозитория + +``` +/ +├── README.md # Основная информация о проекте +├── docs/ # Документация проекта +│ ├── README.md # Основная документация +│ ├── practice_documentation.md # Документация по практике +│ └── ... +├── reports/ # Отчеты по практике +│ ├── README.md # Описание отчетов +│ ├── report.docx # Отчет в формате DOCX +│ ├── report.pdf # Отчет в формате PDF +│ └── practice_report_template.docx # Шаблон отчета +├── site/ # Файлы статического сайта +│ ├── index.html # Главная страница +│ ├── css/ # Стили CSS +│ ├── js/ # JavaScript файлы +│ └── images/ # Изображения +├── src/ # Исходный код проектов +│ ├── code/ # Код телеграм-бота +│ │ ├── bot.py # Основной файл бота +│ │ ├── handlers.py # Обработчики команд +│ │ ├── scripts.py # Вспомогательные скрипты +│ │ └── ... # Прочие модули +├── task/ # Задание на практику +│ ├── README.md # Текст задания +│ ├── git_structure.md # Структура репозитория +│ └── terms.md # Сроки выполнения +└── .gitignore # Файлы, исключенные из репозитория +```