enduro-trails/docs/work-items/ET-011/02-trz.md

ТЗ: Скачивание трека из popup на карте

Work Item: ET-011 Стадия: Анализ → Architecture Автор: analyst Дата: 2026-06-03

---

1. Сводка

Добавить в существующий popup публичного GPS-трека (слой ET-008) кнопку «Скачать», которая запрашивает с сервера GPX-файл и сохраняет его в загрузки пользователя. Новый backend-эндпоинт собирает GPX 1.1 из геометрии трека в БД gps_tracks.sqlite.

2. Функциональные требования

REQ-F-01 — Кнопка «Скачать» в popup трека

В popup публичного трека (создаётся в _renderTrackPopupHtml(props), src/web/gps_tracks.js, l.463) должна появляться кнопка «Скачать».

• Иконка: download (SVG, как в sheet-route downloadGPX, l.135–137 в index.html).
• Tooltip / aria-label: «Скачать GPX».
• Размещение: в правом верхнем углу popup, рядом с названием трека, или отдельной строкой в конце popup перед источниками — на усмотрение архитектора, но всегда видна без скролла.
• Тапабельная зона: ≥ 32×32 CSS px (mobile-friendly, REQ-NF-04 ниже).

REQ-F-02 — Backend: эндпоинт скачивания

Реализовать в роутере src/api/gps_tracks/endpoint.py новый GET-эндпоинт:

GET /api/gps-tracks/{track_id}/download
GET /api/gps-tracks/{track_id}/download?format=gpx   (синоним)

Параметры:

• track_id (path, int, обязательный) — tracks.id из БД.
• format (query, optional, default=gpx) — формат файла. Допустимые значения для текущей итерации: gpx. (При закрытии Q-2 = «делаем KML» — добавится kml.)

Поведение:

• 200 + Content-Type: application/gpx+xml (для GPX) или application/vnd.google-earth.kml+xml (для KML).
• Content-Disposition: attachment; filename="<safe-name>.gpx"; filename*=UTF-8''<urlencoded-name>.gpx (RFC 5987, REQ-NF-05 ниже).
• 404, если track_id не существует.
• 400, если format не входит в whitelist.
• 403, если источник трека запрещает реэкспорт (см. REQ-F-06 и Q-1 в BRD).

REQ-F-03 — Содержимое GPX

