Projektdokumentation – SAMO Infra Tracker

1. Projektüberblick

SAMO Infra Tracker ist eine native iOS-Anwendung zur GPS-basierten Erfassung, Verwaltung und Dokumentation von Infrastrukturelementen – insbesondere Gasleitungen. Die App dient als mobiler Client für das SAMO Infrastruktur-System (Asseco-BERIT) und richtet sich an professionelle Nutzer wie Netzbetreiber, Versorgungsunternehmen, Bauunternehmen, Wartungs- und Inspektionsdienste sowie Kommunen.

Kernfunktionen

• GPS-Tracking: Aufzeichnung von GPS-Tracks entlang von Infrastrukturelementen oder unabhängig, auch im Hintergrund.
• Kartenintegration: Visualisierung von Gasleitungen, GPS-Tracks und Schäden auf einer interaktiven MapKit-Karte.
• SAMO-Backend-Anbindung: REST-basierte Kommunikation mit dem SAMO-Server zum Laden, Erstellen und Verknüpfen von GIS-Features.
• Schadensmeldung: Erfassung von Infrastrukturschäden mit Beschreibung und präziser GPS-Position.
• Foto-Attachments: Möglichkeit, Fotos bei Schäden als Attachments hochzuladen.
• Flexible Konfiguration: Anpassbare Feature-Typen, Relationstypen und Server-Einstellungen.
• Koordinatenumrechnung: Automatische Umrechnung WGS84 ↔ Swiss LV95 für das Schweizer Koordinatensystem.
• Mehrsprachigkeit: Unterstützung für Deutsch, Englisch, Französisch, Italienisch, Tschechisch und Japanisch.

2. Technologie-Stack

2.1 Änderungen in Version 1.1 (Mai 2026)

Neue Features

• Track ohne Leitung: GPS-Tracks können jetzt auch unabhängig von einer Infrastrukturleitung erstellt werden. Dies ermöglicht die Dokumentation von autonomen GPS-Pfaden.
• Foto-Attachments bei Schäden: Benutzer können Fotos von Schadensstellen aufnehmen und direkt als Attachments zur Schadensmeldung hochladen.
• Erweiterte Mehrsprachigkeit: Neben Deutsch und Englisch werden jetzt auch Französisch, Italienisch, Tschechisch und Japanisch unterstützt.

Verbesserungen

• OSLog-Integration: Strukturiertes Logging mit OSLog für bessere Fehleranalyse und Debugging. Geheime Daten werden automatisch maskiert.
• Fehlerbehandlung: Robustere Fehlerbehandlung bei Netzwerkoperationen und JSON-Parsing. Bessere Fehlermeldungen für Benutzer.
• Feature-Loading: Neuer append-Parameter bei loadFeatures() ermöglicht inkrementelles Laden von Features statt vollständigem Ersetzen.
• Track-Upload-Response: Verbesserte Verarbeitung von komplexen JSON-Responses vom SAMO-Server mit optionalen content-Strukturen.

3. Architektur (MVVM)

Die App folgt dem MVVM-Muster (Model-View-ViewModel) mit einem zentralen ViewModel als ObservableObject. Das ViewModel orchestriert die gesamte App-Logik, hält den State und koordiniert die Netzwerk-Schicht über den GisFeatureController.

3.1 Datenfluss

• GisFeatureController – Zuständig für alle HTTP-Anfragen (Features laden, Tracks hochladen, Schäden melden).
• ViewModel – Zentraler State-Holder: GPS-Position, Features, Konfiguration, Karten-Region. Stellt @Published-Properties bereit.
• Views – SwiftUI-Views binden per @ObservedObject / @Binding an das ViewModel und reagieren reaktiv auf Änderungen.

3.2 Architektur-Diagramm

4. Projektstruktur

5. Dateiübersicht

5.1 App Entry Point – SAMO_Infra_TrackerApp.swift

Einstiegspunkt der App, markiert mit @main. Erstellt ein WindowGroup mit CustomContentView als Root-View. Das ViewModel wird innerhalb von CustomContentView instanziiert.

@main
struct SAMO_Infra_TrackerApp: App {
    var body: some Scene {
        WindowGroup {
            CustomContentView(myPolylinesSelected: [])
        }
    }
}

5.2 Model / Netzwerk-Schicht – GisFeatureController.swift

Zentrale Klasse für die HTTP-Kommunikation mit dem SAMO REST API. Verwaltet Authentifizierung (Cookie-basiert mit Basic-Auth-Fallback), Feature-Downloads, Track-Uploads und Schadensmeldungen.

Wichtige Eigenschaften

Wichtige Methoden

5.3 ViewModel – ViewModel.swift

Zentrales ObservableObject, das den gesamten App-State verwaltet. Erbt von NSObject und implementiert CLLocationManagerDelegate für GPS-Updates. Orchestriert den GisFeatureController und stellt @Published-Properties für die Views bereit.

Zentrale @Published Properties

Wichtige Methoden

5.4 Datenstrukturen (Structs)

Alle Datenmodelle befinden sich im Ordner structs/. Details zu den einzelnen Structs finden Sie in Abschnitt 6. Datenmodelle.

5.5 Views

Details zur Benutzeroberfläche finden Sie in Abschnitt 8. Benutzeroberfläche.

6. Datenmodelle

6.1 GisFeature (GisFeature.swift)

Decodable-Modell für die JSON-Antworten des SAMO REST API. Repräsentiert ein geographisches Feature (Leitung).

Methoden

• getFirstCoordinate() → CLLocationCoordinate2D – Erste Koordinate des Features
• getCoordinates() → [CLLocationCoordinate2D] – Alle Koordinaten als Array

6.2 Leitungen (Leitungen.swift)

