Wegwichtel/docs/agents/GPX-Aufzeichnung.md

# GPX und Wegaufzeichnung

## Stationen und Weg getrennt speichern

- Stationen mit Koordinaten stehen als `wpt` unmittelbar unter `gpx`.
- Der Schalter „Meinen Weg aufnehmen“ ist beim Start und beim Öffnen eines
  Entwurfs aus. Einschalten fragt sofort den Standort ab, danach alle zwei Minuten.
  Bei noch nicht gespeicherten Entwürfen beginnt die Aufnahme nach dem ersten Speichern.
  Schließen, Abbrechen, Rückkehr zur Streckenliste oder Wechsel der Strecke
  beendet die Aufzeichnung und schaltet sie aus. 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.
Das Zielkreuz an jedem Wegpunkt fragt frische GPS-Koordinaten ab und füllt nur
dessen Felder. Es startet keine Aufnahme; die Änderung muss gespeichert werden.
Verspätete Antworten nach dem Wechseln oder Schließen werden verworfen.
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 und gültige Stations-Wegpunkte zu `rte/rtept`. Bereits
vorhandene Routenpunkte bilden anstelle von Trackpunkten den Grundverlauf.
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.

Nach dem Vereinfachen des Tracks werden alle gültigen `wpt` ergänzt. Sie werden
nicht durch den Clusterabstand entfernt. Ihre Reihenfolge in der Datei bleibt
erhalten; der Einfügeort im verbleibenden Weg wird anhand der kleinsten
zusätzlichen Weglänge gewählt. Übereinstimmende Orte werden zusammengeführt.
Eine Strecke mit nur Stationen erhält einen Weg in Stationsreihenfolge.
Weglänge, Routenpunktzahl und Suchgrenzen beziehen sich auf den gemeinsamen Weg.

Aus Stationen ergänzte Routenpunkte tragen in ihren GPX-Erweiterungen die
Kennung `wegwichtel:waypointRoutePoint`. Dadurch lassen sich bei erneuter
Normalisierung bzw. Verschieben/Löschen einer Station alte ergänzte Anker
entfernen und anhand der aktuellen `wpt` neu berechnen. Ursprüngliche Wegpunkte
im aufgezeichneten Verlauf bleiben erhalten. Beim Anhängen einer anderen Strecke
wird deren berechneter Weg als zusätzlicher Verlauf übernommen. Wiederholte
Normalisierung darf keine zusätzlichen Stationsanker erzeugen.

`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 weder gültige Wegpositionen noch Stationen mit Koordinaten, 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 einem lokalen Entwurf mit ausschließlich Stationen fehlt vor dem Hochladen
die Wegführung. Nach dem Hochladen verbindet der berechnete Weg die Stationen.
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.