enduro-trails/docs/work-items/ET-007/07-infra-requirements.md

type, work_item_id, title, version, status, created_at, authors

type	work_item_id	title	version	status	created_at	authors
infra-requirements	ET-007	Инфраструктурные требования — ET-007: Спутниковая карта (Схема / Спутник)	1	approved	2026-05-31	agent:architect

Инфраструктурные требования — ET-007

1. Резюме

ET-007 — изменение исключительно фронтенда: src/web/index.html, src/web/app.js, src/web/app.css, src/web/style.json, src/web/style-dark.json. Новой инфраструктуры, новых контейнеров, новых портов и серверной конфигурации не требуется. Документ зафиксирован для полноты work-item и явно подтверждает отсутствие инфра-воздействия (см. 06-adr/ADR-004-satellite-base-layer.md).

2. Контейнеры и сервисы

Аспект	Требование
Новые контейнеры	Нет
Изменения существующих сервисов (api, osrm, nginx)	Нет
Изменения docker-compose.yml	Нет
Изменения Dockerfile	Нет — все правки попадают в образ через уже существующий COPY src/web/ ./src/web/
Изменения подключения скриптов в index.html	Нет новых <script>; добавляется только разметка попапа и обработчики
Перезапуск backend / OSRM	Не требуется
Простой (downtime)	Отсутствует — изменение только в статике фронтенда

3. Сеть

Аспект	Требование
Новые серверные порты	Нет
Изменения reverse proxy (nginx, /enduro/)	Нет
Новые внутренние DNS-записи	Нет
Новые исходящие сетевые вызовы из браузера клиента	Да — GET https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x} (HTTPS, без авторизации, raster PNG/JPEG ≈ 30–80 КБ на плитку). Запросы инициируются только при активном режиме «Спутник» (лениво — см. ADR-004 §5)
Серверный трафик	Не меняется — спутниковые тайлы идут напрямую браузер ↔ Esri, не через mva154

3.1 Корпоративные/DNS-фильтры

Часть пользователей может работать в сетях, блокирующих arcgisonline.com (анти-трекинг-DNS, корпсети). Поведение в этом случае задокументировано в TRZ §1 REQ-F-08: MapLibre показывает прозрачные плитки поверх фона #2a2a2a; пользователь возвращается на «Схему» вручную. Никаких серверных обходов или прокси через /enduro/ не закладывается.

3.2 CSP-заголовок

В проекте сейчас CSP не задаётся (подтверждено в ET-006 07-infra-requirements.md §4). Если CSP будет введён в будущем, директива img-src должна включать https://server.arcgisonline.com (а также уже используемые https://tile.openstreetmap.org и data:). На данном этапе никаких заголовков ET-007 не вводит.

4. Хранилища данных

Аспект	Требование
Изменения схемы SQLite / Spatialite	Нет
Миграции БД (migrations/)	Нет
Серверное хранилище состояния	Нет
Клиентское хранилище	localStorage, единственный ключ map-base-layer, значения "schematic" | "satellite", ≤ 16 байт
Кэширование спутниковых тайлов	Только штатный HTTP-кэш браузера. Самостоятельный offline-кэш (Service Worker, IndexedDB) — out of scope, относится к PH-9 (см. BRD §3)

Подробности по данным — 08-data-requirements.md.

5. Конфигурация и секреты

Аспект	Требование
Новые переменные окружения	Нет
Новые секреты / API-ключи	Нет — выбран провайдер без API-ключа (см. ADR-004 §1, BRD F-02)
Изменения конфигурации FastAPI / uvicorn	Нет
Изменения конфигурации OSRM	Нет

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

Аспект	Требование
Новые npm / Python-пакеты	Нет
Версия MapLibre GL JS	Без изменений (4.7.0)
Новые self-hosted сервисы	Нет
Новые третьи стороны во время выполнения	Да — server.arcgisonline.com (Esri ArcGIS Online, World Imagery). Юридическое основание: бесплатное использование с атрибуцией для некоммерческой / demo-разработки; атрибуция выводится автоматически MapLibre при активном source. Зафиксировано в docs/architecture/README.md §«Внешние тайл-провайдеры»
Альтернативный провайдер (fail-over)	Не закладывается; точка расширения — один объект source-spec в applyBaseLayer()

7. Сборка и деплой

• Pipeline: существующий Gitea Actions без изменений (make lint
  • make test + make build). ESLint автоматически покрывает правки в app.js. Бэкенд-тесты (pytest) ET-007 не затрагивает.
• Артефакт: статические ассеты фронтенда (src/web/). Никаких новых файлов — модифицируются существующие.
• Деплой: стандартный — make deploy-test → docker compose up -d на mva154. Время простоя: 0 (только перевыкладка статики).
• Smoke-проверка после деплоя на https://openclaw.mva154.duckdns.org/enduro/:
  1. Открыть карту, открыть попап «Рельеф».
  2. Убедиться, что виден переключатель «Подложка [Схема][Спутник]».
  3. Переключить на «Спутник» — увидеть растровые снимки и атрибуцию Esri в правом нижнем углу.
  4. Перезагрузить страницу — режим «Спутник» сохранён.
  5. Переключить тёмную/светлую тему — режим «Спутник» сохранён, слои не исчезли.

8. Rollback

• План отката: обратный коммит (revert) и повторный docker compose up -d. Времени отката ≈ 1–2 минуты (пересборка Docker-образа со статикой).
• Серверного состояния / миграций / графов, которые требуется отдельно откатывать, нет.
• Сохранившиеся localStorage-значения у пользователей. После отката ключ map-base-layer остаётся в localStorage, но игнорируется старым кодом — безвреден. Принудительная очистка не требуется.

9. Ресурсы (CPU / RAM / диск)

• Сервер mva154: воздействие отсутствует. Спутниковые тайлы идут напрямую от Esri к браузеру; mva154 не проксирует, не кэширует, не логирует их.
• Клиент-браузер: при активном «Спутник» — дополнительные растровые загрузки 30–80 КБ × число видимых плиток (типично 10–30 плиток на viewport). Это сопоставимо со стоимостью текущего OSM-слоя и не создаёт регрессий по памяти/CPU.

10. Наблюдаемость

• Новые серверные метрики, логи и алерты не требуются.
• Поведение проверяется автотестами (UI/e2e) по плану 04-test-plan.yaml и 04b-ui-test-cases.md.
• Серверные логи /enduro/ дополнений не получают — все обращения к Esri идут с браузера, минуя mva154.

11. Влияние на C4 / архитектурную документацию

Состав внутренних компонентов системы (Frontend, Backend, Tile Server, OSRM, БД) не меняется. Меняется только перечень внешних зависимостей в выполнении: добавляется Esri World Imagery как второй внешний raster-tile провайдер наряду с уже используемым tile.openstreetmap.org.

В репозитории нет файлов c4-*.mmd — описание архитектуры текстовое в docs/architecture/README.md. ET-007 обновляет этот документ: добавляется раздел/строка «Внешние тайл-провайдеры» со списком из двух провайдеров и условием активации каждого.

12. Вывод

Инфраструктурных, сетевых, конфигурационных, серверных и БД-изменений на стороне mva154 нет. Единственное архитектурное расширение — новая клиентская зависимость от внешнего raster-tile провайдера (Esri World Imagery), активируемая лениво и только при явном пользовательском выборе режима «Спутник». Деплой штатный, эскалация arch:major-change не требуется.