sibuti/transport/README.md

🚗 Система мониторинга транспорта

Веб-система для мониторинга местоположения транспортных средств в реальном времени.

🛠 Технологии

• Backend: FastAPI, SQLAlchemy, PostgreSQL
• Frontend: Vue 3, Leaflet, Naive UI
• Инфраструктура: Docker, Nginx

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

Требования

• Docker 20.10+
• Docker Compose 2.0+

Запуск (пошагово)

# 1. Перейти в папку проекта
cd transport

# 2. Собрать и запустить все сервисы
docker-compose up --build -d

# 3. Проверить что все сервисы запущены
docker-compose ps

# Должно быть 4 сервиса в статусе "Up":
#   - transport-nginx-1
#   - transport-backend-1
#   - transport-frontend-1
#   - transport-postgres-1

# 4. Проверить что API работает
curl http://localhost/api/vehicles

# Должен вернуть JSON со списком транспорта

# 5. Открыть приложение в браузере
open http://localhost

Запуск симулятора

В отдельном терминале запустить симулятор данных:

docker-compose exec backend python -m simulator.run

Симулятор будет:

• Генерировать координаты для 5 транспортных средств
• Отправлять данные каждые 2 секунды
• Имитировать движение, остановки, изменение скорости

Для остановки: Ctrl+C

Доступ

Сервис	URL
Приложение	http://localhost
API	http://localhost/api/
API Docs (Swagger)	http://localhost/api/docs
WebSocket	ws://localhost/ws/positions

🔧 Полезные команды

# Посмотреть логи всех сервисов
docker-compose logs -f

# Посмотреть логи только backend
docker-compose logs -f backend

# Перезапустить сервис
docker-compose restart backend

# Остановить все сервисы
docker-compose down

# Остановить и удалить данные (включая БД)
docker-compose down -v

# Пересобрать конкретный сервис
docker-compose up --build backend -d

📡 Работа с API

Создать транспорт

curl -X POST http://localhost/api/vehicles \
  -H "Content-Type: application/json" \
  -d '{"name": "Автобус А-999", "type": "bus"}'

Отправить позицию

curl -X POST http://localhost/api/ingest/position \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": 1,
    "lat": 55.0304,
    "lon": 82.9204,
    "speed": 45.5,
    "heading": 180
  }'

Получить список транспорта

curl http://localhost/api/vehicles

Получить историю позиций

curl "http://localhost/api/vehicles/1/positions?from=2025-12-18T00:00:00"

Получить события

curl http://localhost/api/events

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

transport/
├── docker-compose.yml      # Конфигурация Docker
├── nginx/                  # Nginx конфигурация
│   ├── nginx.conf
│   └── conf.d/default.conf
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── app/               # FastAPI приложение
│   │   ├── main.py        # Точка входа
│   │   ├── models/        # SQLAlchemy модели
│   │   ├── schemas/       # Pydantic схемы
│   │   ├── routers/       # API эндпоинты
│   │   └── services/      # Бизнес-логика
│   ├── alembic/           # Миграции БД
│   └── simulator/         # Симулятор данных
│       └── run.py
└── frontend/
    ├── Dockerfile
    ├── package.json
    └── src/
        ├── main.js
        ├── App.vue        # Главный компонент
        └── components/    # Vue компоненты
            ├── MapView.vue
            ├── VehicleList.vue
            ├── VehicleCard.vue
            ├── TrackHistory.vue
            └── EventFeed.vue

🔌 REST API

Метод	URL	Описание
GET	/api/vehicles	Список транспорта с последними позициями
GET	/api/vehicles/{id}	Информация о конкретном ТС
POST	/api/vehicles	Создать новое ТС
PUT	/api/vehicles/{id}	Обновить ТС
DELETE	/api/vehicles/{id}	Удалить ТС
GET	/api/vehicles/{id}/positions	История позиций ТС
POST	/api/ingest/position	Принять новую позицию
GET	/api/events	Список событий

Типы транспорта

type	Иконка
bus	🚌
truck	🚚
car	🚗

📨 WebSocket API

Подключение: ws://localhost/ws/positions

Формат сообщений

Обновление позиции:

{
  "type": "position_update",
  "data": {
    "vehicle_id": 1,
    "lat": 55.0304,
    "lon": 82.9204,
    "speed": 45.5,
    "heading": 180,
    "timestamp": "2025-12-18T12:00:00Z"
  }
}

Событие:

{
  "type": "event",
  "data": {
    "id": 1,
    "vehicle_id": 1,
    "type": "OVERSPEED",
    "payload": {"speed": 95, "limit": 60},
    "timestamp": "2025-12-18T12:00:00Z"
  }
}

Типы событий

Тип	Описание
OVERSPEED	Превышение скорости (> 60 км/ч)
LONG_STOP	Остановка более 5 минут
CONNECTION_LOST	Нет данных более 5 минут

🐛 Troubleshooting

API возвращает 404

# Проверить что backend запущен
docker-compose ps

# Перезапустить nginx
docker-compose restart nginx

Нет данных на карте

# Проверить что симулятор запущен
docker-compose exec backend python -m simulator.run

# Проверить логи backend
docker-compose logs -f backend

Ошибка подключения к БД

# Проверить что postgres запущен
docker-compose ps postgres

# Посмотреть логи postgres
docker-compose logs postgres

📝 Лицензия

MIT