Stsezhka

Appearance

Use Case #01: Умное Кольцо 🔄 (Авто-генератор маршрутов) ​

1. Жизненная ситуация (Боль пользователя) ​

Представь: Субботнее утро. Пользователь хочет покататься на велосипеде ровно 2 часа. Он знает свою скорость, ему нужен маршрут на 40 километров. Он хочет выехать от своего дома и вернуться к нему же.

Как он мучается сейчас: Открывает обычную карту и впадает в ступор. "Куда ехать? На север? А вдруг там тупик? А как загнуть линию обратно, чтобы получилось ровно 40 км, а не 70? А вдруг я попаду на трассу с фурами?". На планирование такого круга вручную уходит 30–40 минут мучительного кликанья. Мечта юзера: Кликнуть мышкой в свой дом, сказать сайту: "Хочу 40 км по лесам" — и мгновенно получить идеальное готовое кольцо.

2. Как это ДОЛЖНО работать у тебя (UX-Магия) ​

Весь интерфейс должен быть таким же простым, как заказ пиццы.

Сценарий (Что видит юзер):

  1. Юзер ставит на карте ОДНУ точку (свой Дом / Отель).
  2. Сбоку открывается красивая панель "Генератор" с двумя настройками:
    • Длина: Ползунок (юзер тянет его на 40 км).
    • Покрытие: Выпадающий список [ Асфальт / Гравий / Лес ].
  3. Жмет гигантскую кнопку 🪄 [ Сгенерировать кольцо ]. Сайт думает пару секунд... И БАЦ! Рисуется красивая, пузатая синяя петля.
  4. Высший пилотаж UX: Если петля ушла на север, а юзер хотел на юг, он нажимает кнопку 🎲 [ Перемешать / Другой вариант ]. Линия исчезает, и рисуется совершенно новое кольцо! Юзер "крутит рулетку", пока не увидит круг, который ему визуально нравится.

3. СЕКРЕТ ДЛЯ ПРОГРАММИСТА (Как научить код "фантазировать") ​

Кажется, что сайту нужен суперкомпьютер. На самом деле у нас есть два пути: простой и очень простой.

Путь А (Встроенный в сервер): Если мы используем умный движок роутинга (например, GraphHopper или Valhalla), у них прямо "из коробки" есть функция Round Trip (Круговой маршрут). Ты просто отправляешь на сервер стартовую точку и желаемую длину distance=40000, и сервер сам возвращает готовое кольцо!

Путь Б (Фолбэк: Геометрия в 4 шага): Если наш сервер так не умеет, мы сделаем это сами на клиенте:

  1. Математика: 40 км окружность = радиус ~6.5 км.
  2. Невидимый круг: Код рисует вокруг Дома невидимый круг радиусом 6.5 км.
  3. Точки-Якоря: Код бросает на границу круга 2 фейковые точки (широким треугольником).
  4. Запрос: Просим сервер построить путь: Дом ➡️ Фейк 1 ➡️ Фейк 2 ➡️ Дом. Сервер находит реальные дороги, и мы получаем живую петлю! (Кнопка 🎲 просто бросает эти точки под другими углами).

4. Защита от "дурака" (Две главные ловушки генератора) ​

Ловушка 1: "Паук на берегу" (Точки упали в воду) ​

Проблема: Юзер живет у моря. Невидимый круг ляжет на воду. Если фейковая точка упадет в воду, сервер зависнет и выдаст "Дорог не найдено". Решение: Сделать Snap-проверку. "Эй, точка, рядом с тобой в радиусе 500м есть суша/дорога?". Если точка в болоте — код отбрасывает её и кидает новую на твердую землю.

Ловушка 2: Маршрут-"Сосиска" (Туда-обратно) ​

Проблема: В глухой деревне с одной дорогой сервер поведет юзера 20 км туда и 20 км обратно по той же дороге. Это не "кольцо"! Решение: Передать серверу параметр Пенализации (Alternative routes / Penalize used edges). Дать команду: "Избегай возвращения по той же дороге, ищи параллельные тропинки!". Маршрут получится пузатым "бубликом".

5. Идеальный GPX-файл на выходе (Заметаем следы) ​

Важнейшее правило: Эти "фейковые" точки-якоря НЕ ДОЛЖНЫ попасть в GPX-файл как Флажки (<wpt>). Если они попадут, навигатор в лесу запищит: "Вы достигли Точки №1!". Юзер увидит пустые кусты и подумает, что сайт сломался. В файле должна остаться ТОЛЬКО сплошная синяя линия пути (<trk>).

Эпики и Задачи ​

Epic 1: Геометрический Генератор (Путь Б / Fallback) ​

  • Task 1.1: Реализовать LoopGeneratorService на клиенте. Перевод дистанции (км) в радиус генерации.
  • Task 1.2: Использовать turf.destination для вычисления 2-3 фейковых якорей на заданном расстоянии под случайными углами.

Epic 2: Нативная поддержка (Путь А) ​

  • Task 2.1: Проверить API документацию текущего Routing Provider (например, OSRM Trip API или GraphHopper RoundTrip).
  • Task 2.2: Если нативная поддержка есть, передавать seed, distance и heading параметры напрямую в бэкенд по клику на 🪄 и 🎲.

Epic 3: Защита от Воды и "Сосисок" ​

  • Task 3.1 (Water Protection): Делать pre-flight запрос к /nearest API роутера для сгенерированных точек (если выбран Путь Б).
  • Task 3.2 (Sausage Protection): Настроить параметры cost (или передавать alternatives=true), чтобы штрафовать возвраты по той же улице.

Epic 4: Очистка GPX (Заметаем следы) ​

  • Task 4.1: При вызове GPX-экспортера жестко отфильтровывать Waypoints с type === 'generatedAnchor', чтобы они не попали в секцию <wpt>.