GPX-файл должен соответствовать схеме GPX 1.1 (http://www.topografix.com/GPX/1/1) и содержать:

• Корневой <gpx> с атрибутами:
  • version="1.1"
  • creator="Enduro Trails"
  • xmlns="http://www.topografix.com/GPX/1/1"
  • xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  • xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd"
• Блок <metadata> с:
  • <name> — tracks.name или «Без названия».
  • <desc> — tracks.description (если есть).
  • <time> — tracks.created_at в ISO-8601 (если есть, иначе пропустить).
  • <author><name> — tracks.user (если есть).
  • <link href="<external_url>"><text>Источник: <source_id></text></link> — по одному <link> на каждый элемент external_urls.
  • <copyright author="Enduro Trails"><license>https://www.openstreetmap.org/copyright</license></copyright> — для OSM-источника. Для других — без <copyright> либо со ссылкой на исходный URL.
• Ровно один <trk> с:
  • <name> — tracks.name.
  • <type> — activity_type (например, enduro).
  • Ровно один <trkseg> с <trkpt lat="..." lon="..."> для каждой координаты из WKB-геометрии tracks.geom. Без <ele> и <time> (см. BRD A2).

REQ-F-04 — Имя файла

Имя файла (для Content-Disposition и filename*) формируется так:

1. Берём tracks.name. Если пустое / NULL — используем track-<id>.
2. Заменяем все недопустимые для FAT/NTFS символы (/ \ : * ? " < > |) на _.
3. Триммим до 80 символов.
4. Транслитерация не нужна — современные браузеры понимают filename*=UTF-8''… (RFC 5987).
5. Расширение: .gpx (или .kml).

Например: tracks.name = "По грязи к Чёрному озеру" → По грязи к Чёрному озеру.gpx (через filename*=UTF-8''%D0%9F%D0%BE…).

REQ-F-05 — Поведение на фронте

При клике на кнопку «Скачать»:

1. Не закрывать popup (или закрывать — на усмотрение архитектора, главное консистентно с остальными кнопками в проекте). Рекомендация: не закрывать, чтобы пользователь видел индикатор/успех.
2. Сделать GET-запрос на /api/gps-tracks/{id}/download через <a href="..." download="...">.click() (стандартный паттерн, отлично работает в desktop и mobile-браузерах) или через fetch + Blob
   • URL.createObjectURL — выбор за архитектором, см. R-1 в BRD.
3. На время запроса показать спиннер/индикатор на самой кнопке (опц.) — нужно если бэк > 200 ms. Hint: трек на 50 000 точек собирается ≈ 80–150 ms (см. NFR-01), так что индикатор большинству не нужен.
4. При ошибке (HTTP ≠ 200) — показать showToast(...) (функция уже есть в проекте) с человекочитаемым сообщением:
   • 403 → «Источник запрещает скачивание. Откройте трек на сайте источника.»
   • 404 → «Трек не найден.»
   • 5xx / network → «Не удалось скачать. Попробуйте ещё раз.»

REQ-F-06 — Защита по лицензии источника (зависит от Q-1)

Если Owner закрывает Q-1 как «только OSM»:

• Backend проверяет tracks.sources_json. Если ни одного из источников не относится к разрешённому whitelist'у (по умолчанию ["osm"]) — возвращает 403 c JSON {"detail":"source_forbidden", "external_urls":[...]}.
• Frontend в обработчике 403 показывает toast и, если есть external_urls, кнопку «Открыть на сайте источника».

Если Owner отвечает «всё разрешено» — этот REQ становится no-op (вырезать).

REQ-F-07 — Логирование

Каждое успешное скачивание логируется server-side: uvicorn access-log + (опц.) отдельная строка в stdout формата track_download id=<id> source=<sources> size_bytes=<n> ip=<remote>. Это нужно для NFR-06 (наблюдаемость).

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

REQ-NF-01 — Производительность

Сборка GPX и отдача для трека до 50 000 точек — не дольше 300 ms от запроса до начала ответа (P95 на текущем железе test-среды). Размер ответа для типичного трека 100 км / 5 000 точек — до 800 КБ (чистый XML, без gzip; ответ может быть gzip'нут средствами uvicorn).

REQ-NF-02 — Потолок размера ответа

Если число точек в треке > 200 000 (защита от patho-кейсов) — возвращать 413 Payload Too Large с сообщением «Трек слишком большой для скачивания». Реализация: проверка tracks.points_count до сборки XML.

REQ-NF-03 — Соответствие схеме GPX 1.1

Полученный файл должен проходить валидацию по схеме http://www.topografix.com/GPX/1/1/gpx.xsd без warnings/errors. Тест в tests/api/test_gps_tracks_download.py (см. test plan).

REQ-NF-04 — UX mobile

• Кнопка «Скачать» должна быть удобно тапабельной на мобильных (≥ 32×32 CSS px).
• Popup не должен «прыгать» из-за появления кнопки — высота фиксирована или растёт плавно.
• При ширине viewport < 420 px кнопка остаётся видимой (popup имеет max-width: 300px — см. gps_tracks.js l.514).

REQ-NF-05 — Заголовок Content-Disposition

Заголовок должен поддерживать UTF-8 имена через RFC 5987:

Content-Disposition: attachment; filename="track.gpx"; filename*=UTF-8''%D0%9F%D0%BE…

Параметр filename (без *) — ASCII-fallback (транслит или track-<id>.gpx).

REQ-NF-06 — Наблюдаемость

• 200/4xx/5xx ответы видны в uvicorn access-log.
• Стек-трейсы 5xx уходят в stderr (текущая практика FastAPI/uvicorn).
• Метрики (RPS / latency) — не требуются в этой итерации.

REQ-NF-07 — Безопасность

• track_id — int, парсится FastAPI, защита от SQL-инjection встроенная.
• Имя файла санитизуется (REQ-F-04) — защита от path-traversal в загрузках.
• Access-Control-Allow-Origin: * уже стоит в CORS middleware — не трогаем; iframe-embed возможен.

4. Out of scope (явно)

• KML — в backlog (см. Q-2). Если Owner закрывает Q-2 как «делаем» — REQ-F-02 расширяется (format=kml), но это не предмет данной итерации.
• Сохранение скачанного трека в IndexedDB / в sheet-gpx (как пользовательский GPX по ET-006) — отдельная фича.
• Bulk-download (несколько треков). Только один за запрос.
• Конвертация формата (waypoints, маркеры).

5. Артефакты, к которым прикасаемся

• src/web/gps_tracks.js — функция _renderTrackPopupHtml(props) и (вероятно) обработчик клика на новую кнопку.
• src/web/app.css (или gps_tracks.js inline-стили) — стиль кнопки.
• src/api/gps_tracks/endpoint.py — добавляется новый route.
• src/api/gps_tracks/db.py (возможно) — функция get_track_by_id().
• tests/api/test_gps_tracks_download.py — новые тесты (см. test plan).
• tests/web/test_gps_tracks_popup.spec.ts или аналог — UI-тесты (Playwright, см. 04b-ui-test-cases.md).
• ADR docs/work-items/ET-011/06-adr/*.md (создаст architect): про механизм отдачи (link vs blob), про обработку лицензии источника.

6. Зависимости

• Слой ET-008 «Публичные треки» уже в проде (тестовая среда). Этот work item расширяет его popup.
• БД gps_tracks.sqlite инициализируется через миграцию migrations/gps_tracks_001_init.sql — её менять не нужно (все необходимые поля уже есть: id, name, description, activity_type, user, created_at, length_m, points_count, geom, sources_json, external_urls_json).

7. Глоссарий

• Public track — публичный GPS-трек из таблицы tracks в БД gps_tracks.sqlite. Источник — OSM, EnduroRussia, Wikiloc, ttrails и т.п.
• GPX — GPS Exchange Format 1.1, XML-формат для треков и точек.
• KML — Keyhole Markup Language 2.2, XML-формат Google Earth.
• Popup — MapLibre maplibregl.Popup, всплывающее окно по клику на feature.