# Оффлайн-карта с треком по WebSocket

**Стек:** Python (FastAPI) + WebSocket + React (Leaflet + Tauri)
**Цель:** хранить карту полностью локально на устройстве и в реальном времени отображать движение по координатам GNSS.

## 1. Цели и общие требования

### 1.1. Функциональные цели

1. Отображать карту местности **без доступа к интернету**.
2. Получать от устройства GNSS координаты в реальном времени.
3. Передавать координаты в клиентское приложение через **WebSocket**, без периодических запросов.
4. В React-приложении:
	1. показывать текущую позицию на карте.    
	2. рисовать трек движения (историю точек). 
	3. при необходимости в будущем — отображать дополнительные слои (контуры поля, границы, маршруты). 

### 1.2. Нефункциональные требования

1. **Полный оффлайн:**
	1. ни карта, ни координаты не должны требовать внешних сервисов.
	2. все файлы тайлов карты находятся локально на диске устройства.
2. **Устойчивость:**
    1. временные потери GNSS-сигнала не должны ломать интерфейс.
    2. разрыв WebSocket-соединения не должен ломать отображение данных с  фронта.
3. **Расширяемость:**
	1. добавлять новые типы данных (например, скорость, курс, высоту).
	2. подключать реальные GNSS-устройства вместо генераторов.            
	3. добавлять слои на карту: полигоны, точки, маршруты.
4. **Простота развёртывания:**
    1. backend и frontend должны запускаться стандартными командами.
    2. конфигурация (путь к карте, параметры GNSS) выносится в настройки.
## 2. Архитектура решения

### 2.1. Высокоуровневая схема

Система логически делится на три части:
1. **Сервис получения GNSS-данных (внутри backend)**
    - модуль в Python, который:
        1. подключается к приёмнику GNSS.
        2. читает сырые данные.
        3. преобразует их в нормализованный формат (широта, долгота, метки времени).
2. **Backend-сервер (FastAPI)**
    - HTTP-интерфейсы:
        1. выдача тайлов карты по пути вида `/tiles/zoom/x/y.png`.
        2. вспомогательные эндпоинты (health-check, конфигурация и т.п.).
    - WebSocket-интерфейс:
        1. постоянное соединение с клиентом.
        2. отправка координат в режиме “push”.
    - работа с файловой системой:
        1. поиск нужных тайлов.
        2. выдача заглушки при отсутствии тайла.
3. **Клиент (React + Leaflet)**
    - модуль карты:
        1. инициализацирует Leaflet-карту.
        2. использует локальный URL тайлов (через backend).
    - модуль трека:
        1. поддерживает подключение по WebSocket.
        2. хранит массив полученных точек.
        3. обновляет отображение карты при получении новых данных.
#### Связи:
1. GNSS → модуль GNSS backend’а → WebSocket → React → Leaflet.
2. React → HTTP (через Leaflet) → backend → файловая система с тайлами.
### 2.2. Логические компоненты

**Backend:**
1. Модуль инициализации приложения FastAPI.
2. Модуль выдачи тайлов:
    1. логика построения пути к тайлу по `{zoom}/{x}/{y}`.
    2. проверка наличия файла.
    3. выдача или оригинального тайла, или заглушки.
3. Модуль GNSS:
    1. абстракция источника координат.
    2. возможность переключить данный источник:
        1. на реальное устройство.
4. Модуль WebSocket:
    1. управление подключениями клиентов.
    2. цикл отправки координат.
    3. обработка разрывов соединения и ошибок.
**Frontend:**
5. Модуль подключения WebSocket:
    1. открытие соединения.
    2. обработка входящих сообщений с координатами.
    3. восстановление соединения при разрыве.
6. Модуль управления треком:
    1. добавление точки в список.
7. Модуль карты:
    1. инициализация Leaflet-карты.
    2. настройка источника тайлов на локальный backend.
    3. отображение маркера последней точки.
## 3. Оффлайн-карта: концепция и хранение

### 3.1. Формат карты

В начальной версии планируется использовать **растровые тайлы**:
1. карта заранее разбивается на набор изображений (PNG или JPEG).
2. тайлы организованы в структуре каталогов по схеме:
    1. уровень масштабирования (zoom).
    2. координаты тайла по X и Y.
Преимущества:
3. Leaflet “из коробки” умеет работать с тайлами такого формата.
4. не требуется дополнительный сервер картографических данных — достаточно отдавать файлы по HTTP.
5. относительно просто генерировать карту для нужного региона с помощью внешних инструментов (QGIS, GDAL и др.).

### 3.2. Структура хранения тайлов

На уровне файловой системы тайлы лежат в диапазоне, например:

1. `tiles/10/567/321.png` — тайл уровня зума 10, координаты X=567, Y=321.
2. `tiles/11/1134/643.png` — тот же район на другом зуме.

Backend ничего не знает о том, как эти тайлы были созданы, он:

1. получает значение zoom, x и y из URL.
2. строит путь к файлу.
3. проверяет наличие файла.
4. отдаёт файл, если он есть.
5. если файлы нет — отдаёт заранее подготовленную картинку-заглушку.

