🚗 Ямоборец

Интеллектуальная система автоматического обнаружения и анализа дорожных дефектов

---

📋 О проекте

Ямоборец — современная интеллектуальная система для автоматического обнаружения и анализа дорожных дефектов с использованием компьютерного зрения и передовых веб-технологий.

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

Полная документация проекта доступна по ссылке:
https://decodemax.yonote.ru/share/da62cda2-7468-4b95-8b6d-3d14f37f1852

---

🏗️ Архитектура системы

Backend Stack 🖥️

Технология	Описание
FastAPI	Высокопроизводительный асинхронный API фреймворк
PostgreSQL	Реляционная база данных для хранения информации о дефектах
S3 VK Cloud	Облачное хранилище для медиафайлов и изображений
MailRu API	Интеграция с почтовыми сервисами для уведомлений
GigaChat API	AI-ассистент для интеллектуальной обработки данных
Docker	Контейнеризация для простого развертывания

Frontend Stack 🌐

Технология	Описание
React	Современная библиотека для построения пользовательских интерфейсов
Vue.js	Прогрессивный JavaScript фреймворк
MaxUI	Библиотека React-компонентов для создания мини-приложений в MAX
Element-plus	Библиотека компонентов на основе Vue 3 для дизайнеров и разработчиков
reactuse	Cамая большая и полезная библиотека хуков
VK Карты	Используются для отображения карт в приложениях

Computer Vision 👁️

Технология	Описание
Ultralytics YOLO11	Современная нейросетевая модель для детекции дорожных дефектов

---

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

Перед началом работы убедитесь, что у вас установлено:

• ✅ Docker и Docker Compose
• ✅ Python 3.10+ (для локального запуска без Docker)
• ✅ NODE.JS (для локального запуска без Docker)
• ✅ Доступ к следующим API сервисам:
  • GigaChat API
  • MailRu SMTP
  • S3 VK Cloud
  • Telegram Bot API
  • Dadata API
  • VK API Карты
• ✅ Настроенная база данных PostgreSQL (локальная или в Docker)

---

⚡ Быстрый старт

Шаг 1: Загрузка модели компьютерного зрения

Скачайте предобученную модель YOLO11 для распознавания дорожных ям:

🔗 Скачать модель с Яндекс.Диска

После загрузки поместите файл модели в папку cv_models проекта.

Шаг 2: Клонирование репозитория

git clone https://github.com/Timsidorin/MAX_assistant
cd MAX_assistant

Шаг 3: Настройка переменных окружения

Создайте файл .env в корне проекта на основе .env.example:

cp .env.example .env

Заполните все необходимые переменные окружения:

🤖 Настройки MAX Bot

Переменная	Описание	Пример значения
TOKEN_BOT	Токен MAX бота	1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
WEBAPP_URL	URL веб-приложения	https://your-domain.com

🔗 Интеграции API

Переменная	Описание	Пример значения
DADATA_API_KEY	API ключ сервиса Dadata	your_dadata_api_key_here
GIGACHAT_CREDENTIALS	Ключ авторизации GigaChat	your_gigachat_auth_key_here

📧 Настройки почты (Mail.ru)

Переменная	Описание	Пример значения
MAILRU_SMTP_USER	Логин SMTP Mail.ru	your_email@mail.ru
MAILRU_SMTP_PASSWORD	Пароль SMTP Mail.ru	your_smtp_password

🗄️ Конфигурация базы данных

Переменная	Описание	Пример значения
DB_USER	Имя пользователя БД	postgres
DB_NAME	Название базы данных	yamoborets
DB_PASS	Пароль БД	your_secure_password
DB_HOST	Хост БД	db (для Docker) или localhost
DB_PORT	Порт БД	5432

☁️ S3 хранилище (VK Cloud)

Переменная	Описание	Пример значения
AWS_ACCESS_KEY_ID	Access Key для S3	your_access_key
AWS_SECRET_ACCESS_KEY	Secret Key для S3	your_secret_key
S3_BUCKET_NAME	Имя S3 bucket	yamoborets-storage
S3_ENDPOINT_URL	URL эндпоинта S3	https://hb.vkcs.cloud
S3_REGION_NAME	Регион S3	ru-msk

☁️ VK API Краты

Переменная	Описание	Пример значения
VITE_VK_MAP_API	Access Key для S3	12c9338158d1ea82f27ee9697b4b9ae5c3dc7e411594c3fd39f160e37af8ddb2

Шаг 4: Запуск через Docker (рекомендуется)

docker-compose up -d --build

После успешного запуска:

• ✅ API будет доступен по адресу: http://localhost:8005
• ✅ MAX бот начнет работу автоматически
• ✅ База данных будет инициализирована

Шаг 5: Локальный запуск без Docker (опционально)

Для разработки можно запустить проект локально:

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

Linux / macOS:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
venv\Scripts\activate

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

pip install -r requirements.txt

Применение миграций базы данных

alembic upgrade head

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

python api/main.py

Запуск Клиентов

cd mini_app && npm install && npm run dev

cd web_camera && npm install && npm run dev

Шаг 6: Проверка работоспособности

1. Откройте Telegram и найдите вашего бота
2. Отправьте команду /start
3. Загрузите фотографию с дорожной ямой
4. Проверьте результаты:
   • ✅ Дефект распознан моделью YOLO11
   • ✅ Данные сохранены в PostgreSQL
   • ✅ Изображение загружено в S3 VK Cloud
   • ✅ Уведомление отправлено (при настроенной почте)

---

🔧 Разработка

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

📁 backend/
    ├── 
    ├── 📁 alembic/
    ├── 📁 core/
    │   ├── 📄 config.py
    │   ├── 📄 create_base_app.py
    │   └── 📄 database.py
    ├── 📁 cv_models/
    │   ├── 📄 best.pt
    │   └── 📄 ПРОЧИТАТЬ!
    ├── 📁 models/
    │   ├── 📄 report_model.py
    │   └── 📄 users_model.py
    ├── 📁 repositories/
    │   ├── 📄 ReportRepository.py
    │   └── 📄 user_repository.py
    ├── 📁 routers/
    │   ├── 📄 cv_router.py
    │   ├── 📄 reports_router.py
    │   └── 📄 users_router.py
    ├── 📁 schemas/
    │   ├── 📄 cv_schema.py
    │   ├── 📄 report_schema.py
    │   └── 📄 users_schema.py
    ├── 📁 services/
    │   ├── 📁 external_services/
    │   │   ├── 📄 email_service.py
    │   │   ├── 📄 geo_service.py
    │   │   ├── 📄 gigachat_service.py
    │   │   └── 📄 s3_service.py
    │   ├── 📄 ai_agent_service.py
    │   ├── 📄 document_service.py
    │   ├── 📄 pothole_detection_service.py
    │   ├── 📄 report_service.py
    │   └── 📄 users_service.py
    ├── 📁 sql/
    │   ├── 📄 report.sql
    │   └── 📄 users.sql
    ├── 📄 Dockerfile
    ├── 📄 bot.py
    ├── 📄 depends.py
    ├── 📄 main.py
    └── 📄 requirements.txt
📄 docker-compose.yaml
📁 max_bot/
📁 mini_app/
📁 web_camera/
📄 Шаблон заявления.docx

📞 Контакты и поддержка

• GitHub: https://github.com/Timsidorin/MAX_assistant
• Документация: https://decodemax.yonote.ru/share/da62cda2-7468-4b95-8b6d-3d14f37f1852

---

Сделано с ❤️ командой разработчиков Ямоборец

Делаем дороги безопаснее с помощью AI!