Wegwichtel/docs/agents/GPX-Aufzeichnung.md

GPX und Wegaufzeichnung

Stationen und Weg getrennt speichern

• Stationen mit Koordinaten stehen als wpt unmittelbar unter gpx.
• Beim ersten Speichern eines neuen Entwurfs startet während der Bearbeitung eine Aufzeichnung: sofort eine Position, danach alle 30 Sekunden eine neue GPS-Abfrage. Schließen, Abbrechen, Rückkehr zur Streckenliste oder Wechsel der Strecke beendet die Aufzeichnung. Nach einem Neustart ist sie inaktiv. Beim erneuten Öffnen eines lokalen Entwurfs zur Bearbeitung beginnt eine neue Sitzung. Speichern innerhalb derselben Sitzung hebt Pause oder bewusstes Stoppen nicht auf.
• Die sichtbaren Schaltflächen erlauben Pausieren, Fortsetzen und Beenden. Beim Löschen des Entwurfs endet die Aufzeichnung ebenfalls.
• Tatsächliche Positionen stehen als trk/trkseg/trkpt mit Zeitstempel und, falls vorhanden, Höhe in der Datei des Entwurfs.
• Ohne Standort entsteht eine Erweiterung wegwichtel:gpsGap mit Zeitstempel. Eine Station ohne Standort steht als wegwichtel:pendingWaypoint in den Erweiterungen. Es werden keine Koordinaten wie 0,0 erfunden. Leere GPX- wpt oder trkpt wären ungültig, daher werden Erweiterungen verwendet.

Die Aufzeichnung speichert immer die neueste Fassung des Entwurfs, damit gleichzeitige Änderungen an Stationen erhalten bleiben. Auch eine manuelle Bearbeitung ergänzt die neueste Aufzeichnung und bewahrt inzwischen hinzugekommene Positionen. Speicherfehler pausieren die Aufzeichnung und zeigen einen Hinweis.

Später Koordinaten ergänzen

Entwürfe und Stationen dürfen ohne GPS erstellt und gespeichert werden. In der Streckenbearbeitung können unter „Orte auf dem Weg ergänzen“ fehlende Positionen ergänzt, vorhandene geändert und weitere hinzugefügt werden. Breiten- und Längengrad müssen gemeinsam angegeben werden oder beide leer bleiben. Stationen haben eigene Felder unter „Ort ergänzen“.

Die Serverdatenbank erlaubt NULL in pois.lat und pois.lon. Die Tabelle route_points entfällt. Routenpunkte, Start und Mittelpunkt, Weglänge, Höhengewinn und Punktzahl werden aus der gespeicherten GPX-Datei gelesen beziehungsweise berechnet. Die Änderung ist in database/schema.sql enthalten; eine bestehende Datenbank bekommt sie nicht allein durch das Kopieren des Codes. Das Projekt verwendet beim Deployment die vereinbarte Neuerstellung der Datenbank, keine automatische Migration.

SQLite enthält weiterhin Verwaltungseinträge, Freigaben sowie Stations- und Medienangaben. Von den berechneten Routenwerten bleiben dort ausschließlich min_lat, min_lon, max_lat und max_lon als Suchwerte erhalten. Die Näheresuche verwendet diese Grenzen zur Vorauswahl und berechnet anschließend den Abstand zum Start aus der GPX-Datei. Anlegen, Ersetzen, Anhängen und Änderungen an Stationen aktualisieren die Grenzen. Ohne Koordinaten bleiben alle vier leer.

Die Startprüfung erwartet dasselbe Schema einschließlich der optionalen Stationskoordinaten, lehnt die entfernte Tabelle und Routenspalten ab und prüft die Suchgrenzen gegen die GPX-Dateien. Ein zusätzlicher Test führt die Prüfung in einem getrennten Prozess mit einer echten temporären Datenbank und Dateien aus. Damit wird der Fall einer vorhandenen Datenbank auch beim normalen Coverage-Lauf geprüft.

Normalisierung auf dem Server

Beim Einreichen oder Ersetzen einer GPX-Datei normalisiert der Node-Dienst den aufgezeichneten Weg zu rte/rtept. Bereits vorhandene Routenpunkte haben Vorrang. Aufeinanderfolgende Trackpunkte innerhalb des eingestellten Abstands werden zusammengefasst. Der erste Punkt bleibt der Vertreter; der nächste wird erst übernommen, wenn er weiter entfernt liegt. So werden kleine Schwankungen während einer Pause nicht fortlaufend zur Weglänge addiert.

GPX_CLUSTER_METERS in .env steuert den Abstand, standardmäßig 20 Meter. Das Verfahren ist eine geometrische Vereinfachung ohne externen Routingdienst. Es berechnet keine Wege auf einer Straßenkarte. GPS-Lücken werden bei der Routenberechnung übersprungen; zwischen gültigen Nachbarpunkten entsteht eine direkte Verbindung. Die Lücken bleiben für spätere Bearbeitung als Erweiterungen erhalten. Gibt es keine gültigen Wegpositionen, bleiben Weglänge und Punktzahl bei 0 Metern und 0 Punkten; Stationen bleiben trotzdem gespeichert.

Die gespeicherte Serverdatei enthält den normalisierten Weg. Änderungen an Stationen synchronisieren die wpt und die noch unvollständigen Stationen in dieser Datei. GPX verwendet unverändert den Namespace http://www.topografix.com/GPX/1/1; das ist eine Kennung, kein Netzwerkabruf.

Anzeige beim Abspielen

Zwei Pfeile zeigen gleichzeitig die Richtung:

• zum nächsten Routenpunkt, ohne Entfernungsangabe;
• zur nächsten noch offenen Station mit Koordinaten, mit Metern.

Bei einer Strecke mit ausschließlich Stationen fehlt nur die Wegführung. Stationen ohne Koordinaten lösen keine Standort-Erkennung aus. Während einer Pause werden die Pfeile verborgen.

Grenzen und Prüfung

Die Aufzeichnung läuft nur im geöffneten App-Fenster. Neuladen beendet sie; bereits gespeicherte Positionen bleiben erhalten. Browser und Betriebssystem können Zeitgeber und Standort-Abfragen im Hintergrund oder bei gesperrtem Bildschirm verzögern. Ein verlässlicher Hintergrunddienst wird nicht zugesichert. Bei verweigerter Standort-Erlaubnis bleiben die Einträge leer und bearbeitbar.

Die Tests prüfen Aufzeichnung, Pause/Fortsetzen/Ende, verspätete GPS-Antworten, Speicherfehler, GPS-Lücken, manuelle Ergänzungen, getrennte Pfeile, Servernormalisierung sowie Stationen ohne Koordinaten über die API.