📖 Путевые точки на карте (Points of Interest - POI)

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

• Что это такое? Путевые точки интереса (POI) решают проблему информирования о ключевых объектах велоинфраструктуры вдоль пути. Велосипедисту в походе жизненно важно знать, где можно набрать воду, разбить палатку, перекусить или отремонтировать велосипед. POI позволяют наносить независимые от трека ориентиры, экспортировать их в навигаторы и делиться с другими.
• Активация: Правым кликом в любом месте карты и выбором пункта «Создать точку» (Create POI) или кликом по значку булавки (📍 Add POI) в панели инструментов с последующим указанием координат на холсте.
• Физика интерфейса (Basic UI Physics):
  • 💧 Голубая капля: Водный источник (родник, питьевой кран).
  • ⛺ Зеленая палатка: Место для стоянки, кемпинг или турприют.
  • 📸 Желтый фотоаппарат: Красивая панорама или смотровая площадка.
  • 🛒 Красная вилка с ножом: Пункт питания (кафе, сельский магазин).
  • 🔧 Серый ключ: Велосипедная мастерская или общественная стойка с инструментами.
  • При клике по маркеру открывается белая всплывающая карточка с названием, описанием, тегами и кнопкой удаления.
• 

Подробная инструкция для Арт-директора: Сделать снимок экрана открытой карточки POI на карте (например, Кемпинг) с формой ввода имени и выбором категорий.

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

Сценарий А: Размещение глобального ориентира (Water Source Placing)

• Действие пользователя: Нажать 📍 Add POI, кликнуть у берега лесного ручья, в открывшейся форме выбрать иконку Вода (Water), ввести название «Чистый ручей», нажать кнопку «Сохранить».
• Реакция системы (Магия): Иконка с каплей мгновенно появляется на карте. Точка добавляется в общий список путевых ориентиров в боковой панели.
• Физика процесса («Почему»): Клиент считывает координаты клика, упаковывает их в Zod-валидированный объект и отправляет POST /api/poi на Hono-сервер. Запись сохраняется в базе данных pois, привязываясь к аккаунту пользователя.
• 

Подробная инструкция: Нанесение точки водного источника с каплей на берегу лесной реки на карте.

Сценарий Б: Двухэтапное безопасное удаление POI (Double-Confirmation Delete)

• Действие пользователя: Кликнуть по существующему маркеру кемпинга на карте. В открывшемся попапе нажать красную кнопку «Удалить» один раз. Подождать 3 секунды, не кликая повторно.
• Реакция системы (Магия): После первого клика кнопка окрашивается в ярко-красный цвет и меняет текст на «Подтвердить удаление». Через 3 секунды бездействия кнопка плавно возвращается к исходному нейтральному виду. Точка кемпинга остается на карте.
• Физика процесса («Почему»): Таймер обратного отсчета в хуке MapPopups.tsx сбрасывает локальное состояние подтверждения isConfirming в false по истечении 3000 миллисекунд, страхуя пользователя от случайной потери ценной отметки.
• 

Подробная инструкция: Карточка POI с кнопкой удаления в активном состоянии «Подтвердить удаление» красного цвета.

Сценарий В: Поиск и фильтрация ориентиров в каталоге

• Действие пользователя: Открыть боковую панель POI, ввести в поиске «Родник» и отметить галочкой категорию «Вода».
• Реакция системы (Магия): В списке мгновенно остаются только те маркеры, в имени которых есть слово «Родник» и категория которых совпадает с водным фильтром. Остальные иконки на карте временно становятся полупрозрачными.
• Физика процесса («Почему»): Zustand-хранилище usePoiStore применяет реактивные фильтры к исходному массиву pois в оперативной памяти клиента, скрывая неподходящие слои карты MapLibre GL.
• 

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

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

• Деструктивный сценарий: Серия сверхбыстрых многократных кликов по кнопке «Сохранить» при отправке формы POI в условиях медленного интернета (сетевой флуд).
• Реакция UI: Кнопка сохранения блокируется после первого же клика, переходя в неактивное состояние (disabled) и меняя надпись на «Сохранение...». Дублирующиеся сетевые транзакции исключены.
• Точный текст ошибки (Toast): При успешном создании точки интереса: "🛡️ Точка интереса успешно создана."
• 

Подробная инструкция: Снимок экрана заблокированной кнопки отправки формы со статусом сохранения.