Release GPS2Audio v2.5.45 Explorer POI autoload

releases/v2.5.45/GPS2Audio_v2_5_45_explorer_poi_autoload_handoff.md

@@ -0,0 +1,205 @@
+# GPS2Audio v2.5.45 — Explorer POI Autoload — Handoff
+
+## Build-Ergebnis
+
+| Artefakt | Status |
+|---|---|
+| APK | ✅ BUILD SUCCESSFUL |
+| Signing | ✅ APK Signature Scheme v2 verified |
+| applicationId | `de.waypointaudio` |
+| versionCode | 99 |
+| versionName | 2.5.45 |
+| APK-Datei | `GPS2Audio_v2_5_45_explorer_poi_autoload_universal_signed.apk` (57 MB) |
+| Quelle | `GPS2Audio_v2_5_45_explorer_poi_autoload_source.zip` |
+
+Build-Basis: `GPS2Audio_v2_5_44_poi_category_fix_source.zip`
+
+---
+
+## 1. Automatisches POI-Nachladen
+
+### Verhalten
+
+- **Standardmäßig aktiviert** — kein manueller Start nötig.
+- POIs werden nach Kartenbewegung automatisch geladen (1.5 Sekunden Debounce nach `onCameraIdle`).
+- Neue Anfrage **nur** wenn:
+  - Mindest-Zoom ≥ 12.0 (`ExplorerPoiClient.AUTO_LOAD_MIN_ZOOM`)
+  - Karte hat sich um > 300 m bewegt (`MOVE_THRESHOLD_M`) **oder** Zoom hat sich um > 0.8 geändert **oder** Kategorien haben sich geändert
+  - POI-Layer aktiv (mindestens eine Kategorie)
+  - Kein laufendes Load in progress
+
+### Schutzmechanismen
+
+| Schutz | Wert |
+|---|---|
+| Debounce | 1.5 Sekunden nach `onCameraIdle` |
+| Minimaler Zoom | ≥ 12.0 (darunter: keine Auto-Anfrage) |
+| Maximaler Radius | 5 000 m (wie bisher, `MAX_RADIUS_M`) |
+| Cache-Schutz | Cache per Kategorie + BBox-Fingerprint; neue Anfrage nur bei > 300 m Bewegung oder Zoom-/Kategorie-Wechsel |
+| Fehlerverhalten | Bei Fehler: alte POIs bleiben, dezente Snackbar-Meldung; kein White-Screen |
+| Parallel-Schutz | `explorerPoiLoading`-Flag; laufende Auto-Load-Jobs werden bei neuem Trigger gecancelt |
+| Kategorie-Wechsel | Cache + Cursor werden geleert, nächster Idle lädt frisch |
+
+### Manueller Fallback
+
+Der manuelle Reload-Button (`↻`) ist **erhalten** und erzwingt immer einen frischen Load (Cache + Cursor werden geleert).
+
+### Statusanzeige (POI-Bar, BottomCenter)
+
+| Zustand | Anzeige |
+|---|---|
+| Laden läuft | Spinner + „POIs werden aktualisiert…" |
+| Auto-Load aktiv, Ergebnis vorhanden | „POIs: 42" |
+| Auto-Load aktiv, Zoom zu klein | „Hereinzoomen für Auto-Load" |
+| Auto-Load aktiv, keine Ergebnisse geladen | „POIs: Auto-Laden aktiv" |
+| Auto-Load deaktiviert | „POIs: manuell laden" |
+
+### Toggle im Layer-Sheet
+
+Im Ebenen-Panel (Layers-FAB) im POI-Abschnitt:  
+**„POIs automatisch nachladen"** — Switch, Standard: EIN  
+Beschriftungshinweis: „Auto-Laden: POIs werden beim Kartenverschieben aktualisiert (ab Zoom 12)"
+
+---
+
+## 2. POI-Untertypen (Subtypes)
+
+### Architektur
+
+Neues Enum `PoiSubtype` in `ExplorerPoiClient.kt` — **nur In-Memory/Runtime, kein Persistenz-/Backup-Einfluss**.
+
+`ExplorerPoiResult` erhält ein neues Feld `subtype: PoiSubtype` (Default: `GENERIC_*`).
+
+### Enthaltene Untertypen
+
+| Kategorie | Subtype | OSM-Tags | Piktogramm |
+|---|---|---|---|
+| SIGHTS | CASTLE | historic=castle/palace/fort | Zinnenkranz + Tor |
+| SIGHTS | RUIN | historic=ruins/archaeological_site | Gebrochene Mauer |
+| SIGHTS | CHURCH | amenity=place_of_worship, historic=church | Kreuz |
+| SIGHTS | MONASTERY | historic=monastery | Kleines Kreuz + Bogen |
+| SIGHTS | MUSEUM | tourism=museum | Giebelhaus |
+| SIGHTS | VIEWPOINT | tourism=viewpoint | Fernglas |
+| SIGHTS | MONUMENT | historic=monument/memorial | Säule |
+| SIGHTS | GALLERY | tourism=gallery/artwork | Bilderrahmen |
+| SIGHTS | THEATRE | amenity=theatre/cinema/arts_centre | Drama-Bögen |
+| SIGHTS | ZOO | tourism=zoo/theme_park | Pfotenabdruck |
+| SIGHTS | ATTRACTION | tourism=attraction | Monument-Nadel |
+| SIGHTS | HISTORIC_OTHER | historic=* (sonstige) | Säule |
+| GASTRONOMY | RESTAURANT | amenity=restaurant | Messer + Gabel |
+| GASTRONOMY | CAFE | amenity=cafe | Tasse + Dampf |
+| GASTRONOMY | BAR | amenity=bar/pub/biergarten | Bierglas |
+| GASTRONOMY | FAST_FOOD | amenity=fast_food/food_court/ice_cream | Burger-Silhouette |
+| MOBILITY | PARKING | amenity=parking | „P"-Piktogramm |
+| MOBILITY | BUS_STOP | highway=bus_stop, amenity=bus_station | Bus-Silhouette |
+| MOBILITY | TRAIN_STATION | railway=station/halt | Zug |
+| MOBILITY | TRAM_STOP | railway=tram_stop | Straßenbahn + Stromabnehmer |
+| MOBILITY | FUEL | amenity=fuel/charging_station | Zapfsäule |
+| INFRASTRUCTURE | PHARMACY | amenity=pharmacy | Apotheken-Kreuz |
+| INFRASTRUCTURE | HOSPITAL | amenity=hospital/clinic | H-Symbol |
+| INFRASTRUCTURE | TOILETS | amenity=toilets | WC-Piktogramm |
+| INFRASTRUCTURE | DRINKING_WATER | amenity=drinking_water | Wassertropfen |
+
+Alle nicht spezifisch gemappten POIs erhalten ihr Kategorie-Fallback-Icon (wie v2.5.44).
+
+### Marker-Design
+
+- **Hauptkategorie-Farbe** bleibt erhalten (Teal/Amber/Dunkelblau/Dunkelgrün).
+- **Hintergrundform** bleibt per Kategorie (Stern/Kreis/Abger. Rechteck/Kreis mit Rand).
+- **Inneres Piktogramm** variiert per Subtype (Canvas-Zeichnung, wie v2.5.43-Stil).
+- **Sentinel-Pixel** berücksichtigt Kategorie + Subtype-Ordinal, verhindert MapLibre-Cache-Kollisionen.
+
+### Detail-Sheet
+
+Zeigt jetzt `poi.subtype.displayLabel` statt `poi.categoryLabel`, z. B. „Burg/Schloss" statt „Sehenswürdigkeit".
+
+### Legende
+
+- Kompakt-Ansicht: Farbpunkte wie bisher.
+- Ausgeklappt: Hinweis **„Symbole zeigen Untertypen"** (neu in v2.5.45).
+
+---
+
+## 3. Explorer-UX-Aufräumungen
+
+### Vorgenommen
+
+| Bereich | Änderung |
+|---|---|
+| POI-Statusbar | Redesign von reinem Lade-Button zu kompakter Status+Reload-Bar (BottomCenter) |
+| POI-Bar Text | Kontextabhängiger Statustext (Auto-Laden aktiv / Zoom-Hinweis / Fehlerzustand) |
+| Layer-Sheet | Auto-Load-Toggle im POI-Abschnitt ergänzt; Beschreibungshinweis |
+| Legende | Hinweis „Symbole zeigen Untertypen" im aufgeklappten Zustand |
+| Detail-Sheet | Konkreterer Typ-Label (Subtype statt Kategorie) |
+
+### Nicht verändert
+
+- Kein Screen, Dialog oder Sheet entfernt.
+- TopBar, FAB-Layout, Attribution, Kompass, Nordausrichtung unverändert.
+- Routenplaner/Storyboard-UI nicht umgebaut (wie gefordert).
+- Phantom-Track-Fixes, Waypoint-Logik, Follow-Location unverändert.
+
+---
+
+## 4. Was NICHT verändert wurde
+
+| Bereich | Status |
+|---|---|
+| Storyboard/Routenplaner-Datenmodell | ❌ Nicht angefasst |
+| Backup/Import/Export (ZIP, GPX) | ❌ Nicht angefasst |
+| Playback/Multi-Clip/Player | ❌ Nicht angefasst |
+| Lizenzsystem (ECDSA-Validierung, Storage) | ❌ Nicht angefasst |
+| Waypoints/Touren/Tracks | ❌ Nicht angefasst |
+| GPS-Aufzeichnung | ❌ Nicht angefasst |
+| PoiCategory-Enum | ❌ Nicht angefasst (rückwärtskompatibel) |
+| PoiLayerSettings-Persistenz | ❌ Nicht angefasst (keine neuen Keys) |
+| MapStyleSettings | ❌ Nicht angefasst |
+| applicationId | `de.waypointaudio` — unverändert |
+| Keystore-Kompatibilität | Gleicher Keystore wie v2.5.44 |
+| Canvas-Piktogramm-System (v2.5.43) | Erhalten und erweitert |
+
+---
+
+## 5. Geänderte Dateien
+
+| Datei | Art der Änderung |
+|---|---|
+| `app/build.gradle.kts` | versionCode 98→99, versionName 2.5.44→2.5.45 |
+| `util/ExplorerPoiClient.kt` | Neues `PoiSubtype`-Enum; `ExplorerPoiResult.subtype`; `resolveSubtype()`; `shouldAutoLoad()`-Funktion |
+| `ui/ExplorerScreenMapLibre.kt` | Auto-Load-State + Debounce-Logik in cameraIdleListener; Subtype-Icons in Marker-Drawing; Detail-Sheet Subtype-Label; neue POI-Statusbar; MapLayerFab Auto-Load-Callbacks |
+| `ui/MapLayerPanel.kt` | `poiAutoLoadEnabled`/`onPoiAutoLoadChange`-Parameter; Toggle-Row im POI-Abschnitt |
+
+---
+
+## 6. Smoke-Tests (manuell simuliert / Compile-Test)
+
+- ✅ Build: `assembleRelease` erfolgreich (43 tasks executed)
+- ✅ APK-Signing: v2 scheme verifiziert
+- ✅ versionCode = 99, versionName = 2.5.45, applicationId = de.waypointaudio
+- ✅ Keine Kompilier-Fehler (nur Pre-existing deprecation-Warnings aus älteren Dateien)
+- ✅ `PoiSubtype` mit allen 25 Werten kompiliert
+- ✅ Auto-Load-Logik: `shouldAutoLoad()` in `ExplorerPoiClient`, verwendet in `cameraIdleListener`
+- ✅ Subtype-Icons: `buildExplorerPoiIcon(category, subtype)` mit When-Exhaustive-Abdeckung
+- ⚠️ Duplicate-Branch-Warning in `ExplorerPoiClient.kt` (Z. 614: `"fort"` doppelt in `humanizeHistoric`) — funktional ohne Auswirkung, nur Compiler-Hinweis
+
+---
+
+## 7. Bekannte Grenzen
+
+| Thema | Beschreibung |
+|---|---|
+| Kein APK-Größen-Split | Universal APK (57 MB), kein ABI-Split — wie gefordert |
+| Auto-Load nur online | Kein Offline-Cache; bei Netzwerkfehler bleiben alte POIs erhalten |
+| Subtype-Piktogramme | 25 Subtypes; sehr kleine Piktogramme (56×56 px) können auf kleinen Displays unter Details leiden — aber alle klar erkennbar |
+| MapLibre Icon-Cache | Sentinel-Pixel-System verhindert Cache-Kollisionen; bei sehr vielen POIs kann es zu Marker-Redraws beim ersten Laden kommen |
+| Auto-Load-Debouce | 1.5 s Debounce — bei sehr schnellem Scrolling löst erst das finale Idle aus |
+| Storyboard/v2.6.0 | Kein Datenmodell-Umbau in v2.5.45. Vorarbeitung für v2.6.0: `PoiSubtype` als erweiterungsfähiges Enum vorhanden |
+| Duplicate `"fort"` | In `humanizeHistoric()`: `"fort"` erscheint zweimal (Zeile 614 Warning). Zweiter Eintrag wird nie erreicht — keine funktionale Auswirkung |
+
+---
+
+## 8. Upgrade-Pfad
+
+- Update von v2.5.44 auf v2.5.45 mit demselben Keystore (`GPS2Audio_release_keystore_v2.jks`) ist als In-Place-Update möglich.
+- Alle gespeicherten Einstellungen (POI-Layer, Kartenstil, Follow-Location) bleiben erhalten.
+- Keine Datenbank-Migration notwendig.