SnapAndSolve/docs/ProximityNotificationService.md

ProximityNotificationService

Übersicht

Der ProximityNotificationService im Paket com.example.snapandsolve.service ist ein Android Foreground Service. Er ermöglicht die Hintergrund-Überwachung des Nutzerstandorts, um proaktiv Benachrichtigungen auszulösen, wenn sich der Nutzer in der Nähe (Standard: 100m) eines in ArcGIS registrierten Straßenschadens befindet.

---

1. Architektur & Lebenszyklus

Der Dienst ist darauf ausgelegt, unabhängig von der Sichtbarkeit der App zu laufen. Als Foreground Service ist er mit einer permanenten System-Benachrichtigung verknüpft, um eine vorzeitige Beendigung durch das Android-Betriebssystem zu verhindern.

Steuerung über das Companion Object

• start(context, featureTable): Initialisiert den Dienst mit der notwendigen Datenquelle und startet ihn.
• stop(context): Beendet das Tracking und den Dienst.

---

2. Funktionsweise des Standorts-Trackings

Initialisierung

Nach dem Start (onCreate) wird die SystemLocationDataSource von ArcGIS initialisiert. Diese liefert kontinuierlich Standort-Updates innerhalb eines dedizierten serviceScope (CoroutineScope).

Geofencing-Logik (checkProximityToDamages)

Bei jedem Standort-Update führt der Dienst eine räumliche Analyse durch:

1. Abfrage: Alle verfügbaren Features werden aus der ServiceFeatureTable abgerufen.
2. Projektion: Da GPS-Koordinaten (SpatialReference.wgs84()) oft nicht mit dem Koordinatensystem der Karte übereinstimmen, wird der Standort des Nutzers mittels GeometryEngine.projectOrNull transformiert.
3. Distanzberechnung: Die exakte Entfernung wird über GeometryEngine.distanceGeodeticOrNull berechnet. Hierbei wird der Kurventyp Geodesic verwendet, um die Erdkrümmung korrekt zu berücksichtigen.

---

3. Benachrichtigungs-Management

Spam-Prävention

Um mehrfache Warnungen für denselben Schaden zu vermeiden, nutzt der Dienst ein internes Cache-System:

• notifiedFeatures: Ein Set von OBJECTIDs, für die bereits eine Benachrichtigung gesendet wurde.
• Hysterese-Bereinigung: Eine ID wird erst dann aus dem Cache entfernt, wenn sich der Nutzer mehr als 150 Meter vom entsprechenden Schaden entfernt hat (cleanupNotifiedFeatures). Dies verhindert "flackernde" Benachrichtigungen an der Radiengrenze.

Benachrichtigungs-Inhalt

Der Dienst sucht dynamisch nach verfügbaren Attributen im ArcGIS-Feature, um den Text zu generieren:

• Kategorie: Prüft Felder wie Kategorie, kategorie, Category oder category.
• Beschreibung: Sucht nach zusätzlichen Details in Beschreibung oder Description.

---

4. Konfiguration & Konstanten

Konstante	Wert	Beschreibung
PROXIMITY_RADIUS_METERS	100.0	Radius, ab dem eine Warnung ausgelöst wird.
CHANNEL_ID	proximity_notifications	ID des Android-Benachrichtigungskanals.
START_STICKY	Konstante	Sorgt für einen automatischen Neustart des Dienstes nach einem System-Kill.

---

5. Voraussetzungen & Sicherheit

Erforderliche Berechtigungen

In der AndroidManifest.xml müssen folgende Berechtigungen konfiguriert sein:

• ACCESS_FINE_LOCATION (Präziser Standort)
• ACCESS_BACKGROUND_LOCATION (Standort im Hintergrund)
• FOREGROUND_SERVICE (Erlaubnis für Hintergrunddienste)

Datenintegrität

Der Dienst setzt voraus, dass die ServiceFeatureTable beim Start übergeben wird. Ist die Tabelle null, stellt der Dienst die Überprüfung ein und loggt einen Fehler, bleibt aber als Foreground Service aktiv, um Systeminstabilitäten zu vermeiden.

---

Fehlerbehandlung

• Projektionsfehler: Falls die Koordinatentransformation fehlschlägt, wird das betroffene Feature übersprungen.
• Geometrie-Validierung: Nur Features mit gültigen Punkt-Geometrien werden verarbeitet.