RunQuest 🏃‍♂️

RunQuest - это инновационное мобильное приложение для бегунов, объединяющее GPS-трекинг, геймификацию и социальные функции. Приложение помогает пользователям отслеживать свои пробежки, участвовать в гонках, выполнять челленджи и взаимодействовать с друзьями.

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

📱 Мобильное приложение (Flutter)

• GPS-трекинг - точное отслеживание маршрутов пробежек
• Интерактивные карты - визуализация маршрутов с использованием Flutter Map
• Геймификация - система уровней, опыта и достижений
• Челленджи - еженедельные и месячные вызовы
• Гонки - участие в предопределенных трассах с лидербордами
• Социальные функции - друзья, лента активности, совместные пробежки
• Статистика - детальная аналитика пробежек и прогресса

🖥️ Backend API (Django REST Framework)

• RESTful API - полный набор эндпоинтов для всех функций
• JWT аутентификация - безопасная система входа
• PostGIS интеграция - работа с геопространственными данными
• Геймификация - система достижений и челленджей
• Социальные функции - управление друзьями и активностью
• Swagger документация - автоматическая документация API

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

Frontend (Flutter)

• Flutter 3.3+ - кроссплатформенная разработка
• Dart - язык программирования
• flutter_map - интерактивные карты
• geolocator - GPS и геолокация
• dio - HTTP клиент для API
• provider - управление состоянием
• flutter_secure_storage - безопасное хранение токенов

Backend (Django)

• Django 4.2+ - веб-фреймворк
• Django REST Framework - API фреймворк
• PostgreSQL + PostGIS - база данных с геопространственными возможностями
• GeoDjango - работа с геоданными
• JWT - аутентификация
• Swagger/ReDoc - документация API

Дополнительные технологии

• Shapely - работа с геометрией
• Pillow - обработка изображений
• CORS - кросс-доменные запросы

📁 Структура проекта

RunQuest/
├── frontend/                 # Flutter приложение
│   ├── lib/
│   │   ├── main.dart        # Точка входа
│   │   ├── models/          # Модели данных
│   │   ├── screens/         # Экраны приложения
│   │   └── services/        # API сервисы
│   ├── static/              # Статические ресурсы
│   └── pubspec.yaml         # Зависимости Flutter
├── backend/                 # Django API
│   ├── backend/             # Настройки Django
│   ├── core/                # Основное приложение
│   │   ├── models.py        # Модели базы данных
│   │   ├── views.py         # API представления
│   │   ├── serializers.py   # Сериализаторы
│   │   └── urls.py          # URL маршруты
│   └── requirements.txt     # Python зависимости
├── Documentation/           # Документация проекта
└── README.md               # Этот файл

🚀 Установка и запуск

Предварительные требования

• Flutter SDK 3.3+
• Python 3.8+
• PostgreSQL 12+ с расширением PostGIS
• Git

Backend (Django API)

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

git clone <repository-url>
cd RunQuest

2. Создание виртуального окружения

cd backend
python -m venv .venv
.venv\Scripts\activate  # Windows
# или
source .venv/bin/activate  # Linux/Mac

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

pip install -r requirements.txt

4. Настройка базы данных

# Создайте базу данных PostgreSQL с PostGIS
# Обновите настройки в backend/settings.py
python manage.py migrate
python manage.py createsuperuser

5. Запуск сервера

python manage.py runserver
# или используйте start_backend.bat

Frontend (Flutter)

1. Установка Flutter зависимостей

cd frontend
flutter pub get

2. Запуск приложения

flutter run
# или используйте start_frontend.bat

📚 API Документация

После запуска backend сервера, документация API доступна по адресам:

• Swagger UI: http://localhost:8000/swagger/
• ReDoc: http://localhost:8000/redoc/

Основные эндпоинты:

• POST /api/register/ - регистрация пользователя
• POST /api/token/ - получение JWT токена
• GET /api/profile/ - профиль пользователя
• POST /api/runs/ - создание пробежки
• GET /api/race-tracks/ - список гонок
• GET /api/achievements/ - достижения
• GET /api/challenges/ - челленджи

🎮 Основные функции

GPS-трекинг

• Точное отслеживание маршрута в реальном времени
• Сохранение геометрии маршрута в PostGIS
• Расчет дистанции и времени

Геймификация

• Система уровней - прогрессия от 1 до 100 уровня
• Опыт - начисление за пробежки, гонки и достижения
• Достижения - разблокировка за различные цели
• Челленджи - еженедельные и месячные вызовы

Социальные функции

• Друзья - система запросов и принятия
• Лента активности - новости от друзей
• Совместные пробежки - планирование групповых тренировок
• Лидерборды - рейтинги по гонкам

Гонки

• Предопределенные трассы - готовые маршруты для гонок
• Сравнение маршрутов - анализ точности прохождения
• Рекорды - лучшие результаты по трассам

🔧 Конфигурация

Backend настройки

Основные настройки находятся в backend/backend/settings.py:

• База данных PostgreSQL
• CORS настройки
• JWT конфигурация
• PostGIS настройки

Frontend настройки

• API базовый URL в сервисах
• Настройки карт в flutter_map
• Тема приложения в main.dart

📱 Скриншоты

Скриншоты приложения будут добавлены в раздел screenshots/

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

1. Форкните репозиторий
2. Создайте ветку для новой функции (git checkout -b feature/AmazingFeature)
3. Зафиксируйте изменения (git commit -m 'Add some AmazingFeature')
4. Отправьте в ветку (git push origin feature/AmazingFeature)
5. Откройте Pull Request

📄 Лицензия

Этот проект создан в образовательных целях как портфолио. Все права защищены.

👨‍💻 Автор

Азиз Мухаммадиев - Разработчик мобильных приложений

• Email: aziztarorazizchikago@gmail.com

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

• Flutter команде за отличный фреймворк
• Django сообществу за мощный веб-фреймворк
• PostGIS проекту за геопространственные возможности
• Всем open-source библиотекам, использованным в проекте

---

RunQuest - где каждая пробежка становится приключением! 🏃‍♂️✨