sibuti/transport/README.md

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

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

## 🛠 Технологии

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

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

### Требования
- Docker 20.10+
- Docker Compose 2.0+

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

```bash
# 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
```

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

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

```bash
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 |

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

```bash
# Посмотреть логи всех сервисов
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

### Создать транспорт
```bash
curl -X POST http://localhost/api/vehicles \
  -H "Content-Type: application/json" \
  -d '{"name": "Автобус А-999", "type": "bus"}'
```

### Отправить позицию
```bash
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
  }'
```

### Получить список транспорта
```bash
curl http://localhost/api/vehicles
```

### Получить историю позиций
```bash
curl "http://localhost/api/vehicles/1/positions?from=2025-12-18T00:00:00"
```

### Получить события
```bash
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`

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

**Обновление позиции:**
```json
{
  "type": "position_update",
  "data": {
    "vehicle_id": 1,
    "lat": 55.0304,
    "lon": 82.9204,
    "speed": 45.5,
    "heading": 180,
    "timestamp": "2025-12-18T12:00:00Z"
  }
}
```

**Событие:**
```json
{
  "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
```bash
# Проверить что backend запущен
docker-compose ps

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

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

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

### Ошибка подключения к БД
```bash
# Проверить что postgres запущен
docker-compose ps postgres

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

## 📝 Лицензия

MIT