404 lines
24 KiB
Markdown
404 lines
24 KiB
Markdown
# BRD: Enduro Trails — Фаза 3 «Умный маршрут»
|
||
|
||
**Версия:** 1.1
|
||
**Дата:** 2026-05-04
|
||
**Автор:** Стрим 🌊
|
||
**Статус:** Согласовано ✅
|
||
|
||
---
|
||
|
||
## 1. Контекст и цели
|
||
|
||
### Что уже есть (Фаза 1–2)
|
||
- Карта грунтовок ЦФО+Чувашия (1.1М треков)
|
||
- Роутинг «Дикий путь» A→B (OSRM, кастомный профиль)
|
||
- Поиск населённых пунктов (Nominatim)
|
||
- Линейка расстояний
|
||
|
||
### Цель Фазы 3
|
||
Превратить «Дикий путь» из простого роутинга в **инструмент планирования маршрута**: несколько вариантов на выбор, детальная статистика по каждому, удобный экспорт. Пользователь должен уметь сравнить маршруты и выбрать тот, который ему нравится — не вслепую, а опираясь на данные.
|
||
|
||
### Приоритеты
|
||
1. **Удобство** — минимум кликов, всё под рукой
|
||
2. **Наглядность** — статистика читается с первого взгляда
|
||
3. **Качество** — данные точные, UI не ломается на крайних случаях
|
||
|
||
---
|
||
|
||
## 2. Фичи
|
||
|
||
---
|
||
|
||
### F-01: Альтернативные маршруты
|
||
|
||
#### Описание
|
||
При построении маршрута A→B система генерирует **до 5 вариантов** с разным балансом грунтовок/асфальта/дистанции. Все варианты отображаются на карте одновременно. Пользователь выбирает понравившийся.
|
||
|
||
#### Зачем
|
||
Один маршрут — это лотерея. Иногда OSRM строит «технически правильный» путь, но он скучный или неудобный. Пользователь хочет видеть спектр вариантов и выбрать осознанно.
|
||
|
||
#### Use Cases
|
||
|
||
**UC-01.1 — Базовый выбор маршрута**
|
||
> Слава ставит точки A и B. Нажимает «Дикий путь». Появляются 3–5 маршрутов разными цветами. Карточки вариантов показывают дистанцию, % грунта, время. Слава выбирает вариант с максимальным % грунта. Остальные исчезают, выбранный остаётся.
|
||
|
||
**UC-01.2 — Сравнение вариантов**
|
||
> Слава видит вариант 1 (120 км, 85% грунт) и вариант 3 (95 км, 70% грунт). Хочет посмотреть оба на карте. Наводит мышь на карточку — соответствующий маршрут подсвечивается жирнее. Решает взять вариант 1 — больше грунта, пусть и длиннее.
|
||
|
||
**UC-01.3 — Нет альтернатив**
|
||
> Точки A и B близко, только один разумный путь. Система показывает 1–2 варианта и поясняет: «Альтернативных маршрутов не найдено».
|
||
|
||
#### Требования
|
||
- Минимум 1 маршрут, максимум **5** (подтверждено Славой)
|
||
- Варианты визуально различимы: разные цвета (палитра: синий, зелёный, фиолетовый, оранжевый, серый)
|
||
- Активный (выбранный) маршрут — жирнее и ярче
|
||
- Hover на карточке → подсветка маршрута на карте
|
||
- Клик на карточке → выбор маршрута
|
||
- Клик на маршруте на карте → выбор маршрута
|
||
- Кнопка «Сбросить» убирает все маршруты и маркеры
|
||
|
||
#### Технические заметки
|
||
OSRM поддерживает `alternatives=true` (до 3 вариантов) и `alternatives=N` (до 5). Параметр передаётся в запросе к `/route/v1/driving/`. Дополнительно можно варьировать `radiuses` и `snapping` для получения более разнообразных вариантов. Запрашивать `alternatives=5` всегда — показывать сколько вернёт OSRM (от 1 до 5).
|
||
|
||
---
|
||
|
||
### F-02: Статистика маршрута
|
||
|
||
#### Описание
|
||
Каждый маршрут сопровождается **карточкой со статистикой**: дистанция, время, разбивка покрытия по типам дорог. Карточки компактные, читаются за 2 секунды.
|
||
|
||
#### Зачем
|
||
Без статистики маршрут — просто линия на карте. Пользователь не может оценить «насколько это грунтовый маршрут» без цифр и визуализации.
|
||
|
||
#### Use Cases
|
||
|
||
**UC-02.1 — Быстрая оценка**
|
||
> Слава видит 4 карточки маршрутов. На каждой — дистанция, время и цветная полоска покрытия. За 5 секунд понимает: вариант 2 самый «грунтовый» (80% жёлтого в полоске), вариант 4 самый короткий. Выбирает вариант 2.
|
||
|
||
**UC-02.2 — Детальная статистика**
|
||
> Слава выбрал маршрут. Карточка разворачивается: показывает детальную разбивку по км и %, количество треков каждого типа, расчётное время. Слава видит что 15 км из 120 — асфальт (неизбежный участок через город).
|
||
|
||
**UC-02.3 — Сравнение двух маршрутов**
|
||
> Слава не может выбрать между вариантом 1 и 3. Нажимает «Сравнить» — карточки встают рядом, колонки выровнены. Видно что вариант 1 длиннее на 25 км, но даёт +15% грунта.
|
||
|
||
#### Состав статистики
|
||
|
||
**Компактная карточка (всегда видна):**
|
||
- Номер варианта + цветовой маркер
|
||
- Дистанция: `142 км`
|
||
- Время: `4 ч 35 мин` (см. F-03)
|
||
- Полоска покрытия (цветная, пропорциональная):
|
||
- 🟡 Lev1-2 (грунт твёрдый)
|
||
- 🔴 Lev3-5 (грунт мягкий)
|
||
- 🔴 Тропа (path/bridleway)
|
||
- ⬜ Асфальт
|
||
|
||
**Развёрнутая карточка (по клику «Подробнее»):**
|
||
- Разбивка по км и %:
|
||
```
|
||
Lev1-2 (твёрдый грунт): 68 км (48%)
|
||
Lev3-5 (мягкий грунт): 42 км (30%)
|
||
Тропы: 12 км (8%)
|
||
Асфальт: 20 км (14%)
|
||
```
|
||
- Итого грунт: `122 км (86%)`
|
||
- Итого асфальт: `20 км (14%)`
|
||
|
||
#### Требования
|
||
- Полоска покрытия — пропорциональная, минимальная ширина сегмента 3px (чтобы не терялся)
|
||
- Цвета полоски совпадают с цветами слоёв на карте
|
||
- Статистика считается на бэкенде по геометрии маршрута + данным БД
|
||
- Карточки не перекрывают карту (панель сбоку или снизу)
|
||
|
||
---
|
||
|
||
### F-03: Человекочитаемое время
|
||
|
||
#### Описание
|
||
Время маршрута отображается в формате `X ч Y мин` или `X дн Y ч Z мин`. Никаких «135 минут».
|
||
|
||
#### Зачем
|
||
«135 минут» — это неудобно. Мозг не воспринимает большие числа минут интуитивно. «2 ч 15 мин» — сразу понятно.
|
||
|
||
#### Use Cases
|
||
|
||
**UC-03.1 — Короткий маршрут**
|
||
> Маршрут 45 минут → отображается `45 мин`
|
||
|
||
**UC-03.2 — Стандартный маршрут**
|
||
> Маршрут 155 минут → отображается `2 ч 35 мин`
|
||
|
||
**UC-03.3 — Длинный маршрут**
|
||
> Маршрут 1560 минут → отображается `1 дн 2 ч`
|
||
|
||
**UC-03.4 — Очень длинный маршрут**
|
||
> Маршрут 2750 минут → отображается `1 дн 21 ч 50 мин`
|
||
|
||
#### Правила форматирования
|
||
```
|
||
< 60 мин → "X мин"
|
||
60 мин – 23:59 → "X ч Y мин" (если Y=0 → "X ч")
|
||
≥ 24 ч → "X дн Y ч Z мин" (если Z=0 → "X дн Y ч")
|
||
```
|
||
|
||
#### Требования
|
||
- Реализовать как утилитарную функцию `formatDuration(seconds)` в `app.js`
|
||
- Применить везде где отображается время: карточки маршрутов, развёрнутая статистика
|
||
- Время считается от OSRM (секунды) — конвертировать на фронте
|
||
|
||
---
|
||
|
||
### F-04: Промежуточные точки маршрута
|
||
|
||
#### Описание
|
||
Пользователь может добавить **промежуточные точки** (waypoints) между A и B. Маршрут строится через все точки по порядку. Точки можно перетаскивать.
|
||
|
||
#### Зачем
|
||
Часто нужно «зайти» в конкретное место — деревню, лесной массив, смотровую точку. Без промежуточных точек маршрут строится напрямую и может обойти интересное место стороной.
|
||
|
||
#### Use Cases
|
||
|
||
**UC-04.1 — Добавление точки**
|
||
> Слава построил маршрут A→B. Видит что маршрут обходит интересный лесной массив. Нажимает «+ Точка» и кликает на карте в нужном месте. Маршрут перестраивается через новую точку C: A→C→B.
|
||
|
||
**UC-04.2 — Несколько точек**
|
||
> Слава добавляет 3 промежуточные точки. Маршрут строится A→C1→C2→C3→B. В панели точек видны все 5 точек с возможностью удалить любую.
|
||
|
||
**UC-04.3 — Перетаскивание точки** ✅ (подтверждено)
|
||
> Слава хочет немного сдвинуть промежуточную точку. Перетаскивает маркер на карте. Маршрут перестраивается в реальном времени (debounce 300ms).
|
||
|
||
**UC-04.4 — Удаление точки**
|
||
> В панели точек Слава нажимает ✕ рядом с промежуточной точкой. Точка удаляется, маршрут перестраивается.
|
||
|
||
**UC-04.5 — Изменение порядка**
|
||
> Слава хочет поменять порядок точек. Перетаскивает строку в панели точек (drag-and-drop). Маршрут перестраивается.
|
||
|
||
#### Требования
|
||
- Максимум 8 промежуточных точек (итого 10 точек включая A и B)
|
||
- Маркеры промежуточных точек визуально отличаются от A/B (меньше, другой цвет — белый с цветной обводкой)
|
||
- Перестройка маршрута при перетаскивании — debounce 300ms (**обязательно**, подтверждено Славой)
|
||
- Панель точек: список с иконками A, 1, 2, ..., B и кнопками удаления
|
||
- При добавлении точки режим «добавить точку» активируется кнопкой, деактивируется после клика
|
||
|
||
---
|
||
|
||
### F-05: Экспорт GPX
|
||
|
||
#### Описание
|
||
Выбранный маршрут можно скачать в формате GPX для загрузки в навигатор (OsmAnd, Garmin, Locus Map и др.).
|
||
|
||
#### Зачем
|
||
Карта в браузере — для планирования. В поле нужен навигатор. GPX — универсальный формат, поддерживается всеми мото/вело навигаторами.
|
||
|
||
#### Use Cases
|
||
|
||
**UC-05.1 — Скачать маршрут**
|
||
> Слава выбрал маршрут. Нажимает «Скачать GPX». Браузер скачивает файл `enduro-route-2026-05-04.gpx`. Слава загружает его в OsmAnd. Файл содержит и трек (полная геометрия), и waypoints (метки + точки маршрута).
|
||
|
||
**UC-05.2 — GPX с промежуточными точками**
|
||
> Маршрут с 3 промежуточными точками. GPX содержит все waypoints + трек. В OsmAnd точки отображаются как промежуточные остановки.
|
||
|
||
**UC-05.3 — Имя файла**
|
||
> Файл называется `enduro-YYYYMMDD-HHMMSS.gpx` — уникальное имя, не перезаписывает предыдущие.
|
||
|
||
#### Требования
|
||
- GPX 1.1 формат
|
||
- Содержит **оба элемента** (подтверждено Славой):
|
||
- `<trk>` + `<trkseg>` — полная геометрия маршрута (все точки от OSRM)
|
||
- `<wpt>` — точки A, промежуточные, B + все флажки/метки с карты
|
||
- Метаданные: name (`Enduro route YYYY-MM-DD`), desc (дистанция + % грунта), time
|
||
- Генерация на фронте (из геометрии OSRM ответа + localStorage меток) — не требует бэкенда
|
||
- Кнопка «Скачать GPX» активна только когда маршрут выбран
|
||
|
||
---
|
||
|
||
### F-06: Флажки / именованные метки
|
||
|
||
#### Описание
|
||
Пользователь может расставить на карте **именованные метки** (флажки) — интересные места, точки старта, лагерь, заправка и т.д. Метки сохраняются в localStorage.
|
||
|
||
#### Зачем
|
||
При планировании маршрута нужно отмечать «хочу заехать сюда», «здесь заправка», «здесь ночёвка». Без меток всё держится в голове или в отдельных заметках.
|
||
|
||
#### Use Cases
|
||
|
||
**UC-06.1 — Поставить метку**
|
||
> Слава нажимает кнопку 🚩. Курсор меняется. Кликает на карте. Появляется диалог: поле для названия (placeholder «Метка 1»), выбор иконки (🚩⛺🔧⛽💧). Нажимает «Сохранить». Метка появляется на карте.
|
||
|
||
**UC-06.2 — Метка без названия**
|
||
> Слава кликает и сразу нажимает Enter (пустое название). Метка сохраняется с автоименем «Метка N».
|
||
|
||
**UC-06.3 — Клик по метке**
|
||
> Слава кликает по существующей метке. Попап: название, координаты, кнопки «Редактировать» и «Удалить».
|
||
|
||
**UC-06.4 — Метки сохраняются**
|
||
> Слава закрывает браузер, открывает снова. Все метки на месте (localStorage).
|
||
|
||
**UC-06.5 — Использовать метку как точку маршрута**
|
||
> В попапе метки есть кнопки «Сделать точкой A» и «Сделать точкой B». Слава нажимает «Сделать точкой A» — метка становится стартом маршрута.
|
||
|
||
**UC-06.6 — Экспорт меток в GPX**
|
||
> При скачивании GPX (F-05) метки включаются как `<wpt>` с именами.
|
||
|
||
#### Требования
|
||
- Хранение: localStorage, ключ `enduro_markers` (**только браузер**, подтверждено Славой — синхронизация между устройствами не нужна)
|
||
- Максимум 50 меток (предупреждение при достижении лимита)
|
||
- Иконки: 🚩 (по умолчанию), ⛺, 🔧, ⛽, 💧, 📍
|
||
- Метки отображаются поверх всех слоёв
|
||
- Кнопка «Очистить все метки» с подтверждением
|
||
|
||
---
|
||
|
||
## 3. Нефункциональные требования
|
||
|
||
### Производительность
|
||
- Построение маршрута (включая статистику) — не более 5 секунд
|
||
- При ожидании — спиннер на кнопке, карта не блокируется
|
||
- Перестройка при перетаскивании точки — debounce 300ms, не тормозит UI
|
||
|
||
### Мобильность
|
||
- Панель маршрутов не перекрывает карту на экранах < 768px
|
||
- Карточки маршрутов скроллируются горизонтально на мобиле
|
||
- Touch-события для перетаскивания точек
|
||
|
||
### Надёжность
|
||
- Если OSRM не вернул альтернативы — показать 1 маршрут без ошибки
|
||
- Если статистика не посчиталась — показать маршрут без статистики, не ломать UI
|
||
- Если localStorage недоступен — метки работают только в сессии, без ошибки
|
||
|
||
---
|
||
|
||
## 4. Изменения в бэкенде
|
||
|
||
### Новый endpoint: `/api/route` (расширение существующего)
|
||
|
||
**Запрос:**
|
||
```json
|
||
{
|
||
"waypoints": [
|
||
{"lon": 37.6, "lat": 55.7},
|
||
{"lon": 38.1, "lat": 55.9},
|
||
{"lon": 39.5, "lat": 56.2}
|
||
],
|
||
"alternatives": 5
|
||
}
|
||
```
|
||
|
||
**Ответ:**
|
||
```json
|
||
{
|
||
"routes": [
|
||
{
|
||
"index": 0,
|
||
"geometry": { "type": "LineString", "coordinates": [...] },
|
||
"distance_m": 142000,
|
||
"duration_s": 16500,
|
||
"stats": {
|
||
"track_lev12_m": 68000,
|
||
"track_lev345_m": 42000,
|
||
"path_m": 12000,
|
||
"asphalt_m": 20000,
|
||
"track_lev12_pct": 48,
|
||
"track_lev345_pct": 30,
|
||
"path_pct": 8,
|
||
"asphalt_pct": 14,
|
||
"dirt_total_pct": 86
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Логика расчёта статистики
|
||
1. Получить геометрию маршрута от OSRM (LineString)
|
||
2. Разбить на сегменты по 50м
|
||
3. Для каждого сегмента — найти ближайший трек в БД (spatial query по bbox)
|
||
4. Суммировать длины по типам: `highway_type` + `track_type`
|
||
5. Вернуть в ответе вместе с геометрией
|
||
|
||
> ⚠️ Расчёт статистики — приближённый (snap to nearest road). Точность ±5% — **согласовано со Славой**, достаточно для принятия решения.
|
||
|
||
---
|
||
|
||
## 5. UI/UX требования
|
||
|
||
### Панель маршрутов
|
||
- Появляется справа (десктоп) или снизу (мобиле) после построения маршрутов
|
||
- Карточки маршрутов: компактные, скроллируемые
|
||
- Активный маршрут выделен рамкой/фоном
|
||
- Кнопка «Сбросить всё» — сбрасывает маршруты и точки
|
||
|
||
### Карточка маршрута (компактная)
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ ● Вариант 1 142 км │
|
||
│ ████████████░░░ 4 ч 35 мин │
|
||
│ 86% грунт · 14% асфальт │
|
||
│ [Подробнее ▼] │
|
||
└─────────────────────────────────┘
|
||
```
|
||
- Цветная точка = цвет маршрута на карте
|
||
- Полоска = визуализация покрытия
|
||
- Клик на карточку = выбор маршрута
|
||
|
||
### Карточка маршрута (развёрнутая)
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ ● Вариант 1 142 км │
|
||
│ ████████████░░░ 4 ч 35 мин │
|
||
│ │
|
||
│ 🟡 Lev1-2 68 км 48% │
|
||
│ 🔴 Lev3-5 42 км 30% │
|
||
│ 🔴 Тропы 12 км 8% │
|
||
│ ⬜ Асфальт 20 км 14% │
|
||
│ │
|
||
│ [📥 GPX] [Выбрать маршрут] │
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
### Панель точек
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ 📍 Точки маршрута [+ Точка] │
|
||
│ A Москва, ул. Ленина [✕] │
|
||
│ 1 55.812, 37.441 [✕] │
|
||
│ B Тверь, центр [✕] │
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Приоритет реализации
|
||
|
||
| # | Фича | Приоритет | Сложность | Ценность |
|
||
|---|------|-----------|-----------|----------|
|
||
| F-03 | Человекочитаемое время | 🔴 Высокий | Низкая | Высокая |
|
||
| F-01 | Альтернативные маршруты | 🔴 Высокий | Средняя | Очень высокая |
|
||
| F-02 | Статистика маршрута | 🔴 Высокий | Средняя | Очень высокая |
|
||
| F-05 | Экспорт GPX | 🟡 Средний | Низкая | Высокая |
|
||
| F-04 | Промежуточные точки | 🟡 Средний | Высокая | Высокая |
|
||
| F-06 | Флажки/метки | 🟢 Низкий | Средняя | Средняя |
|
||
|
||
**Рекомендуемый порядок реализации:**
|
||
1. F-03 (время) — быстро, сразу улучшает UX
|
||
2. F-01 + F-02 (альтернативы + статистика) — ядро фазы, делать вместе
|
||
3. F-05 (GPX) — логичное продолжение после выбора маршрута
|
||
4. F-04 (промежуточные точки) — отдельный итерация
|
||
5. F-06 (флажки) — последними, наименее критично
|
||
|
||
---
|
||
|
||
## 7. Решения (согласовано 2026-05-04)
|
||
|
||
| # | Вопрос | Решение |
|
||
|---|--------|---------|
|
||
| 1 | Количество альтернатив | **5** — запрашивать максимум, показывать сколько вернёт OSRM |
|
||
| 2 | Точность статистики | **±5% ок** — приближённый расчёт по сегментам |
|
||
| 3 | Перетаскивание точек | **Нужно** — drag на карте с debounce 300ms |
|
||
| 4 | Синхронизация меток | **Только localStorage** — между устройствами не нужно |
|
||
| 5 | Формат GPX | **Трек + метки** — `<trk>` с геометрией и `<wpt>` для всех точек и флажков |
|
||
|
||
---
|
||
|
||
*Документ согласован. Готов к передаче Dev-агенту.*
|