mirror of
https://github.com/EDeev/mospoly-helper.git
synced 2026-06-15 11:01:14 +03:00
replacing the README
This commit is contained in:
parent
ae4408db02
commit
aa650d149b
2 changed files with 372 additions and 54 deletions
351
README.md
351
README.md
|
|
@ -1,75 +1,318 @@
|
|||
# Проектная (учебная) практика
|
||||
# МосПолиХелпер 🎓
|
||||
|
||||
## Участники
|
||||
**Телеграм-бот для навигации по кампусам Московского Политехнического Университета**
|
||||
|
||||
| ФИО | Учебная группа | Код направления подготовки | Профиль образовательной программы |
|
||||
|-|-|-|-|
|
||||
| Деев Егор Викторович | 241-327 | 09.03.01 | Системная и программная инженерия |
|
||||
| Сапрыкин Пётр Иванович | 241-327 | 09.03.01 | Системная и программная инженерия |
|
||||
| Старков Руслан Владимирович | 241-327 | 09.03.01 | Системная и программная инженерия |
|
||||
[](https://python.org)
|
||||
[](https://aiogram.dev/)
|
||||
[](https://moviepy.readthedocs.io/)
|
||||
[](https://t.me/MosPoly_Helperbot)
|
||||
[](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 учебный год.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**МосПолиХелпер** — делаем навигацию в университете простой и понятной! 🎓✨
|
||||
|
||||
[](https://github.com/EDeev/mospoly-helper)
|
||||
[](https://t.me/MosPoly_Helperbot)
|
||||
|
||||
*Создано с ❤️ студентами МосПолитеха для студенческого сообщества*
|
||||
|
||||
</div>
|
||||
75
practice_README.md
Normal file
75
practice_README.md
Normal file
|
|
@ -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 # Файлы, исключенные из репозитория
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue