🚗 NVK-Driver

Автоматизированная платформа для студенческого трансфера НВК

---

📋 Содержание

• Суть проекта
• Проблематика
• Наше решение
• Функциональные возможности
• Технологический стек
• Быстрый старт
• GitHub Actions & Автоматизация
• Команды бота
• Команда проекта
• Метрики успеха

---

🎯 Суть проекта

Студенты, проживающие в общежитиях НВК, ежедневно сталкиваются с необходимостью добираться до учебных корпусов. В общежитии существует Telegram-группа "Трансфер НВК", где студенты-водители предлагают подвезти других студентов за 150 рублей — это в 5 раз дешевле такси и значительно быстрее автобусов с пересадками.

Однако текущая система работает крайне неэффективно и создает множество проблем в коммуникации между водителями и пассажирами.

---

❌ Проблематика

1. Хаотичная коммуникация и потеря времени

Основная проблема — неструктурированная коммуникация:

• ❌ Группа "Трансфер НВК" сильно засорена сообщениями от множества водителей
• ❌ Невозможно быстро найти поездку на нужное время из-за потока сообщений
• ❌ Приходится вручную писать каждому водителю в личные сообщения
• ❌ Нужно уточнять у каждого: актуальна ли поездка? остались ли свободные места?
• ❌ Отсутствует автоматизация и структурирование информации
• ❌ Пассажиры тратят 15-30 минут только на поиск подходящей поездки

Последствия:

• Студенты теряют драгоценное время на организацию поездки
• Неэффективное использование ресурсов (водители едут полупустыми)
• Потенциальные пассажиры отказываются от системы из-за сложности
• Водители не могут эффективно набрать пассажиров

2. Отсутствие прозрачности и контроля

• ❌ Нет видимости количества свободных мест в реальном времени
• ❌ Водители не могут эффективно управлять бронированиями
• ❌ Часто возникают ситуации двойного бронирования
• ❌ Невозможно отследить историю своих поездок
• ❌ Нет механизма автоматического удаления устаревших объявлений

3. Высокий барьер входа

• ❌ Сложность использования текущей системы отпугивает новых пользователей
• ❌ Студенты предпочитают переплачивать за такси или тратить время на автобусы
• ❌ Низкая вовлеченность ограничивает количество доступных поездок

---

✅ Наше решение

Telegram Mini App "NVK-Driver" — автоматизированная платформа для студенческого трансфера, которая полностью решает проблемы коммуникации и автоматизирует процесс поиска попутчиков.

Решение проблемы коммуникации:

• ✅ Структурированная система анкет вместо хаотичного чата
• ✅ Автоматическое управление доступностью мест
• ✅ Мгновенное бронирование без необходимости писать водителю
• ✅ Фильтры поиска по дате, времени и маршруту
• ✅ Автоматические уведомления для всех участников

Решение проблемы времени:

• ✅ Поиск подходящей поездки: 30 секунд вместо 15-30 минут
• ✅ Бронирование в одно нажатие без переписок
• ✅ За счет удобства → больше пользователей → больше поездок → меньше время ожидания
• ✅ Автоматическое удаление устаревших поездок

---

🚀 Функциональные возможности

Для водителей:

📝 Создание анкеты поездки (2 минуты):

• Имя водителя
• Свободное текстовое поле для описания маршрута
• Дата и время отправления (с защитой от выбора прошлых дат)
• Количество свободных мест (1-8)
• Стоимость поездки
• Информация о машине (марка, цвет, номер)
• Telegram-контакт (автозаполнение)
• Геолокация водителя (опционально, с интеграцией Яндекс.Карт)
• Дополнительное описание (место встречи, особые условия)

🎯 Управление поездками:

• ✅ Автоматическое уменьшение мест при бронировании
• ✅ Просмотр всех заявок от пассажиров
• ✅ Telegram-уведомления о новых бронированиях с контактами пассажира
• ✅ Завершение поездки одной кнопкой
• ✅ Видимость своих поездок даже при заполненности всех мест
• ✅ Автоматическое удаление поездки через 20 минут после времени отправления

Для пассажиров:

🔍 Поиск и бронирование:

• ✅ Удобный список доступных поездок
• ✅ Фильтры по дате, времени и маршруту
• ✅ Просмотр деталей: водитель, машина, цена, геолокация, описание
• ✅ Мгновенное бронирование свободных мест
• ✅ Автоматическое уведомление водителя о бронировании

📋 Управление бронированиями:

• ✅ Раздел "Мои бронирования" с полной информацией
• ✅ Прямая ссылка на Telegram водителя
• ✅ Просмотр геолокации водителя на Яндекс.Картах
• ✅ Отмена бронирования (место автоматически освобождается)
• ✅ Уведомления при отмене поездки водителем

Автоматизация:

🤖 Умное управление:

• ⚡ Автоматическое скрытие заполненных поездок от пассажиров
• ⚡ Водитель продолжает видеть свои поездки для управления
• ⚡ Автоматическое удаление через 20 минут после отправления
• ⚡ Проверка и очистка каждые 5 минут
• ⚡ Автоматические Telegram-уведомления всем участникам при изменениях

🔄 Надежность:

• ✅ Мониторинг работоспособности через UptimeRobot
• ✅ Постоянная доступность (сервис не "засыпает")
• ✅ Health check endpoint для проверки статуса
• ✅ Автоматический деплой при обновлениях

---

💬 Telegram-интеграция

Команды бота:

/start      - 🚀 Запуск приложения с приветствием
/help       - 📖 Подробная инструкция по использованию
/myrides    - 🚗 Просмотр своих поездок (для водителей)
/mybookings - 🎫 Просмотр бронирований (для пассажиров)
/about      - ℹ️ Информация о сервисе

Удобная клавиатура:

• 🚀 Открыть приложение - запуск WebApp
• 📖 Помощь - справка
• ℹ️ О сервисе - информация

---

🎨 Интерфейс

• 🌟 Современный неоновый киберпанк-дизайн с анимациями
• 📱 Интуитивно понятная навигация
• 💫 Адаптивная верстка для всех устройств
• ⚡ Быстрые переходы между разделами
• 🔔 Popup-уведомления для обратной связи

---

🛠 Технологический стек

Frontend:

• HTML5, CSS3, JavaScript (Vanilla)
• Telegram WebApp API
• Адаптивная верстка (Mobile-first)

Backend:

• Node.js v24.11.0
• Express.js 4.18.2 (веб-сервер)
• node-telegram-bot-api 0.64.0 (интеграция с Telegram)
• dotenv (управление конфигурацией)

База данных:

• JSON-файлы с автоматическим созданием и управлением
• Простая структура:
  rides[]
  и
  bookings[]

Инфраструктура:

• Git + GitHub для version control
• Render.com для хостинга и автодеплоя
• UptimeRobot для мониторинга доступности (uptime ≥ 99%)

Интеграции:

• Яндекс.Карты для отображения геолокации
• Telegram Bot API для уведомлений и команд

---

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

Для пользователей:

1. Откройте Telegram и найдите бота: @nvk_driver_bot
2. Нажмите
   /start
3. Выберите роль: Водитель или Пассажир
4. Начните пользоваться! 🎉

Для разработчиков:

Требования:

• Node.js ≥ 14.0.0
• Telegram Bot Token (получить у @BotFather)

Установка:

Переменные окружения:

Деплой на Render:

Подробные инструкции в файле DEPLOY.md

Локальная разработка:

Инструкции по настройке окружения в файле SETUP.md

---

📊 Метрики успеха

Количественные показатели:

📈 Приживаемость продукта:

• Daily Active Users (DAU): ≥ 100 пользователей/день
• Конверсия из группы "Трансфер НВК": ≥ 80% в первые 2 месяца
• Retention rate: ≥ 60% через месяц

📊 Активность:

• Созданных поездок в день: ≥ 20
• Бронирований в день: ≥ 50
• Время от создания до первого бронирования: < 10 минут

⏱️ Эффективность:

• Время поиска поездки: < 1 минуты (vs 15-30 минут ранее)
• Заполненность поездок: ≥ 70%
• Технических отмен: < 5%

Качественные показатели:

✅ Все функции работают стабильно
✅ Uptime ≥ 99%
✅ Положительные отзывы пользователей
✅ NPS (Net Promoter Score) ≥ 50
✅ Группа "Трансфер НВК" практически не используется

---

👥 Команда проекта

Руководитель проекта:

• Иван (@DickUpRio) - автор идеи, product owner

Команда разработки:

• Егор, Кристина, Кристина, Аркадий

Поддержка:

• Telegram: @DickUpRio
• Email: support@nvk-driver (coming soon)

---

🎯 Целевая аудитория

Основные пользователи:

