feat(android): Phase 3 map — clustered viewport with scope chips #1126

Merged
chris merged 4 commits from ux-android-map into main 2026-10-11 23:41:39 +02:00
Owner

What

Spec 055 T009 — the KARTE tab: an osmdroid map driven entirely by the server's map API.

  • Library: osmdroid 6.1.20 (Apache-2, offline tile cache, consumes the backend's {z}/{x}/{y} template directly; no provider is hardcoded — ADR 0018).
  • API client (additive tail block, concurrent-lane convention): GET /api/map/viewport, /api/map/bounds, /api/map/tile-provider + DTOs tolerant of unknown keys; fakes gain gated viewport responses.
  • Viewport: 400 ms debounce after pan/zoom idle; the in-flight OkHttp call is cancelled with its job when a newer camera move arrives, so a stale answer never lands. Subtle spinner + small error banner with retry; the map stays visible.
  • Clusters: count-badge markers for count>1, default pin for single-marker clusters. Tap cluster → zoom in two levels, centre, refetch. Tap pin → bottom-sheet card (thumbnail, date, photo/video glyph) → MediaViewerScreen over the viewport's marker list.
  • Scope chips: Alle / Meine, same chip idiom as the timeline; re-clusters the current view immediately. Satellite chip appears only when the server configured satelliteTileUrlTemplate.
  • Initial camera: from /api/map/bounds padded ~10% (floor span so one pin doesn't over-zoom), else world view. Re-entering the tab restores the last camera box from the app-scoped ViewModel.
  • Attribution: © action over the map opens a sheet with the provider's name, attribution and privacyDisclosure.
  • i18n: all strings in de/da/en; nav_karte = Karte / Kort / Map.
  • Nav: KARTE is the 4th tab between Fotos and Sicherung; all route/wiring changes are in the final isolated commit.

Tile-provider findings

  • GET /api/map/tile-provider returns mode (external|self_hosted), a single {z}/{x}/{y} template, attribution, optional satellite template/name/attribution, privacyDisclosure and externalProvider. The client renders tiles only from this answer.
  • Server defaults: viewport clamps markerLimit to 5000 and includes cluster members unless told otherwise; single-marker clusters always carry their marker. Web's display path uses the 5000 default without members; its split-view viewer path uses 240 with members. Android combines display+viewer in one call → 500 as the middle ground (ISSUE-131 notes the count-undercount trade-off).
  • Cluster counts reflect the fetched rows (server aggregates after the LIMIT), so a very large library at low zoom can undercount — same class of behaviour the web accepts via its clamp.

Risks / notes

  • ISSUE-131 (low): markerLimit=500 caps cluster counts + members on very large viewports.
  • ISSUE-132 (low): the osmdroid canvas (MapView lifecycle, badges, drill-down animation, tile swap) is outside the JVM suite — 17 ViewModel + 5 JSON tests cover the decisions, not the pixels.
  • If the tile-provider call fails, the tab shows the load-error state rather than a blank map with markers (deliberate: no third-party tile fallback).
  • lintDebug: 18 errors, all pre-existing (ISSUE-119 + plurals) — verified zero new on this branch.

Verification

  • ./gradlew :app:testDebugUnitTest :app:assembleDebug → 331 tests, 0 failures, BUILD SUCCESSFUL (22 new: 17 MapViewModelTest, 5 MapJsonTest).
  • Version bumped to 0.2.1 / versionCode 12.
  • KNOWN_ISSUES: ISSUE-131, ISSUE-132 appended.
## What Spec 055 T009 — the **KARTE** tab: an osmdroid map driven entirely by the server's map API. - **Library**: osmdroid 6.1.20 (Apache-2, offline tile cache, consumes the backend's `{z}/{x}/{y}` template directly; no provider is hardcoded — ADR 0018). - **API client** (additive tail block, concurrent-lane convention): `GET /api/map/viewport`, `/api/map/bounds`, `/api/map/tile-provider` + DTOs tolerant of unknown keys; fakes gain gated viewport responses. - **Viewport**: 400 ms debounce after pan/zoom idle; the in-flight OkHttp call is cancelled with its job when a newer camera move arrives, so a stale answer never lands. Subtle spinner + small error banner with retry; the map stays visible. - **Clusters**: count-badge markers for count>1, default pin for single-marker clusters. Tap cluster → zoom in two levels, centre, refetch. Tap pin → bottom-sheet card (thumbnail, date, photo/video glyph) → **MediaViewerScreen** over the viewport's marker list. - **Scope chips**: Alle / Meine, same chip idiom as the timeline; re-clusters the current view immediately. Satellite chip appears only when the server configured `satelliteTileUrlTemplate`. - **Initial camera**: from `/api/map/bounds` padded ~10% (floor span so one pin doesn't over-zoom), else world view. Re-entering the tab restores the last camera box from the app-scoped ViewModel. - **Attribution**: © action over the map opens a sheet with the provider's name, `attribution` and `privacyDisclosure`. - **i18n**: all strings in de/da/en; `nav_karte` = Karte / Kort / Map. - **Nav**: KARTE is the 4th tab between Fotos and Sicherung; all route/wiring changes are in the final isolated commit. ## Tile-provider findings - `GET /api/map/tile-provider` returns `mode` (`external`|`self_hosted`), a single `{z}/{x}/{y}` template, attribution, optional satellite template/name/attribution, `privacyDisclosure` and `externalProvider`. The client renders tiles only from this answer. - Server defaults: viewport clamps `markerLimit` to 5000 and includes cluster members unless told otherwise; single-marker clusters always carry their marker. Web's display path uses the 5000 default without members; its split-view viewer path uses 240 with members. Android combines display+viewer in one call → **500** as the middle ground (ISSUE-131 notes the count-undercount trade-off). - Cluster counts reflect the *fetched* rows (server aggregates after the LIMIT), so a very large library at low zoom can undercount — same class of behaviour the web accepts via its clamp. ## Risks / notes - **ISSUE-131** (low): markerLimit=500 caps cluster counts + members on very large viewports. - **ISSUE-132** (low): the osmdroid canvas (MapView lifecycle, badges, drill-down animation, tile swap) is outside the JVM suite — 17 ViewModel + 5 JSON tests cover the decisions, not the pixels. - If the tile-provider call fails, the tab shows the load-error state rather than a blank map with markers (deliberate: no third-party tile fallback). - `lintDebug`: 18 errors, all pre-existing (ISSUE-119 + plurals) — verified zero new on this branch. ## Verification - `./gradlew :app:testDebugUnitTest :app:assembleDebug` → **331 tests, 0 failures, BUILD SUCCESSFUL** (22 new: 17 MapViewModelTest, 5 MapJsonTest). - Version bumped to 0.2.1 / versionCode 12. - KNOWN_ISSUES: ISSUE-131, ISSUE-132 appended.
Additive tail block per the concurrent-lane convention: GET /api/map/viewport
(clusters + optional members), /api/map/bounds, /api/map/tile-provider, with
DTOs that tolerate unknown keys (the server carries cluster extras and marker
dimensions we do not render yet). Fakes gain gated viewport responses for the
ViewModel debounce tests; MapJsonTest covers the full/minimal shapes.
osmdroid 6.1.20 drives the canvas straight from the server's tile-provider
template ({z}/{x}/{y}); no provider is hardcoded (ADR 0018), and the © action
opens a sheet with the provider's attribution + privacy disclosure. Clusters
render as count badges, single markers as pins with a marker card (thumbnail,
date, type) whose tap hands the whole viewport's markers to the viewer.

MapViewModel (app-scoped, hoisted at the route) owns the 400 ms viewport
debounce with job cancellation of in-flight fetches, the bounds-padded first
camera, scope chips (Alle/Meine, same idiom as the timeline), satellite
toggle, and the saved camera for tab re-entry. 17 ViewModel + 5 JSON tests;
the osmdroid surface itself is outside the JVM suite (ISSUE-132).

Strings added in de/da/en; nav_karte lands with the tab wiring.
Fourth tab between Fotos and Sicherung, wired in the established pattern:
MapViewModel hoisted app-scope (reset on session change) so the scope chip,
satellite toggle and last camera box survive tab switches, plus the full-bleed
mapMedia/{mediaItemId} viewer route reading the viewport's marker list. This
commit is deliberately isolated: every route/wiring change lives here.
chore(android): 0.2.1 / versionCode 12 + map known issues
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 / 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 postgres image (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 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 6m58s
529e45a614
ISSUE-131: viewport markerLimit=500 means cluster counts can undercount on
very large libraries (server clusters only the fetched rows).
ISSUE-132: the osmdroid canvas itself has no JVM coverage; only the
ViewModel and DTO shapes are unit-tested.
chris merged commit da3886f110 into main 2026-10-11 23:41:39 +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!1126
No description provided.