📖 Автоматический круговой генератор маршрутов (Round-Trip Loop)

🧠 1. Анатомия инструмента и Логика движка (Tool Anatomy & Engine Logic)

• Что это такое? Круговой генератор маршрутов решает проблему планирования в незнакомых локациях. Когда велосипедист хочет проехать определенное расстояние (например, 20 км), начав и закончив поездку у отеля или дома, инструмент за один клик находит безопасные, непересекающиеся дороги и строит замкнутый цикл без необходимости ручной отрисовки.
• Активация: Кликнуть по значку круга со стрелкой (Loop Generator / Круговой маршрут) в боковой панели планирования или нажать кнопку в меню быстрого доступа.
• Физика интерфейса (Basic UI Physics):
  • Зеленый стартовый маркер (Origin): Единственная точка, которую ставит пользователь. Она служит и началом, и концом пути.
  • Синяя замкнутая линия-петля: Итоговый круговой трек, рассчитанный по реальным дорогам.
  • Боковая панель параметров: Содержит поле ввода дистанции (в километрах) и круговой переключатель направлений (Север, Восток, Юг, Запад, Случайно).
• 

Подробная инструкция для Арт-директора: Сделать снимок экрана боковой панели параметров кругового генератора с введенным значением 20 км и проложенной красивой замкнутой петлей на карте.

🎬 2. Матрица сценариев (Все комбинации взаимодействия)

Сценарий А: Генерация случайной петли заданной длины

• Действие пользователя: Поставить стартовый маркер у парка, в боковой панели ввести дистанцию 30 km, выбрать направление Случайно (Random) и нажать кнопку «Сгенерировать петлю».
• Реакция системы (Магия): Планировщик за полсекунды вычисляет траекторию, прокладывая замкнутый маршрут длиной 29.4 km. На карте отображается аккуратная петля, обходящая загруженные магистрали.
• Физика процесса («Почему»): Движок usePlannerStore рассчитывает три промежуточные виртуальные вершины на расстоянии около 1/3 целевой дистанции от старта, расположенные под углами 0°, 120° и 240° (для создания треугольной петли), затем отправляет их на Hono API /api/routing/calculate для прокладки трека.
• 

Подробная инструкция: Чертеж или схема распределения промежуточных расчетных вершин треугольной петли вокруг точки старта на карте.

Сценарий Б: Генерация с привязкой к направлению

• Действие пользователя: Выбрать направление Север (North), ввести дистанцию 15 km и нажать генерацию.
• Реакция системы (Магия): Сгенерированная петля вытягивается строго на север от стартовой точки, проходя через северные районы или лесопарки, и возвращается обратно в старт с южной стороны.
• Физика процесса («Почему»): Алгоритм генерирует промежуточные точки со смещением вектора угла в диапазоне от -45° до +45° относительно северного направления, ограничивая область поиска дорог северным сектором.
• 

Подробная инструкция: Снимок экрана с круговым маршрутом, явно смещенным в северную часть относительно зеленой точки старта.

Сценарий В: Обход пространственных барьеров (Obstacle Bypassing)

• Действие пользователя: Поставить маркер на берегу моря, выбрать направление Запад (West) (в сторону воды), ввести дистанцию 10 km и запустить генерацию.
• Реакция системы (Магия): Алгоритм автоматически разворачивает поиск на восток (вглубь суши) и строит петлю вдоль побережья, корректируя маршрут.
• Физика процесса («Почему»): Если BRouter возвращает ошибку отсутствия дорог на первых расчетных координатах сегмента, система отбрасывает этот вариант, сдвигает угол поиска на 90° или 180° и перезапускает генерацию по сухопутной сетке.
• 

Подробная инструкция: Карта, показывающая береговую линию и сгенерированную петлю, которая идет строго по суше, обходя водную преграду.

🚨 3. Защита от дурака и Крайние случаи (QA Guide)

• Деструктивный сценарий: Попытка сгенерировать петлю экстремально малой длины (< 2 км) или гигантской дистанции (> 200 км).
• Реакция UI: Поля ввода снабжены жесткими валидаторами Zod. При вводе некорректного числа кнопка «Сгенерировать» блокируется, а граница поля подсвечивается ярко-красным цветом.
• Точный текст ошибки (Toast): При попытке принудительного сохранения невалидного значения через клавиатуру: "🛡️ Дистанция кругового маршрута должна быть в диапазоне от 2 до 200 км."
• 

Подробная инструкция: Скриншот поля ввода дистанции с красной рамкой ошибки и текстом предупреждения на панели.