feat(map): add persistent gateway and ontology package

infra/.env.example

@@ -78,3 +78,25 @@ AI_WORKSPACE_HUB_HOST_BIND=127.0.0.1:18081
 AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub
 AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru
 AI_WORKSPACE_HUB_FALLBACK_URLS=
+
+# map gateway — keep the actual ion token only in local/staging environment files or Docker secrets.
+# Never copy it into workflow metadata, Git, frontend code, or a runtime cache key.
+MAP_GATEWAY_HOST_BIND=127.0.0.1:18103
+MAP_GATEWAY_ALLOW_ANONYMOUS=true
+MAP_GATEWAY_CORS_ORIGIN=http://127.0.0.1:3333,http://localhost:3333
+MAP_GATEWAY_UPSTREAM_ALLOWLIST=api.cesium.com,assets.ion.cesium.com,tile.openstreetmap.org,dev.virtualearth.net,ecn.t0.tiles.virtualearth.net,ecn.t1.tiles.virtualearth.net,ecn.t2.tiles.virtualearth.net,ecn.t3.tiles.virtualearth.net
+# Imported Engine imagery is selected through the explicit offline cache
+# profile, not through a global host-side block.
+MAP_GATEWAY_LEGACY_CACHE_HOSTS=
+# Leave empty unless the provider/data licence explicitly permits disconnected/offline use.
+MAP_GATEWAY_OFFLINE_PROVIDER_ALLOWLIST=
+MAP_GATEWAY_UPSTREAM_TIMEOUT_SECONDS=30
+CESIUM_ION_TOKEN=
+CESIUM_ION_ASSET_ALLOWLIST=1,2,96188
+MAP_CACHE_MODE=readwrite
+# Mutable cache is mounted at /var/lib/nodedc-map-live-cache by compose.
+# MAP_OFFLINE_SNAPSHOT_DIR is intentionally wired by compose as a read-only
+# imported Engine snapshot; never place secrets or the live cache there.
+MAP_CACHE_MAX_MB=20480
+MAP_CACHE_MAX_OBJECT_MB=128
+MAP_CACHE_DEFAULT_TTL_SECONDS=604800

infra/README.md

@@ -6,6 +6,7 @@
 - reverse proxy;
 - локальные домены;
 - shared env examples;
+- Map Gateway с persistent TileCache;
 - будущие docker compose файлы.
 
 Первый local dev слой проксирует текущие локальные приложения без физического переноса репозиториев:
@@ -70,10 +71,26 @@ docker compose --env-file infra/.env -f infra/docker-compose.dev.yml ps
 curl -I -H 'Host: auth.local.nodedc' http://127.0.0.1/
 curl -I -H 'Host: launcher.local.nodedc' http://127.0.0.1/
 curl -I -H 'Host: task.local.nodedc' http://127.0.0.1/
+curl http://127.0.0.1:18103/healthz
 ```
 
 Generated Authentik bootstrap credentials are stored only in `infra/.env`.
 
+## Map Gateway и offline TileCache
+
+`map-gateway` добавлен как общий платформенный сервис на `127.0.0.1:18103`. Его mutable live-cache монтируется как внешний named Docker volume `nodedc-platform_map-live-tile-cache`; offline snapshot — как `nodedc-platform_map-offline-snapshot`. Они не пишутся в `platform/`, не попадают в Git и не включаются в Docker image.
+
+Оба тома намеренно объявлены `external`: `docker compose down -v` не должен уничтожать уже записанные тайлы. На чистой машине они создаются один раз до первого запуска:
+
+```bash
+docker volume create nodedc-platform_map-live-tile-cache
+docker volume create nodedc-platform_map-offline-snapshot
+```
+
+Очистка кэша — только осознанной командой `docker volume rm nodedc-platform_map-live-tile-cache` при остановленном Gateway.
+
+Для реального ion terrain/buildings положите `CESIUM_ION_TOKEN` только в неотслеживаемый `infra/.env` или deployment secret. Studio получает asset-scoped endpoint token, а master token остаётся внутри Gateway. Детали API, cache modes и production access boundary описаны в `services/map-gateway/README.md`.
+
 5. Bootstrap local Authentik groups and OIDC applications:
 
 ```bash

infra/docker-compose.dev.yml