• 👥 Студенты НВК, проживающие в общежитиях
• 🎓 Регулярно совершающие поездки на учебные корпуса (ГУК и др.)
• 👶 Возраст: 18-25 лет
• 📱 Высокий уровень технологической грамотности

Распределение:

• 🚗 Водители: 20-30% аудитории
• 👤 Пассажиры: 70-80% аудитории

Размер рынка:

• Потенциальная аудитория: ~500-1000 студентов НВК
• Текущие пользователи группы: ~200-300 человек
• Целевая конверсия: 100% текущих + новые пользователи

---

📅 Дорожная карта

✅ Этап 1: Предпроектный (Завершен)

• Анализ проблемы и целевой аудитории
• Определение функциональных требований
• Утверждение концепции

✅ Этап 2: MVP (Завершен)

• Детальное планирование архитектуры
• Базовые функции: создание/просмотр/бронирование
• Telegram-интеграция (бот + WebApp)

✅ Этап 3: Разработка (Завершен)

• Полный функционал для водителей и пассажиров
• Автоматизация управления
• Система уведомлений
• Адаптивный интерфейс
• Интеграция с Яндекс.Картами
• Деплой на Render.com
• Мониторинг через UptimeRobot

🔄 Этап 4: Запуск (Текущий)

• Пилотное тестирование с первыми пользователями
• Сбор обратной связи и доработка
• Масштабирование на всю аудиторию НВК
• Информационная кампания

📋 Этап 5: Пост-релизная поддержка (Запланировано)

• Мониторинг метрик использования
• Оперативное исправление багов
• Внедрение новых функций по запросам
• Регулярные обновления

---

🔒 Безопасность и приватность

• 🔐 Все данные хранятся локально на сервере
• 🚫 Не собираем лишнюю информацию о пользователях
• ✅ Используем только публичную информацию из Telegram
• 🔒 Безопасное соединение через HTTPS
• 📝 Автоматическое удаление устаревших данных

---

📈 Преимущества

Для пассажиров:

• ⚡ Экономия времени: 15-30 минут → 30 секунд
• 💰 Экономия денег: 150₽ вместо 750₽ на такси
• 🎯 Удобство: интуитивный поиск и бронирование
• 📍 Прозрачность: видно все детали поездки
• 🔔 Уведомления: никогда не пропустите важное

Для водителей:

• 👥 Больше пассажиров: автоматизация привлекает больше людей
• ⚙️ Автоматизация: не нужно отвечать на однотипные вопросы
• 📊 Контроль: видите все заявки в одном месте
• 💰 Оптимизация расходов: заполняете все места
• 🎯 Простота: создание поездки за 2 минуты

Для всех:

• 🌐 Сетевой эффект: чем больше пользователей, тем ценнее сервис
• 🚀 Постоянное развитие: учитываем фидбэк и добавляем функции
• 💪 Надежность: uptime ≥ 99%, круглосуточная работа
• 🆓 Бесплатно: нет комиссий и скрытых платежей

---

🤝 Вклад в проект

Мы открыты для предложений и улучшений!

Как помочь:

1. 🐛 Нашли баг? Создайте Issue
2. 💡 Есть идея? Напишите нам: @DickUpRio
3. 🔧 Хотите доработать код? Создайте Pull Request
4. 📣 Расскажите о проекте друзьям!

Guidelines:

• Следуйте существующему стилю кода
• Добавляйте комментарии к сложным частям
• Тестируйте изменения перед коммитом
• Описывайте изменения в коммит-сообщениях

---

🔧 GitVerse CI/CD

Проект использует GitVerse CI/CD для автоматизации разработки и деплоя. Конфигурация в файле .gitlab-ci.yml.

Pipeline Stages

lint → test → build → deploy → monitoring

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

Автоматизация

✅ Проверка кода - синтаксис, секреты, структура
✅ Сборка Docker - автоматическая сборка образов
✅ Деплой - staging автоматически, production по подтверждению
✅ Мониторинг - health checks после деплоя
✅ Scheduled jobs - бэкапы и статистика по расписанию
✅ Artifacts - сохранение отчетов (90 дней) и бэкапов (30 дней)

📚 Подробная документация: docs/GITVERSE_CICD.md

---

⚙️ GitHub Actions & Автоматизация

Проект также использует GitHub Actions для дополнительной автоматизации:

🧪 CI - Code Quality Check

Что делает:

• ✅ Проверяет синтаксис JavaScript файлов
• 📊 Генерирует статистику кода
• 🔐 Проверяет на случайно закоммиченные секреты
• 📝 Валидирует структуру проекта

