# Map Template

`Map Page 0.1.0` — первый готовый функциональный шаблон NDC Module Foundry. Он описывает пространственный интерфейс через стабильные доменные сущности, а не через API конкретного renderer.

## Границы ответственности

- Page Template владеет компоновкой страницы, Inspector, Toolbar, Assistant entry point, слотами данных и системными действиями.
- Map Scene Fixture задаёт минимальный проверочный набор пространственных сущностей и состояний.
- Application Manifest фиксирует экземпляр страницы, выбранный Design Profile и feature visibility.
- Platform capability binding связывает слоты шаблона с scoped data products через Foundry runtime BFF.
- Renderer adapter преобразует provider-neutral scene в Cesium или другой поддерживаемый renderer.

Engine/NDC остаётся средой создания и исполнения автоматизаций. Он не является владельцем визуального языка Map Template и не экспортирует в Studio внутренние Cesium objects.

## Зафиксированные сущности v0.1

- viewport и базовые capabilities;
- base/buildings/grid layers;
- planet-scale grid с LOD bands;
- place targets;
- moving objects и traces;
- универсальные pins и labels;
- rail/metro/stop/terminal stations;
- routes и track segments;
- polygon/multipolygon zones;
- selection;
- ready/loading/empty/stale/error/offline states.

Размеры и внешний вид разновидностей сущностей задаются ссылками на `styleProfiles`. Это позволяет одному доменному типу иметь разные подтверждённые варианты, не создавая новый renderer-specific тип.

## Acceptance fixtures

- `registry/fixtures/map/map-operational-v0.1.json` — минимальная рабочая сцена с сеткой, транспортом, станциями, маршрутом, железнодорожным путём, зоной и selection.
- `registry/fixtures/map/map-empty-offline-v0.1.json` — отсутствие provider/live data без разрушения shell и управляющих действий.

Fixtures малы и детерминированы. Большие геоданные, tile cache, credentials и реальные streaming snapshots в репозиторий гайдлайнов не входят.

## Sandbox credit overlay

Во внутренней sandbox-сборке Map Page временно скрывает визуальный credit overlay renderer, потому что он перекрывает рабочую композицию во время настройки шаблона. Метаданные provider attribution не удаляются из runtime. Перед любым внешним, пользовательским или коммерческим развёртыванием overlay должен быть возвращён в соответствии с условиями выбранного provider. Это зафиксированный технический долг, а не правило production-интерфейса.

## Cesium adapter 1.143

Текущий reference adapter использует CesiumJS `1.143.0`. Он загружается отдельным lazy chunk только при открытии Map Page и преобразует fixture в реальные Cesium entities: points, labels, routes, tracks, zones и selection. Без настроенного ion gateway используется development fallback `WGS84 globe + OpenStreetMap imagery`.

Server-side runtime contract:

- `GET /api/map/runtime-config` сообщает версию renderer и readiness возможностей, но не возвращает master token;
- `GET /api/map/ion/assets/:assetId/endpoint` разрешает только allowlisted assets и возвращает public provider URL без credential; private Gateway добавляет asset credential только к своему upstream request;
- `CESIUM_ION_TOKEN` передаётся только private Platform Map Gateway через deployment environment/secret, не в Foundry;
- `CESIUM_ION_ASSET_ALLOWLIST` ограничивает terrain/buildings/Gaussian assets;
- production endpoint переезжает в `platform/services/map-gateway`.

Development и production gateway позволяют проверить World Terrain и 3D Buildings, не сериализуя никакой Cesium/Bing credential во frontend.

## TileCache boundary

Runtime tile cache не является исходным кодом и не хранится в Git или Docker image layer. Production `map-gateway` использует NAS bind directory `/volume1/docker/nodedc-platform/map-gateway/live-tile-cache` и поддерживает:

- cache-first read/write и явный live-refresh;
- нормализацию cache key без credentials;
- upstream allowlist и SSRF protection;
- ограничения размера объекта и общего объёма;
- append-only no-overwrite по умолчанию, явный refresh viewport, stats, health и наблюдаемость;
- отдельный export/import версионируемых seed snapshots при необходимости.

Существующий Engine cache используется как donor поведения, но его runtime-файлы не копируются в Studio.

## Следующие контракты

`registry/schemas/map-lod-policy-v0.1.schema.json` и `registry/fixtures/map/map-lod-policies-v0.1.json` фиксируют первый provider-neutral LOD/visibility contract. Единственная метрика v0.1 — расстояние камеры в метрах; интервалы полуоткрытые `[minRange, maxRange)`, а `hysteresisRatio` предотвращает дрожание на границах. Renderer переводит эту политику в собственный API, но не меняет её смысл.

Дальше:

1. уточнить единый Label Style contract и варианты размеров уже на живой сцене;
2. спроектировать batching/instancing contract для больших потоков объектов и геозон;
3. вынести development gateway в `platform/services/map-gateway` и подключить persistent cache;
4. добавить реальный Gaussian Splat 3D Tiles acceptance asset;
5. расширить entity-stream adapter с `points` на traces, routes и zones;
6. оформить renderer adapter capability matrix для Cesium и будущих providers.

## Live data-product runtime

`Map Page` хранит только provider-neutral binding: `dataProductId`, approved
semantic types, field projection и `slotId` (`points` для live point entities).
При открытии Application page browser делает same-origin запрос к Foundry:

```text
Application/Page/Binding → Foundry BFF → External Data Plane snapshot/history → SSE patch
```

Foundry сопоставляет target с opaque reader grant в закрытом persistent
runtime. При первом exact consumer apply Foundry генерирует token локально и
передаёт EDP только его digest в запросе с отдельной service-подписью; EDP сам
разрешает unique active writer scope и fail-closed отклоняет ambiguity. Legacy
root-owned deployment directory используется только как совместимый fallback.
Browser, manifest и Cesium adapter не получают provider
endpoint, tenant/connection scope, reader token или raw provider payload.
Сначала server-owned Foundry consumer коммитит snapshot, затем применяет patch
events с exact cursor и только после commit делает fan-out всем viewers. При
пропуске cursor требуется snapshot rebase; несколько вкладок одного binding не
создают несколько upstream EDP subscriptions. Timeline использует provider-neutral
history route (`from/to/resolution/sourceIds/cursor`) через тот же BFF и не
занимает общую L2 execution queue. Renderer держит отдельный `CustomDataSource`
на binding и обновляет stable entity id без пересоздания viewer. Sampling и
retention остаются политикой Data Plane, а не Map Template.