Neuaufbau des früheren schiffsbezogenen Ansagesystems als mobile Lernweg-Anwendung für Schulen. GPX-Strecken werden serverseitig verwaltet; POIs können einzeln verwaltete Bilder mit Beschreibungen und eine separat verwaltete Audioansage enthalten. Der Client schlägt anhand der aktuellen Position nahe Routen vor und aktiviert POIs während einer Wanderung über einen GPS-Watcher. Beim Erreichen eines POIs wird die Audioansage nur vorgeladen und erst nach einer bewussten Bedienung abgespielt.

Architektur

Server: Node.js 22.13+, Express 5, node:sqlite, Multer, fast-xml-parser, file-type und @file-type/av
Client: klassisches JavaScript, jQuery 4.0.0 und jQuery UI 1.14.2 mit lokalem Base-Theme
Medien: getrennte Verzeichnisse für aktive und zum Löschen markierte Strecken
Löschmodell: Soft Delete in SQLite plus atomisches Verschieben des gesamten Streckenordners in storage/trash/routes
Wiederherstellung: POST /api/routes/:id/restore verschiebt die Daten zurück und korrigiert alle gespeicherten Pfade

Schnellstart

cp .env.example .env
npm install
npm run init-db
npm start

Danach lauscht Wegwichtel ausschließlich auf dem lokalen Socket 127.0.0.1:47145 und ist unter http://127.0.0.1:47145 erreichbar. Die offiziellen, exakt versionierten Distributionsdateien sind bereits unter public/vendor enthalten. npm install installiert zusätzlich die Pakete jquery@4.0.0 und jquery-ui@1.14.2 und synchronisiert daraus JavaScript, Base-Theme, Themebilder und Lizenzdateien erneut in das Vendor-Verzeichnis. Der Browser lädt keine Bibliotheken von einem CDN.

Server-Socket

Die Standardwerte stehen in .env.example und werden auch verwendet, wenn keine .env vorhanden ist:

HOST=127.0.0.1
PORT=47145

HOST ist die tatsächliche Bind-Adresse des Node.js-Servers. Der Health-Endpunkt meldet beispielsweise:

{
  "ok": true,
  "service": "wegwichtel",
  "socket": "127.0.0.1:47145"
}

Initialisierungsablauf des Clients

statischer Initialisierungsbildschirm erscheint ohne Bibliotheksabhängigkeit,
lokale jQuery-Datei wird geladen und auf Version 4.0.0 geprüft,
lokales jQuery UI 1.14.2 samt Base-Theme wird geladen und über jQuery.ui.version geprüft,
die Clientmodule werden sequenziell geladen,
/api/health prüft Server und SQLite,
der Client lädt die Routenliste,
anschließend wird die Position ermittelt; daraus entstehen nahe Empfehlungen, während die Gesamtliste vollständig erhalten bleibt,
die responsive Routenansicht wird freigeschaltet.

Scheitert ein Schritt, bleibt der Initialisierungsbildschirm mit einer konkreten Fehlermeldung und einem Wiederholungsbutton sichtbar.

Lokale UI-Abhängigkeiten

Im Vendor-Verzeichnis liegen die zur Laufzeit verwendeten Dateien vollständig lokal:

