feat(api,web): optional satellite map tile layer (ADR 0018) #1107

Merged
chris merged 2 commits from feat/map-satellite-tile-provider into main 2026-10-11 13:18:55 +02:00
Owner

Summary

Adds an optional second map tile style ("satellite") alongside the existing operator-configured base tile provider (ADR 0018 boundary). The satellite layer extends the SAME operational_settings record (map_tile_provider, JSONB) — no migration, no new key. If satellite is not configured, nothing changes in the UI.

Contract (another lane depends on this — do not change names)

MapTileProviderSettings (apps/api/.../api/map/) and UpdateMapTileProviderSettingsRequest gain three nullable fields:

  • String satelliteTileUrlTemplate — null/blank = satellite disabled
  • String satelliteName
  • String satelliteAttribution

TypeScript type in apps/web/src/lib/api/map.ts (placed after attribution: string;):

  satelliteTileUrlTemplate?: string | null;
  satelliteName?: string | null;
  satelliteAttribution?: string | null;

Behaviour

  • sanitize(): null/blank satellite template → stored null and name/attribution nulled (disabled). When set: must contain {z}, {x}, {y} (order-independent contains-check, so Esri {z}/{y}/{x} passes) and start with https://, http:// or /. Blank satelliteName defaults to "Satellite"; satelliteAttribution may stay "".
  • decode(): null fallbacks — legacy stored JSON without satellite fields decodes cleanly with satellite disabled; base provider defaults unchanged.
  • toView(): pass-through, nulls serialize as null (no exceptions).

Admin UI (Super Admin, existing "Karten" tile provider card)

  • defaultMapProvider() satellite fields = null, saveMapProvider() sends them.
  • useEsriSatellitePreset(): https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x} / Esri World Imagery / Esri, Maxar, Earthstar Geographics, plus a Clear satellite layer action.
  • AdminDataTab.svelte: satellite template/name/attribution inputs (same classes as base fields), preset + clear buttons, short privacy note (an external satellite provider sees the same data as any external tile provider).

Tests

MapSettingsServiceTest: (a) defaults have no satellite layer, (b) satellite update round-trips, (c) invalid satellite template (missing {y}, bad scheme) rejected, (d) blank satellite template clears satellite, (e) legacy stored JSON without satellite fields decodes with satellite disabled.

Docs & bookkeeping

deploy/README.md, docs/wiki/ops/map-tiles-and-places-privacy.md, docs/wiki/user/places-and-map.md (optional-satellite paragraphs), OpenAPI contract schemas, changelog docs/dev/changelog/v1.21.75.md, version 1.21.74 → 1.21.75.

Verification

  • rtk ./gradlew :apps:api:test --tests 'dev.memories.api.map.*' → BUILD SUCCESSFUL (MapSettingsServiceTest: 9 tests, 0 failures, 0 errors)
  • npm run check (svelte-check) → 0 errors, 22 pre-existing warnings (none in touched files)

Out of scope (other lanes)

MapView.svelte satellite toggle, map/album/MediaInfoPanel call sites (provider prop carries the new fields automatically).

## Summary Adds an **optional second map tile style ("satellite")** alongside the existing operator-configured base tile provider (ADR 0018 boundary). The satellite layer extends the SAME `operational_settings` record (`map_tile_provider`, JSONB) — no migration, no new key. If satellite is not configured, nothing changes in the UI. ### Contract (another lane depends on this — do not change names) `MapTileProviderSettings` (apps/api/.../api/map/) and `UpdateMapTileProviderSettingsRequest` gain three nullable fields: - `String satelliteTileUrlTemplate` — null/blank = satellite disabled - `String satelliteName` - `String satelliteAttribution` TypeScript type in `apps/web/src/lib/api/map.ts` (placed after `attribution: string;`): ```ts satelliteTileUrlTemplate?: string | null; satelliteName?: string | null; satelliteAttribution?: string | null; ``` ### Behaviour - `sanitize()`: null/blank satellite template → stored null and name/attribution nulled (disabled). When set: must contain `{z}`, `{x}`, `{y}` (order-independent contains-check, so Esri `{z}/{y}/{x}` passes) and start with `https://`, `http://` or `/`. Blank `satelliteName` defaults to `"Satellite"`; `satelliteAttribution` may stay `""`. - `decode()`: null fallbacks — legacy stored JSON without satellite fields decodes cleanly with satellite disabled; base provider defaults unchanged. - `toView()`: pass-through, nulls serialize as null (no exceptions). ### Admin UI (Super Admin, existing "Karten" tile provider card) - `defaultMapProvider()` satellite fields = null, `saveMapProvider()` sends them. - `useEsriSatellitePreset()`: `https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}` / `Esri World Imagery` / `Esri, Maxar, Earthstar Geographics`, plus a **Clear satellite layer** action. - `AdminDataTab.svelte`: satellite template/name/attribution inputs (same classes as base fields), preset + clear buttons, short privacy note (an external satellite provider sees the same data as any external tile provider). ### Tests `MapSettingsServiceTest`: (a) defaults have no satellite layer, (b) satellite update round-trips, (c) invalid satellite template (missing `{y}`, bad scheme) rejected, (d) blank satellite template clears satellite, (e) legacy stored JSON without satellite fields decodes with satellite disabled. ### Docs & bookkeeping `deploy/README.md`, `docs/wiki/ops/map-tiles-and-places-privacy.md`, `docs/wiki/user/places-and-map.md` (optional-satellite paragraphs), OpenAPI contract schemas, changelog `docs/dev/changelog/v1.21.75.md`, version 1.21.74 → 1.21.75. ### Verification - `rtk ./gradlew :apps:api:test --tests 'dev.memories.api.map.*'` → BUILD SUCCESSFUL (MapSettingsServiceTest: 9 tests, 0 failures, 0 errors) - `npm run check` (svelte-check) → 0 errors, 22 pre-existing warnings (none in touched files) ### Out of scope (other lanes) `MapView.svelte` satellite toggle, map/album/MediaInfoPanel call sites (provider prop carries the new fields automatically).
Extend the single operator-configured map tile provider settings record
(operational_settings key map_tile_provider) with an optional satellite
layer. No satellite template configured = nothing changes in the UI.

Contract:
- MapTileProviderSettings / UpdateMapTileProviderSettingsRequest gain
  satelliteTileUrlTemplate, satelliteName, satelliteAttribution (nullable).
- sanitize(): null/blank satellite template -> disabled (name/attribution
  nulled); set -> must contain {z}/{x}/{y} (order-independent, Esri
  {z}/{y}/{x} passes) and start with https://, http:// or /. Blank name
  defaults to 'Satellite', attribution may stay empty.
- decode(): null fallbacks so legacy stored JSON decodes with satellite
  disabled; base provider defaults unchanged.
- toView(): pass-through; nulls serialize as null.

Frontend:
- map.ts type block (+3 optional fields after attribution).
- admin setup page: defaultMapProvider/saveMapProvider carry satellite
  fields; useEsriSatellitePreset() + clearSatelliteLayer() helpers.
- AdminDataTab: satellite template/name/attribution inputs, Esri World
  Imagery preset + clear buttons, privacy note.

Tests: defaults have no satellite, round-trip, invalid template rejected,
blank template clears, legacy JSON decodes disabled.

Docs: deploy/README.md, docs/wiki/ops/map-tiles-and-places-privacy.md,
docs/wiki/user/places-and-map.md, OpenAPI contract schemas.
chore: version bump 1.21.74 -> 1.21.75 + changelog
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 17m56s
51f8c5b845
chris merged commit ecfff9507c into main 2026-10-11 13:18:55 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1107
No description provided.