claude-bot
1984b0bde6
All checks were successful
12-review.md (REQUEST_CHANGES, attempt 2/3) flagged 6 must-fix items
in the analysis/architecture artefacts plus matching bugs that had
already leaked into the committed implementation. This patch lands
both: documents corrected, code aligned with corrected specs, tests
updated.
P1-1: TRZ/ADR/Data/Risks referenced fictional layer ids
(`trails-grade1..5-halo-satellite`, `paths-bridleway-halo-satellite`).
Actual style*.json has only `trails-track-halo-satellite` and
`trails-path-bridleway-halo-satellite`; grade differentiation lives
inside one `match` expression on `tracktype` within `trails-track`.
Docs rewritten to operate on real ids.
P1-2: POI labels contrast was broken — spec changed only halo-color
to black, leaving `text-color: #333333` (light theme baseline)
unreadable over the new black halo. Code+docs now switch BOTH
`text-color` (-> `#ffffff` on satellite) AND halo together, with
per-theme baselines (`#333333` light / `#e0e0e0` dark) restored on
return to Schematic.
P1-3: BRD §5 hillshade risk said «hillshade auto-disabled on
satellite», contradicting TRZ/ADR/AC. BRD wording aligned: hillshade
keeps working over satellite; visual check is AC-04.
P1-4: background-color had four divergent sources (`#1a1a1a`,
`#2a2a2a`, `#1a1a2e`, `#f0ede6`), incl. an inverted-theme typo and a
baseline `#1a1a1a` that didn't match the actual `style-dark.json:28`
value `#1a1a2e`. Settled on ADR-004's single-constant model: `#2a2a2a`
on satellite for both themes; on Schematic restore per-theme baselines
`#f0ede6` (light) / `#1a1a2e` (dark). `_applyBackgroundForSatellite`
fixed accordingly.
P1-5: app.js already had `layerState.basemap` and `toggleLayer
('basemap')` (legacy «Базовая карта» switch). Neither TRZ nor ADR
specified the interaction. Added save&restore contract: on entering
Satellite save `layerState.basemap` to `_savedBasemapState` and
force-hide `osm-base`; on returning to Schematic restore osm-base
visibility from the saved value. CSS hook `body.satellite-active
#btn-basemap { display:none }` keeps the user from trying to enable
a hybrid mode (out of scope, BRD §3). TRZ §5.6, ADR-004 §8.
P1-6: `restoreTrailsState()` and `onTrailsCheckbox()` only managed
visibility of `trails-track` / `trails-path-bridleway`, leaving
their halo-underlay siblings as «phantom» halos when the user
unchecked grunты/тропы under Satellite. Introduced
`_applyTrailHaloVisibility(map, base)` reading checkbox state from
DOM; called from `onTrailsCheckbox`, `restoreTrailsState`, and both
branches of `applyBaseLayer`. Rule: halo visible ⇔ (base ===
satellite) AND (checkbox ON). TRZ §5.7, ADR-004 §9.
Docs bumped: BRD v2, TRZ v2, AC v2, Data v2, Risks v2; ADR-004
получает «Ревизии»-секцию (status remains accepted — only editorial
fixes, no decision change).
Tests:
- tests/unit/base_layer.test.js: rewritten 2 background-color
assertions (#1a1a1a expectation removed), added 6 new tests for
P1-2 / P1-4 (POI text-color per-theme baselines, single satellite
bg #2a2a2a, baseline restore on Schematic).
- All 33 JS unit tests + 22 pytest static checks green.
- Full pytest suite: 76 passed (excluding pre-existing
shapely-import skipped collection in tests/unit/test_health.py).
Refs: ET-007
Review: docs/work-items/ET-007/12-review.md (P1-1..P1-6)
ADR: docs/work-items/ET-007/06-adr/ADR-004-satellite-base-layer.md (rev. 2026-05-31)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
101 lines
9.7 KiB
Markdown
101 lines
9.7 KiB
Markdown
---
|
||
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 закладывает архитектурную основу
|
||
(источник тайлов, точка переключения).
|