- Dokumentation

- Bereinigung von Code

docs/ProximityNotificationService.md

@@ -0,0 +1,72 @@
+# 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 `OBJECTID`s, 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.