public/vendor/jquery/jquery-4.0.0.min.js
public/vendor/jquery/LICENSE.txt
public/vendor/jquery-ui/jquery-ui-1.14.2.min.js
public/vendor/jquery-ui/jquery-ui-1.14.2.min.css
public/vendor/jquery-ui/images/*.png

Die Anwendung verwendet aus jQuery UI insbesondere das Widget Button. Das offizielle vollständige jQuery-UI-Bundle bleibt lokal verfügbar, damit weitere aktuelle Widgets ohne erneuten CDN-Bezug ergänzt werden können. Die frühere jQuery-Mobile-Seitensteuerung wurde durch eine eigene, History-API-basierte Navigation ersetzt.

API-Dokumentation

Die vollständige REST-API ist einschließlich aller Pfad-, Query-, Formular- und Datei-Parameter sowie ausführlicher curl-Beispiele in docs/REST-API.md dokumentiert. Die README beschreibt bewusst nur Installation, Architektur und Bedienverhalten.

Python-Werkzeuge

Unter tools/python/ liegen eigenständige Python-3-Skripte zum Anlegen, Ändern, Erweitern, Wiederherstellen und Löschen von Routen, POIs, Bildern und Audiodateien. Die Werkzeuge selbst verwenden ausschließlich die Python-Standardbibliothek. Fehlende Parameter werden interaktiv abgefragt. Antwortet ein vorgeschalteter Passwortschutz mit HTTP 401, fragt die gemeinsame Request-Schicht Benutzername und Passwort ab und wiederholt den Request. Fehler werden mit einer verständlichen Zusammenfassung und dem vollständigen Python-Stacktrace auf stderr ausgegeben.

Dateistruktur

public/                  mobiler Client
  index.html              reduzierte semantische Seitenstruktur
  js/bootstrap-loader.js  lädt und prüft lokale Bibliotheken
  js/orientation.js       Kompassausrichtung für den Navigationspfeil
  js/vibration.js         gekapselte Vibration mit benannten Mustern
  vendor/                lokale jQuery-/jQuery-UI-Dateien samt Themebildern
src/routes/              REST-Routing
src/services/            GPX-, Geodaten-, Speicher- und Fachlogik
database/schema.sql      SQLite-Schema
data/                    lokale SQLite-Datei
storage/active/routes/   aktive GPX-, Bild- und Audiodateien
storage/trash/routes/    zum Löschen markierte Strecken
examples/                Beispiel-GPX
test/                    automatisierte Tests
tools/python/            interaktive API-Werkzeuge ohne Node.js-Abhängigkeit

Automatisierte Tests

Die REST-Integrationstests starten die Anwendung über npm start mit isolierten temporären Daten- und Speicherverzeichnissen. Der eigentliche Node.js-Prozess lauscht innerhalb des Testaufbaus auf 127.0.0.1:47146. Davor läuft ein ausschließlich für die Tests bestimmter Reverse-Proxy auf http://127.0.0.1:47145, sodass dieser Loopback-Endpunkt das einzige Ziel der API-Aufrufe bleibt. Der Produktivserver wird von der Testsuite nicht angesprochen.

Der lokale Proxy lässt GET, HEAD und OPTIONS ohne Anmeldung passieren. Für POST, PUT, PATCH und DELETE antwortet er zunächst mit 401 Unauthorized und WWW-Authenticate: Basic, sofern kein gültiger Authorization-Header vorhanden ist. Nach erfolgreicher Basic-Auth-Prüfung entfernt der Proxy den Header wieder und leitet den Request an den lokal per NPM gestarteten Server weiter. Damit wird ein möglicher Nginx-Passwortschutz für schreibende Operationen realistisch simuliert, ohne Authentifizierung in die Anwendung selbst einzubauen.

Der Integrationstest prüft dabei ausdrücklich, dass lesende Requests nicht präventiv authentifiziert werden und dass für POST, PUT und DELETE jeweils zuerst ein 401 und anschließend ein erfolgreicher authentifizierter Request erfolgt. Zusätzlich bleibt ein kleiner, isolierter HTTP-Mock auf einem zufälligen Loopback-Port bestehen, der die 401-Wiederholungslogik der Python-Request-Schicht unabhängig vom vollständigen REST-Test prüft.

Die kombinierte Coverage wird mit folgenden Befehlen erzeugt:

npm ci
npm run test:coverage

Der Python-Coverage-Runner verwendet ausschließlich die Python-Standardbibliothek. Er führt die Unit-Tests mit unittest unter dem eingebauten trace-Modul aus und erzeugt daraus ohne pip oder zusätzliche Pakete einen Cobertura-kompatiblen Bericht. Ausführungsfehler werden mit vollständigem Python-Stacktrace auf stderr ausgegeben.

Dabei entstehen coverage/js/lcov.info für JavaScript und coverage/python/coverage.xml für die Python-Werkzeuge. Die zugehörigen SonarQube-Pfade stehen in sonar-project.properties. Die Coverage-Skripte erzwingen selbst keinen Mindestwert; die Bewertung und die Hinweise zu nicht abgedeckten Stellen bleiben Aufgabe des SonarQube Quality Gates.

Technische Hinweise

Medienpfade werden relativ zu storage/ gespeichert. So bleibt das Projekt verschiebbar.
Öffentliche GPX-, Bild- und Audiodateien werden ausschließlich über die zugehörigen /api/routes/...-Ressourcen ausgeliefert. Interne Speicherpfade und ein separates /media-URL-Schema werden nicht veröffentlicht.
Dateiverschiebung und Datenbankänderung sind durch eine kompensierende Rückverschiebung gekoppelt: Schlägt die SQL-Transaktion fehl, wird das Verzeichnis an seinen vorherigen Ort zurückbewegt.
GPX-Erweiterungen ergänzen die Trackpunkte in SQLite. Das Original-GPX bleibt im Skelett unverändert; ein späterer Exportdienst sollte aus den Datenbankpunkten eine konsolidierte GPX-Datei generieren.
Die Node.js-Anwendung authentifiziert Schreibzugriffe nicht selbst. Ein vorgeschalteter Nginx kann Basic Auth erzwingen; Rollen, CSRF-Schutz, Rate-Limits und ein Moderationsworkflow bleiben sinnvolle Ausbaustufen.
Uploadtypen werden serverseitig aus dem Inhalt erkannt. Binärformate verwenden file-type und @file-type/av; GPX wird als UTF-8-XML mit <gpx>-Wurzelelement geprüft. Dateiname und vom Client behaupteter MIME-Typ sind dafür unerheblich.
Der Server bindet standardmäßig nur an 127.0.0.1; Zugriffe von anderen Geräten sind damit bewusst ausgeschlossen.
Anwendungsaktionen verwenden Pointer Events für Touch, Stift und Maus. Enter und Leertaste bleiben als Tastaturbedienung erhalten.
Bei gestarteter Route zeigt ein fixierter Footer vorrangig Entfernung und Richtung zum nächstgelegenen, noch nicht erreichten POI. Der GPX-Fortschritt wird parallel entlang der Trackpunkte nachgeführt; sind alle POIs erreicht, übernimmt wieder der nächste GPX-Trackpunkt beziehungsweise das Routenziel. Ohne Kompassdaten wird die Peilung mit Norden oben dargestellt.
Auf iPhone und iPad wird die Freigabe der Geräteausrichtung beim Start der Route innerhalb der Benutzeraktion angefordert.
Für die Geolokalisierung sollte der Client lokal über http://127.0.0.1:47145 oder online ausschließlich über HTTPS geöffnet werden. Das betrifft ebenso den Gerätekompass.

Nächste Ausbaustufen

Administrationsoberfläche zum Zeichnen/Importieren von Routen und Platzieren der POIs
Benutzer-, Schul- und Projektzuordnung mit Rollenmodell
Offline-Cache/PWA für Wanderungen ohne Mobilfunkempfang
Kartenansicht, GPX-Visualisierung und Abweichungswarnung
Administrationsoberfläche für die bereits vorhandenen Einzelendpunkte zur Medienverwaltung
Hintergrundbereinigung des Papierkorbs nach einer konfigurierbaren Aufbewahrungsfrist
Integritätsjournal für Dateiverschiebungen und Wiederherstellungen

Routenauswahl

Die Startseite zeigt standortbasierte Empfehlungen und darunter alle aktiven Routen. Die Gesamtliste bleibt auch bei verweigertem oder nicht verfügbarem GPS auswählbar und kann nach Name, Schule oder Beschreibung durchsucht werden.

Mobile Bedienung und Routennavigation

Das HTML verwendet nur IDs, die von den Clientmodulen tatsächlich angesprochen werden. Die wenigen Klassen bilden wiederverwendete Layoutbausteine wie Seiten, Inhalte, Hinweise, Routenlisten und Routendaten ab. Automatisierte Tests gleichen diese Verwendungen ab.

Alle selbst implementierten Schaltaktionen reagieren primär auf pointerup; dadurch funktionieren dieselben Handler mit Touchscreen, Eingabestift und Maus. Die Diashow kann zusätzlich horizontal gewischt werden. Für die Tastatur werden Enter und Leertaste separat behandelt.

Beim Start der Route wird der aktuellen Position nächstgelegene GPX-Trackpunkt gesucht und der Fortschritt anschließend nur vorwärts entlang der Punktfolge nachgeführt. Für die sichtbare Navigation haben jedoch POIs Vorrang: Aus allen noch nicht automatisch aktivierten Stationen wird bei jeder Positionsänderung die räumlich nächstgelegene bestimmt. Der Footer zeigt:

Name und auf ganze Meter gerundete Luftlinienentfernung zum nächsten POI,
einen frei rotierenden SVG-Pfeil relativ zur Geräte- oder Bewegungsrichtung,
andernfalls die absolute Peilung bei Norden oben,
nach dem Aktivieren unmittelbar den nächsten noch offenen POI,
und erst nach Erreichen aller POIs wieder den nächsten GPX-Trackpunkt beziehungsweise das Routenziel.

In der Stationsliste erhält jeder POI rechts einen kleinen Richtungspfeil und seine aktuelle Entfernung in Metern. Diese Werte werden mit jeder GPS- oder Kompassaktualisierung neu berechnet. Die Reihenfolge der Stationsliste bleibt dabei unverändert.

Routensteuerung und GPS-Tracking

Die Routenansicht besitzt drei nebeneinanderliegende, semantische Schaltflächen mit lokalen SVG-Symbolen:

Route starten beziehungsweise fortsetzen: aktiviert navigator.geolocation.watchPosition() und die Geräteausrichtung.
Route pausieren: beendet den aktiven GPS-Watcher und den Kompass-Listener, pausiert eine laufende Audioansage und behält Routenfortschritt, Audioquelle, Abspielposition und bereits ausgelöste POIs bei.
Route beenden: beendet alle Sensor-Listener, hält die Audioansage an, entlädt ihre Quelldatei, setzt den Fortschritt zurück und kehrt zur Routenauswahl zurück.

Die aktuell geöffnete beziehungsweise automatisch aktivierte Station wird in der Stationsliste sichtbar hervorgehoben und mit aria-current="step" semantisch gekennzeichnet. Beim Eintritt in den Auslöseradius wird ihre Audiodatei mit preload="auto" vorbereitet, aber niemals automatisch gestartet. Die Wiedergabe beginnt ausschließlich über die nativen Audio-Bedienelemente.

Die Vibration API ist in public/js/vibration.js gekapselt. Die aus dem historischen Projekt übernommenen Konstanten MICRO, MINI, SHORT, LONG, ALARM und POI stehen unter Wegwichtel.Vibration.Patterns zur Verfügung. Für eine neu aktivierte Station wird ACTIVE_POI mit dem Muster [500, 300, 500] verwendet. Nicht unterstützende Browser ignorieren den Aufruf ohne Fehler; Pause und Beenden brechen ein laufendes Muster ab.

Beispiel für einen Aufruf mit Konstante:

Wegwichtel.Vibration.start(Wegwichtel.Vibration.Patterns.ACTIVE_POI);

Während die Route läuft, werden Positionsänderungen fortlaufend verarbeitet. Eine Browser-Webanwendung ist jedoch kein nativer Hintergrunddienst: Betriebssystem und Browser können die Aktualisierung bei gesperrtem Bildschirm, Energiesparmodus oder im Hintergrund drosseln beziehungsweise anhalten.

Die Symbole liegen unter public/images/icons/. Sie befinden sich innerhalb nativer <button>-Elemente. Die Bilder selbst sind dekorativ (alt=""); der zugängliche Name wird über aria-label und title am jeweiligen Button bereitgestellt.

Datenschutz, Impressum und lokale Browserdaten

Die Oberfläche enthält rechts oben einen global verfügbaren Informationsbutton. Er öffnet ein touch- und tastaturbedienbares Overlay mit Datenschutzerklärung, Impressum sowie einer technischen Erläuterung zu Cookies, Local Storage und den lokal eingebundenen JavaScript-Bibliotheken.

Die enthaltenen Rechtstexte sind technische Vorlagen. Vor einer öffentlichen Bereitstellung müssen insbesondere Betreiber, ladungsfähige Anschrift, Kontakt, Hostinganbieter, Protokollierungsdauer, Datenschutzkontakt und zuständige Aufsicht ergänzt und rechtlich geprüft werden. Eine Checkliste steht in docs/PUBLICATION-CHECKLIST.md.

Wegwichtel setzt selbst keine Cookies und bindet keine Analyse-, Werbe- oder Trackingdienste ein. Der Startbildschirm weist darauf hin. Die freiwillige Speicherung des Streckenfortschritts wird getrennt gesteuert:

wegwichtel.privacy.v1 speichert die gewählte Einstellung,
wegwichtel.route-progress.v1 enthält bei aktivierter Funktion ein JSON-Objekt mit aktueller Route, Routenstatus, besuchten und angesehenen Stationen, abgespielten Audioeinträgen und Zeitstempeln,
Streckendaten mit einer letzten Aktualisierung von mindestens 24 Stunden werden beim nächsten Start schrittweise entfernt,
beim Ausschalten der Funktion wird der gesamte Streckenfortschritt sofort aus dem Local Storage gelöscht,
ohne aktivierte Speicherung bleiben alle Routen- und Stationsdaten ausschließlich im Arbeitsspeicher des geöffneten Browserfensters.

Der Initialisierungsbildschirm bleibt nach erfolgreichem Laden sichtbar. Erst eine bewusste Pointer- oder Tastaturaktion öffnet die eigentliche Anwendung. Das Informationsfenster und die Datenschutzeinstellungen können bereits auf dem Startbildschirm verwendet werden, ohne die Anwendung weiterzuschalten.