Repräsentiert eine Leitung (z.B. Gasleitung) für die Kartenanzeige. Konvertiert aus GisFeature.

Extension: isNear(coordinate:) – Hit-Test, ob eine Koordinate innerhalb von 15m liegt (für Tap-Erkennung).

6.3 GpsPath (GpsTrack.swift)

Repräsentiert einen aufgezeichneten GPS-Track (Pfad aus Koordinaten).

6.4 Schaden (Schaden.swift)

Repräsentiert eine Schadensmeldung an einer Punktposition.

myEncode() erzeugt das JSON für die SAMO API mit Attributen wie at_alg_report_description und Punkt-Geometrie.

6.5 ConfigData (ConfigData.swift)

Codable-Struct für die Persistierung aller Einstellungen.

ConfigManager (Singleton): save(_:) und load() lesen/schreiben config.json im Documents-Verzeichnis.

7. Netzwerk & API

7.1 Authentifizierung

Die App verwendet eine zweistufige Authentifizierungsstrategie:

1. Cookie-basiert (Primär): Bei vorhandenem Session-Cookie wird dieser für Anfragen verwendet. Der Cookie wird aus Response-Headers extrahiert und persistiert.
2. Basic Auth (Fallback): Falls kein Cookie vorhanden ist oder der Cookie abgelaufen ist, wird ein Base64-codierter username:password-Token als Authorization: Basic …-Header gesendet.

Bei 401 Unauthorized-Antworten wechselt die App automatisch zurück zu Basic Auth und versucht einen neuen Cookie zu erhalten.

7.2 API-Endpunkte

7.3 Retry-Logik

Alle Netzwerkanfragen nutzen eine generische Retry-Logik (retryRequest()):

• Maximale Versuche: 10
• Verzögerung: 2 Sekunden zwischen den Versuchen
• Auslöser: HTTP 401 (Unauthorized) → neuer Auth-Versuch mit Basic Auth
• Cookie-Refresh: Bei erfolgreicher Antwort wird der Session-Cookie aktualisiert

8. Benutzeroberfläche

8.1 Hauptbildschirm – CustomContentView.swift

Root-View der App mit folgendem Aufbau (von oben nach unten):

Verhalten

• Scene-Phase-Observer: Speichert Konfiguration automatisch beim App-Wechsel in den Hintergrund.
• GPS-Button: Toggelt trackVerfolgenUndAufzeichnen, startet/stoppt Location-Updates.
• Leitungsauswahl: Delegiert an viewModel.selectGasleitung().
• Schadenserstellung: Ruft viewModel.neuenSchadenErstellen() auf.
• Drag-Handle: Grauer Balken zum Vergrößern/Verkleinern der Karte (200–550pt).

8.2 Kartenansicht – customMapView.swift

UIViewRepresentable-Wrapper um MKMapView für volle MapKit-Kontrolle. Ein Coordinator dient als MKMapViewDelegate.

Overlay-Farbkodierung

Interaktionen

• Tap-Geste: Hit-Test auf Polylines – wählt nächste Leitung innerhalb von 15m aus.
• Pan/Zoom: Aktualisiert die ViewModel-Position, berechnet Swiss Bounding Box neu, triggert Feature-Download.
• Auto-Center: Bei aktivem GPS-Following zentriert sich die Karte auf den Benutzer.

8.3 Konfigurationsseite – configPage.swift

Einstellungs-View mit @Binding-Properties zum ViewModel. Zwei Formularbereiche:

• Verbindungseinstellungen: URL, Benutzername, Passwort, Anzeigenamen
• SAMO Konfiguration: Feature-Typen, Relationstypen, Rollen

Drei Aktionsbuttons: Konfiguration speichern, Verbindung prüfen, Verbindung trennen.

9. Koordinatensysteme

Die App arbeitet mit zwei Koordinatensystemen und konvertiert automatisch zwischen diesen:

Umrechnung WGS84 → LV95

Die Methode wgs84ToLV95(lat:lon:) im ViewModel implementiert die offiziellen swisstopo-Formeln zur Umrechnung von WGS84-Breitengrad/Längengrad in Schweizer LV95-Koordinaten (Easting/Northing).

Bounding Box

boundingBoxLV95FromGPS(lat:lon:edgeLengthMeters:) berechnet eine quadratische Bounding Box in LV95-Koordinaten um eine GPS-Position. Diese wird für den Feature-Download verwendet, um nur Features im aktuellen Kartenausschnitt zu laden.

10. Konfiguration & Persistenz

Alle Einstellungen werden als JSON-Datei im Documents-Verzeichnis der App gespeichert:

Documents/config.json

Gespeicherte Daten

• Server-URL, Benutzername und Passwort
• Alle SAMO Feature-Typen, Relationstypen und Rollen
• Anzeigenamen (Leitung / Schaden)
• Session-Cookie (für persistente Anmeldung)

Speicher-Zeitpunkte

• Manuell: Button „Konfiguration speichern" auf der Einstellungsseite
• Automatisch: Beim Wechsel in den Hintergrund (scenePhase == .background)

ConfigManager (Singleton)

11. Zentrale Workflows

11.1 App-Start

11.2 GPS-Tracking

11.3 Schadensmeldung

11.4 Karteninteraktion

12. Build & Systemanforderungen

Entwicklungsumgebung

Verwendete Frameworks

Zielplattform

Build-Schritte

1. Repository / Projektordner in Xcode öffnen (SAMO Infra Tracker.xcodeproj)
2. Signing & Capabilities konfigurieren (Apple Developer Account erforderlich)
3. Zielgerät oder Simulator auswählen
4. ⌘ + B zum Bauen, ⌘ + R zum Ausführen

13. Glossar