@@ -19,6 +19,8 @@ services:
         condition: service_started
       ai-workspace-assistant:
         condition: service_started
+      map-gateway:
+        condition: service_healthy
     extra_hosts:
       - "host.docker.internal:host-gateway"
 
@@ -183,6 +185,51 @@ services:
     ports:
       - "${AI_WORKSPACE_HUB_HOST_BIND:-127.0.0.1:18081}:18081"
 
+  map-gateway:
+    image: nodedc/map-gateway:local
+    build:
+      context: ../services/map-gateway
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+      PORT: 18103
+      CESIUM_ION_TOKEN: ${CESIUM_ION_TOKEN:-}
+      CESIUM_ION_ASSET_ALLOWLIST: ${CESIUM_ION_ASSET_ALLOWLIST:-1,2,96188}
+      MAP_GATEWAY_UPSTREAM_ALLOWLIST: ${MAP_GATEWAY_UPSTREAM_ALLOWLIST:-api.cesium.com,assets.ion.cesium.com,tile.openstreetmap.org,dev.virtualearth.net,ecn.t0.tiles.virtualearth.net,ecn.t1.tiles.virtualearth.net,ecn.t2.tiles.virtualearth.net,ecn.t3.tiles.virtualearth.net}
+      # Offline access is selected explicitly with the cache profile, rather
+      # than treating live Bing tile hosts as legacy providers globally.
+      MAP_GATEWAY_LEGACY_CACHE_HOSTS: ${MAP_GATEWAY_LEGACY_CACHE_HOSTS:-}
+      MAP_GATEWAY_OFFLINE_PROVIDER_ALLOWLIST: ${MAP_GATEWAY_OFFLINE_PROVIDER_ALLOWLIST:-}
+      MAP_GATEWAY_CORS_ORIGIN: ${MAP_GATEWAY_CORS_ORIGIN:-http://127.0.0.1:3333,http://localhost:3333}
+      MAP_GATEWAY_ALLOW_ANONYMOUS: ${MAP_GATEWAY_ALLOW_ANONYMOUS:-true}
+      # The mutable live cache and the immutable imported Engine snapshot are
+      # separate stores. Selecting the offline adapter can never write to or
+      # fetch through the live store.
+      MAP_CACHE_DIR: /var/lib/nodedc-map-live-cache
+      MAP_OFFLINE_SNAPSHOT_DIR: /var/lib/nodedc-map-offline-snapshot
+      MAP_CACHE_MODE: ${MAP_CACHE_MODE:-readwrite}
+      MAP_CACHE_MAX_MB: ${MAP_CACHE_MAX_MB:-20480}
+      MAP_CACHE_MAX_OBJECT_MB: ${MAP_CACHE_MAX_OBJECT_MB:-128}
+      MAP_CACHE_DEFAULT_TTL_SECONDS: ${MAP_CACHE_DEFAULT_TTL_SECONDS:-604800}
+      MAP_GATEWAY_UPSTREAM_TIMEOUT_SECONDS: ${MAP_GATEWAY_UPSTREAM_TIMEOUT_SECONDS:-30}
+    expose:
+      - "18103"
+    ports:
+      - "${MAP_GATEWAY_HOST_BIND:-127.0.0.1:18103}:18103"
+    volumes:
+      - map-live-tile-cache:/var/lib/nodedc-map-live-cache
+      - map-offline-snapshot:/var/lib/nodedc-map-offline-snapshot:ro
+    healthcheck:
+      test:
+        - CMD
+        - node
+        - -e
+        - "fetch('http://127.0.0.1:18103/healthz').then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))"
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
 volumes:
   authentik-database:
   authentik-data:
@@ -191,3 +238,12 @@ volumes:
   ai-workspace-database:
   caddy-data:
   caddy-config:
+  # Cache data is runtime state, not Compose lifecycle state. These volumes are
+  # created once by Platform bootstrap and deliberately survive `down -v`.
+  # Removing them requires an explicit `docker volume rm` operation.
+  map-live-tile-cache:
+    external: true
+    name: ${NODEDC_MAP_LIVE_CACHE_VOLUME:-nodedc-platform_map-live-tile-cache}
+  map-offline-snapshot:
+    external: true
+    name: ${NODEDC_MAP_OFFLINE_SNAPSHOT_VOLUME:-nodedc-platform_map-offline-snapshot}