Таким образом, карта является полностью статичной, а логика backend — максимально простой.

### 3.3. Генерация и обновление карты

Это отдельный процесс, который выполняется вне основной системы:
1. Выбирается необходимый регион (поля, районы полётов).
2. В GIS-инструменте формируется растровая подложка.
3. Эта подложка нарезается в тайлы нужных уровней масштабирования.
4. Готовый набор тайлов копируется на устройство в папку `tiles/`.

В дальнейшем можно:

1. обновлять карту, подменяя содержимое `tiles/`.
2. хранить несколько наборов карт (например, по сезонам) и включать нужный через конфиг.

## 4. Работа с координатами и GNSS

### 4.1. Источник данных

Фактически координаты приходят либо:
1. от реального GNSS-приёмника, подключённого по:
    1. последовательному порту.
    2. USB.
    3. сетевому протоколу.
2. либо от программного симулятора, который генерирует “виртуальный маршрут”.

Задача backend — предоставить единый интерфейс, не зависящий от конкретного железа.

### 4.2. Нормализация координат

Сырые данные могут быть в формате NMEA или другом специфичном виде. Модуль GNSS:

1. парсит входные данные.    
2. приводит координаты к стандартной системе:
    1. широта (latitude) в градусах.
    2. долгота (longitude) в градусах.
    3. опционально — высота, скорость, курс.
3. добавляет метку времени (например, UNIX timestamp или ISO-строку).
4. формирует структуру, удобную для отправки на фронт.

Важно, чтобы координаты были в той системе, которую ожидает Leaflet (обычно WGS84).

### 4.3. Частота обновления

1. Модуль GNSS определяет:
	1. как часто появляются новые точки.
	2. как часто обновлять данные на фронте:
    3. возможен вариант “как пришло — так отправили”.
    4. либо накопление точек и отправка пачками (например, раз в секунду).

Частота обновления — важный параметр, влияющий на:
1. плавность трека.
2. нагрузку на канал связи.
3. нагрузку на фронт.

## 5. Потоки данных и жизненный цикл приложения

### 5.1. Запуск backend

1. При старте FastAPI:
    1. инициализирует конфигурацию (настройки путей, порты, параметры GNSS).
    2. проверяет наличие базовых директорий (`tiles/`, заглушка тайла).
    3. при необходимости пробует подключиться к GNSS-источнику.
2. Запускается HTTP-сервер:
    1. обслуживает выдачу тайлов.
    2. отвечает на запросы.

### 5.2. Запуск frontend

1. React-приложение загружается в оболочке Tauri (Бинарник)
2. После инициализации:
    1. открывается WebSocket-соединение с backend.
    2. инициализируется карта:
        1. начальный центр (по умолчанию либо по первой полученной точке).
        2. указание backend-урла тайлов.
3. При успешном подключении по WebSocket:
    1. приложение начинает получать координаты.
    2. каждая новая точка добавляется в список.
    3. карта обновляет положение маркера и линии трека.

### 5.3. Реакция на ошибки и разрывы

1. Если WebSocket-соединение закрывается:
    1. фронт может попытаться переподключиться через интервалы.
    2. на карте можно оставить последнюю известную позицию.
2. Если нет GNSS-данных:
    1. backend может отправлять специальные сообщения о состоянии (например, “нет сигнала”).
    2. фронт может отображать статичную карту без движения или соответствующее уведомление.
3. Если тайл для карты отсутствует:
    1. backend отдаёт заглушку.
    2. на карте вместо участка появляется условный “серый” квадрат, но интерфейс остаётся рабочим.

## 6. Основные этапы разработки

### Этап 1. Подготовка окружения и структуры проекта

1. Создать общий репозиторий с двумя основными директориями: `backend` и `frontend`.
2. Настроить базовую систему сборки и запуска:
    - для backend — запуск FastAPI через Uvicorn.
    - для frontend — сборщик (Vite + Tauri).
### Этап 2. Скелет backend-приложения

1. Инициализировать приложение FastAPI.
2. Добавить endpoint для проверки, что сервер поднялся.
3. Настроить CORS так, чтобы frontend мог связаться с backend в локальной разработке

На этом этапе можно убедиться, что базовая связка “frontend - backend по HTTP” работает.

### Этап 3. Механизм выдачи тайлов

1. Определить директорию хранения тайлов (`tiles/`).
2. Реализовать логику извлечения тайла по запросу вида `/tiles/{zoom}/{x}/{y}.png`.
3. Добавить заглушку для отсутствующих тайлов.
4. Прогнать простой тест: вручную запросить существующий и несуществующий тайл и убедиться, что:
    1. первый отдаётся корректно.
    2. второй отдаёт заглушку.

### Этап 4. Проработка GNSS-абстракции

1. Определить интерфейс модуля “источник координат”:
    1. формат выдаваемых данных.
    2. тип возвращаемой структуры (координаты + время).
2. На этом этапе использовать **симулятор** вместо реального устройства:
    1. сделать виртуальную траекторию (линия, круг, восьмёрка и т.п.).
    2. выдавать новые точки с заданным интервалом.
