NANDI/sibuti

Fork 0

Files

mamonov.ep 030af7ca83 init

2025-12-18 21:13:49 +03:00

20 KiB

Raw Blame History

Техническое задание

Система мониторинга транспорта в реальном времени

1. Общие сведения

Параметр	Значение
Название проекта	Transport Monitoring System
Тип	Учебный проект
Версия ТЗ	1.0
Дата	2025-12-18
Срок разработки	2 недели
Frontend фреймворк	Vue 3 (выбран)

2. Цели и задачи проекта

2.1 Цель

Разработка веб-системы для мониторинга местоположения транспортных средств в реальном времени с визуализацией на карте и хранением истории перемещений.

2.2 Задачи

Отображение текущего положения транспорта на интерактивной карте
Обновление позиций в реальном времени (WebSocket)
Хранение и просмотр истории перемещений
Генерация событий (остановки, превышение скорости)
Симуляция данных для демонстрации работы системы

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

3.1 Backend

Компонент	Технология	Версия
Язык	Python	3.11+
Фреймворк	FastAPI	0.104+
ORM	SQLAlchemy	2.0+
Миграции	Alembic	1.12+
База данных	PostgreSQL	15+
WebSocket	FastAPI WebSockets	встроено

3.2 Frontend

Компонент	Технология	Версия
Фреймворк	Vue 3	3.4+
Сборщик	Vite	5.0+
Карты	Leaflet	1.9+
UI-компоненты	Naive UI	2.35+
HTTP-клиент	Axios	1.6+

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

Компонент	Технология
Контейнеризация	Docker + Docker Compose
Reverse Proxy	Nginx 1.25+
Тайлы карты	OpenStreetMap

3.4 Nginx (Reverse Proxy)

Nginx выступает единой точкой входа:

