---
type: infra-requirements
work_item_id: ET-007
title: "Инфраструктурные требования — ET-007: Спутниковая карта (Схема / Спутник)"
version: 1
status: approved
created_at: 2026-05-31
authors:
  - "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` не требуется.