3. Важно: модуль должен быть реализован так, чтобы позже его можно было легко заменить реализацией, работающей с реальным железом.

### Этап 5. Добавление WebSocket-эндпоинта в backend

1. Создать WebSocket-обработчик:
    1. принимать подключение от клиента.
    2. при подключении запускать цикл, в котором:
        1. берётся следующая точка из GNSS-источника.
        2. отправляется на клиента.
2. Обработать возможные сценарии:
    1. разрыв соединения клиентом.
    2. ошибки в процессе отправки.
    3. отключение GNSS-источника.

На этом этапе backend уже умеет:

1. выдавать тайлы.
2. в реальном времени отдавать поток координат любому подключенному клиенту по WebSocket.

### Этап 6. Скелет frontend-приложения

1. Инициализировать React-приложение.
2. Подготовить базовую структуру компонентов:
    1. основной компонент приложения.
    2. компонент карты.
    3. будущий модуль для WebSocket.
3. Настроить запуск фронта и убедиться, что базовый “каркас” работает.

### Этап 7. Интеграция Leaflet в frontend

1. Подключить Leaflet и его React-обёртку.
2. Создать компонент карты, который:
    1. инициализирует карту с некоторым стартовым центром.
    2. использует URL `http://localhost:8000/tiles/{z}/{x}/{y}.png` в качестве источника тайлов.
3. Проверить:
    1. что при старте приложение отображает карту (в рамках подготовленной области).
    2. что при перемещении и масштабировании запросы к тайлам уходят на backend.

На этом этапе карта уже отображается локально, без участия внешних сервисов.

### Этап 8. Подключение WebSocket на frontend

1. Создать модуль, который:
    1. открывает WebSocket-соединение с backend’ом по адресу `ws://localhost:8000/ws/track`.
    2. слушает сообщения и добавляет новые координаты в локальное состояние приложения.
2. Реализовать простую логику:
    1. хранить массив точек.
    2. по каждой новой точке:
        1. добавлять её в массив.
        2. обновлять центр карты.
3. Связать модуль WebSocket с компонентом карты:
    1. передавать массив точек как пропсы.
    2. отображать:
        1. маркер последней точки.
        2. линию, соединяющую все точки (трек).

### Этап 9. Обработка ошибок и повышение устойчивости

1. Добавить обработку ошибок WebSocket на frontend:
    1. логировать причины разрыва.
    2. реализовать простую стратегию повторного подключения (например, попытка подключиться раз в несколько секунд при разрыве).
2. На backend:
    1. в явном виде логировать ошибки GNSS и WebSocket.
    2. при необходимости — реализовать таймауты и защиту от зависаний.

### Этап 10. Подключение реального GNSS-устройства

1. Вместо симулятора реализовать модуль чтения реальных данных:
    1. добавить конфиг с параметрами подключения: порт, скорость, протокол.
    2. реализовать парсинг данных.
2. Убедиться, что внешний интерфейс модуля GNSS не изменился:
    1. по-прежнему выдаются координаты в ожидаемом формате.
3. Протестировать работу системы “в поле”:
    1. убедиться, что карта и трек корректно отражают реальное движение.

### Этап 11. Оптимизация и подготовка к эксплуатации

1. Оптимизация производительности:
    1. ограничение длины трека, если ожидается очень длинное использование без перезапуска.
    2. настройка частоты обновления координат.
2. Упаковка приложения:
    1. вариант 1: backend + frontend как отдельные пакеты.
    2. вариант 2: объединение фронта и бека в один пакет.
3. Документация по развёртыванию:
    1. пошаговое руководство по установке зависимостей.
    2. инструкции по замене тайлов карты.
    3. инструкции по смене GNSS-источника.

## 7. Возможные дальнейшие расширения

После того как базовый функционал будет устойчиво работать, его можно расширять:

1. **Отображение контуров полей**
    1. загрузка контуров из локальных файлов (например, GeoJSON).
    2. визуализация границ поля поверх карты.
2. **Планирование маршрута**
    1. формирование линии проходов (полос) по ширине захвата.
    2. привязка трека к этим линиям (показ отклонения).
3. **Запись и экспорт данных**
    1. сохранение трека в файл (например, GeoJSON, GPX).
    2. экспорт для дальнейшего анализа.
4. **Конфигурация через UI**
    1. настройка масштабов карты, уровней тайлов.
    2. переключение наборов карт (разные сезоны, регионы).

## 8. Итоговая сводка

Суть решения: на устройстве устанавливается локальный сервер на Python (FastAPI), который одновременно:
1. отдаёт статические файлы тайлов карты с диска,
2. и по WebSocket непрерывно передаёт координаты из приёмника ГЛОНАСС.

React-приложение с Leaflet открывает эту локальную карту (через HTTP) и подписывается на WebSocket, чтобы в реальном времени обновлять положение маркера и трек движения. Всё — от карты до координат — живёт локально, не зависит от интернета и может работать в любых условиях, где есть только устройство, приёмник и локальная сеть (или даже один компьютер).