/ → статика Vue (production) или проксирование на Vite (development)
/api/* → проксирование на FastAPI backend
/ws/* → проксирование WebSocket на backend

┌─────────────────────────────────────────────────────────────┐
│                        Nginx (:80)                          │
├─────────────────────────────────────────────────────────────┤
│  /              →  Frontend (статика или Vite dev:5173)     │
│  /api/*         →  Backend (FastAPI :8000)                  │
│  /ws/*          →  Backend WebSocket (:8000)                │
└─────────────────────────────────────────────────────────────┘

4. Функциональные требования

4.1 Модуль "Диспетчер" (главный экран)

FR-1.1 Карта

Отображение интерактивной карты на базе Leaflet + OSM
Маркеры транспортных средств с иконками по типу (автобус, грузовик, легковой)
Всплывающая подсказка при наведении на маркер (название, скорость)
Центрирование карты по выбранному объекту

FR-1.2 Список объектов

Боковая панель со списком всех транспортных средств
Поиск/фильтрация по названию
Индикатор статуса: движется (зелёный), стоит (жёлтый), нет связи (серый)
Клик по объекту — выделение на карте + открытие карточки

FR-1.3 Карточка объекта

Название и тип ТС
Текущие координаты (lat, lon)
Скорость (км/ч)
Направление движения (heading)
Время последней точки
Статус (движется/стоит)

4.2 Модуль "История движения"

FR-2.1 Запрос истории

Выбор временного диапазона: 30 мин / 1 час / 24 часа / произвольный
Кнопка "Показать трек"

FR-2.2 Отображение трека

Полилиния маршрута на карте
Цветовая индикация скорости (опционально)
Маркеры начала и конца маршрута

FR-2.3 Таблица точек

Список точек: время, координаты, скорость
Клик по строке — центрирование карты на точке
Экспорт в CSV (опционально)

4.3 Модуль "Реалтайм обновления"

FR-3.1 WebSocket соединение

Автоматическое подключение при загрузке страницы
Переподключение при обрыве связи
Индикатор статуса соединения в UI

FR-3.2 Обновление данных

Плавное перемещение маркеров при получении новых координат
Обновление данных в карточке объекта
Обновление статусов в списке объектов

4.4 Модуль "События"

FR-4.1 Типы событий

LONG_STOP — остановка более N минут (настраиваемый порог)
OVERSPEED — превышение скорости (порог настраивается)
CONNECTION_LOST — нет данных более 5 минут

FR-4.2 Лента событий

Панель с последними событиями (10-20 штук)
Фильтр по типу события
Клик по событию — переход к объекту на карте

4.5 Модуль "Симулятор"

FR-5.1 Генерация данных

Python-скрипт для имитации движения N объектов
Реалистичное движение по координатам (не телепортация)
Случайные остановки и изменения скорости
Отправка данных через REST API или WebSocket

5. Архитектура системы

5.1 Общая схема

                              ┌─────────────────┐
                              │                 │
                              │     Nginx       │ :80
                              │  (reverse proxy)│
                              │                 │
                              └────────┬────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │ /api, /ws        │ /                │
                    ▼                  │                  ▼
┌─────────────────┐ │  ┌─────────────────┐     ┌─────────────────┐
│                 │ │  │                 │     │                 │
│   Симулятор     │────▶   Backend       │     │   Frontend      │
│   (Python)      │POST│   (FastAPI)     │     │   (Vue 3)       │
│                 │    │   :8000         │     │   :5173 (dev)   │
└─────────────────┘    └────────┬────────┘     └─────────────────┘
                                │
                                │ SQL
                                ▼
                       ┌─────────────────┐
                       │                 │
                       │   PostgreSQL    │ :5432
                       │                 │
                       └─────────────────┘

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

transport/
├── docker-compose.yml
├── docs/
│   └── TECHNICAL_SPECIFICATION.md
├── nginx/
│   ├── nginx.conf           # Основной конфиг
│   ├── conf.d/
│   │   └── default.conf     # Конфиг сервера
│   └── Dockerfile           # (опционально, для кастомизации)
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── alembic/
│   │   └── versions/
│   ├── alembic.ini
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI приложение
│   │   ├── config.py            # Настройки
│   │   ├── database.py          # Подключение к БД
│   │   ├── models/
│   │   │   ├── __init__.py
│   │   │   ├── vehicle.py
│   │   │   ├── position.py
│   │   │   └── event.py
│   │   ├── schemas/
│   │   │   ├── __init__.py
│   │   │   ├── vehicle.py
│   │   │   ├── position.py
│   │   │   └── event.py
│   │   ├── routers/
│   │   │   ├── __init__.py
│   │   │   ├── vehicles.py
│   │   │   ├── positions.py
│   │   │   └── events.py
│   │   ├── services/
│   │   │   ├── __init__.py
│   │   │   ├── event_detector.py
│   │   │   └── websocket_manager.py
│   │   └── websocket.py         # WS эндпоинт
│   └── simulator/
│       └── run.py               # Симулятор данных
├── frontend/
│   ├── Dockerfile
│   ├── package.json
│   ├── vite.config.js
│   ├── index.html
│   └── src/
│       ├── main.js
│       ├── App.vue
│       ├── components/
│       │   ├── MapView.vue
│       │   ├── VehicleList.vue
│       │   ├── VehicleCard.vue
│       │   ├── TrackHistory.vue
│       │   └── EventFeed.vue
│       ├── composables/
│       │   ├── useWebSocket.js
│       │   └── useVehicles.js
│       └── stores/
│           └── vehicles.js
└── README.md

6. API спецификация

6.1 REST API

Транспортные средства

Метод	Эндпоинт	Описание
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/vehicles/{id}/last-position`	Последняя позиция ТС

Query параметры для /api/vehicles/{id}/positions:

from — начало периода (ISO 8601)
to — конец периода (ISO 8601)
limit — максимум записей (default: 1000)

События

Метод	Эндпоинт	Описание
GET	`/api/events`	Список событий
GET	`/api/vehicles/{id}/events`	События конкретного ТС

Query параметры для /api/events:

type — тип события (LONG_STOP, OVERSPEED, CONNECTION_LOST)
from / to — временной диапазон
limit — максимум записей

6.2 WebSocket API

Подключение

ws://localhost/ws/positions

(Nginx проксирует на backend:8000)

Формат сообщений (сервер → клиент)

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

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

7. Структура базы данных

7.1 Таблица `vehicles`

Поле	Тип	Описание
id	SERIAL PRIMARY KEY	Идентификатор
name	VARCHAR(100) NOT NULL	Название/номер ТС
type	VARCHAR(50)	Тип: bus, truck, car
created_at	TIMESTAMP	Дата создания

7.2 Таблица `positions`

Поле	Тип	Описание
id	SERIAL PRIMARY KEY	Идентификатор
vehicle_id	INTEGER FK	Ссылка на vehicles
timestamp	TIMESTAMP NOT NULL	Время фиксации
lat	DOUBLE PRECISION	Широта
lon	DOUBLE PRECISION	Долгота
speed	REAL	Скорость (км/ч)
heading	REAL	Направление (0-360)

Индексы:

idx_positions_vehicle_ts ON (vehicle_id, timestamp DESC)

7.3 Таблица `events`

Поле	Тип	Описание
id	SERIAL PRIMARY KEY	Идентификатор
vehicle_id	INTEGER FK	Ссылка на vehicles
timestamp	TIMESTAMP NOT NULL	Время события
type	VARCHAR(50) NOT NULL	Тип события
payload	JSONB	Дополнительные данные