---
type: brd
work_item_id: ET-007
title: "BRD: Спутниковая карта (Схема / Спутник)"
version: 2
status: draft
created_at: 2026-05-31
updated_at: 2026-05-31
changelog:
  - "v2 (2026-05-31): code-review fix (12-review.md P1-3) — митигация риска hillshade приведена в соответствие с TRZ/ADR/AC: авто-выключение не вводится."
authors:
  - "agent:analyst"
---

# BRD — ET-007: Спутниковая карта (Схема / Спутник)

## 1. Цель

Дать пользователю возможность одним кликом переключать подложку карты
между «Схемой» (текущая OSM-схема) и «Спутник» (растровые снимки
поверхности Земли). Спутниковая подложка помогает увидеть реальный
рельеф и поверхность маршрута — лес/поле/брод/каменистый участок — до
выезда.

## 2. Контекст

- Сейчас в приложении используется единственная подложка — OSM-растр,
  стилизованный для «Схемы» в двух темах (`style.json`,
  `style-dark.json`). Спутникового слоя нет.
- В фазе PH-5 Redesign уже была введена тёмная/светлая тема — но
  «тема» относится к стилизации (контрасты, насыщенность), а не к
  природе подложки.
- Эндуро-маршруты часто проходят вне дорог OSM (бездорожье, броды,
  лесные участки). Спутник критичен для разведки.
- Все клиентские модули (`app.js`, `units.js`, `gpx.js`) уже умеют
  переживать `map.setStyle()` через `rebuildMapOverlays()` — это
  опорная точка для будущей реализации.

## 3. Scope

### In scope

| #     | Функция                                                                              |
| ----- | ------------------------------------------------------------------------------------ |
| F-01  | Переключатель «Схема / Спутник» в UI (segmented control)                             |
| F-02  | Спутниковая подложка как новый raster-источник (бесплатный, без API-ключа)           |
| F-03  | В режиме «Спутник» — скрыта OSM-схема, показаны спутниковые тайлы                    |
| F-04  | Все надстройки (грунтовки, тропы, POI, hillshade, TRI, маршрут, GPX) поверх спутника |
| F-05  | Сохранение выбора в `localStorage` (ключ `map-base-layer`)                           |
| F-06  | Восстановление выбора при загрузке страницы и при смене темы                         |
| F-07  | Корректное отображение атрибуции спутниковых тайлов                                  |
| F-08  | Сохранение всех пользовательских слоёв (роутинг, GPX, recon) при переключении        |

### Out of scope

- Кэширование спутниковых тайлов (offline / PWA — это PH-9).
- Динамический выбор провайдера спутниковых тайлов в UI.
- Гибридный режим «Спутник + подписи дорог OSM поверх».
- Самостоятельный хостинг спутниковых тайлов (юридические/трафик-риски).
- Изменение базовой карты для расчёта маршрутов (роутинг по-прежнему OSRM).
- Авто-переключение Схема/Спутник в зависимости от зума.

## 4. Метрики успеха

| Метрика                  | Критерий                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------- |
| Время переключения       | ≤ 500 мс от клика до первой видимой спутниковой плитки                                |
| Сохранение состояния     | Выбор подложки сохраняется после reload, смены темы, смены слоёв terrain              |
| Совместимость со слоями  | Грунтовки, тропы, POI, маршрут OSRM, GPX-треки, hillshade, TRI видны и поверх спутника |
| Совместимость с темой    | Переключение тёмной/светлой темы не сбрасывает режим «Спутник»                         |
| Атрибуция                | На карте видна корректная атрибуция провайдера спутника                                |
| Не ломает существующее   | Все режимы (роутинг, разведка, красивый маршрут, GPX, линейка) работают как прежде     |

## 5. Риски

| Риск                                                                                              | Вероятность | Влияние | Митигация                                                                                                                  |
| ------------------------------------------------------------------------------------------------- | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| Провайдер спутниковых тайлов закроет доступ / введёт лимит / потребует API-ключ                    | Средняя     | Высокое | Зафиксировать конкретного провайдера в ADR; предусмотреть точку расширения для альтернативного провайдера (несколько URL)  |
| Спутниковая подложка медленно грузится → пользователь видит «дыры»                                 | Высокая     | Среднее | Использовать background-цвет (тёмно-серый) под спутником; OSM-схема остаётся как fallback в случае ошибки загрузки тайлов  |
| Цвет грунтовок и троп плохо виден на спутниковой подложке                                         | Высокая     | Среднее | TRZ: на режиме «Спутник» включается обводка (halo) у линий грунтовок и троп — по аналогии с подписями POI                  |
| Hillshade поверх спутника даёт некрасивое наложение (двойное затенение рельефа)                    | Средняя     | Низкое  | Hillshade продолжает работать поверх спутника как и поверх схемы — авто-выключение не вводится (TRZ §1 REQ-F-04, ADR-004 §«Контекст 1.5»); визуальная проверка — UI-тест AC-04 «Hillshade поверх спутника» |
| Юридические ограничения на использование стороннего провайдера спутниковых тайлов                  | Низкая      | Высокое | В ADR указать выбранного провайдера с лицензией, разрешающей использование без API-ключа (Esri World Imagery, ArcGIS)      |
| Регресс UI на мобильных устройствах из-за нового переключателя                                    | Низкая      | Среднее | UI-тест-кейсы (04b) для desktop и mobile viewport                                                                          |
| Конфликт с уже сохранёнными localStorage-значениями старых версий                                 | Низкая      | Низкое  | Использовать новый ключ `map-base-layer`, default = `schematic`                                                            |

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

- Только фронтенд — backend изменений не требуется.
- MapLibre GL JS 4.7.0 (уже подключен).
- Внешний провайдер спутниковых тайлов (выбор и фиксация — в ADR).
- Сетевое подключение клиента к серверу провайдера.

## 7. Связь с roadmap

- Фаза PH-5 Redesign — тёмная тема и mobile UI уже сделаны; ET-007
  встраивается в эту же панель «Рельеф / Слои» (одна точка управления
  визуальными слоями карты).
- Фаза PH-9 PWA — кэширование спутниковых тайлов оффлайн — будет
  планироваться отдельно, ET-007 закладывает архитектурную основу
  (источник тайлов, точка переключения).