Триггеры:

• Push в ветки main/develop
• Pull Request в main/develop

Практическая ценность:

• Предотвращает попадание сломанного кода в production
• Обеспечивает качество кода
• Защита от утечки секретов

---

📊 Statistics Report Generator

Что делает:

• 📈 Генерирует еженедельные отчеты о развитии проекта
• 📝 Анализирует активность коммитов и контрибьюторов
• 📁 Собирает статистику по коду (количество файлов, строк)
• 💾 Автоматически коммитит отчеты в папку
  reports/
• 📤 Сохраняет артефакты для загрузки (90 дней хранения)

Расписание: каждый понедельник в 9:00 UTC (

)

Что генерируется:

• reports/stats-YYYY-MM-DD.md
  - еженедельный отчет
• reports/SUMMARY.md
  - сводная статистика за все время
• Артефакты с детальной информацией

Практическая ценность:

• Прозрачность развития проекта
• Мотивация команды через визуализацию прогресса
• История изменений для анализа

---

💾 Database Backup

Что делает:

• 💾 Создает ежедневные резервные копии базы данных
• 🗜️ Сжимает бэкапы в архив (tar.gz)
• 📋 Ведет лог всех бэкапов в
  backups/BACKUP_LOG.md
• 📤 Загружает бэкапы как артефакты GitHub (30 дней хранения)
• 🧹 Автоматически очищает временные файлы

Расписание: ежедневно в 3:00 UTC (

)

Метаданные бэкапа:

• Временная метка
• Commit SHA и ветка
• Информация о триггере

Практическая ценность:

• Защита от потери данных
• Возможность восстановления при сбоях
• Соответствие best practices резервного копирования

---

📦 Artifacts & Reports

Все workflow создают артефакты, доступные для скачивания:

• Statistics Reports - сохраняются 90 дней
• Database Backups - сохраняются 30 дней
• Доступны во вкладке Actions

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

✅ Творческое использование GitHub Actions:

• Не только для проверки кода
• Запуск по расписанию (schedule триggер)
• Обработка данных (генерация отчетов)
• Автоматический коммит результатов
• Триггеры workflow_dispatch для ручного запуска
• Автоматическое создание Issues

✅ Логичность и практическая ценность:

• Мониторинг production среды
• Автоматизация бэкапов
• Прозрачность развития проекта

✅ Документация:

• Каждый workflow задокументирован в README
• Понятное описание назначения
• Примеры использования

📚 Подробная документация: docs/GITHUB_ACTIONS.md

---

📝 Лицензия

Этот проект разработан для студентов НВК и распространяется под лицензией MIT.

---

🔗 Полезные ссылки

• 🤖 Telegram бот: @nvk_driver_bot
• 🌐 Production: nvk-driver.onrender.com
• 💻 GitHub: github.com/stevankzt/nvk-driver
• 📖 Документация: DEPLOY.md, SETUP.md
• 💬 Поддержка: @DickUpRio

---

❓ FAQ

Q: Это бесплатно?
A: Да! Использование приложения полностью бесплатно. Вы платите только водителю за поездку (обычно 150₽).

Q: Нужно ли регистрироваться?
A: Нет! Приложение использует ваш Telegram-аккаунт для авторизации.

Q: Что делать, если водитель не приехал?
A: Свяжитесь с водителем через Telegram (ссылка есть в бронировании). Если не отвечает — отмените бронирование и выберите другую поездку.

Q: Можно ли создать несколько поездок одновременно?
A: Да! Вы можете создать сколько угодно поездок. Все они будут отображаться в разделе "Мои поездки".

Q: Как долго хранятся данные о поездках?
A: Поездки автоматически удаляются через 20 минут после времени отправления.

Q: Можно ли изменить поездку после создания?
A: Пока нет. Вы можете завершить текущую поездку и создать новую с обновленными данными.

---

🎉 Благодарности

Спасибо всем, кто помогал в создании проекта:

• 🎓 Преподавателям за менторство и советы
• 👥 Студентам НВК за фидбэк и тестирование
• 💻 Open Source сообществу за инструменты и библиотеки
• 🤝 Команде разработки за упорную работу

---

📞 Контакты

Есть вопросы или предложения?

• 📱 Telegram: @DickUpRio
• 🤖 Бот: @nvk_driver_bot
• 💻 GitHub Issues: github.com/stevankzt/nvk-driver/issues

---