158 lines
11 KiB
Markdown
158 lines
11 KiB
Markdown
# Wegwichtel Next
|
|
|
|
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 und `fast-xml-parser`
|
|
- **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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```dotenv
|
|
HOST=127.0.0.1
|
|
PORT=47145
|
|
```
|
|
|
|
`HOST` ist die tatsächliche Bind-Adresse des Node.js-Servers. Der Health-Endpunkt meldet beispielsweise:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"service": "wegwichtel",
|
|
"socket": "127.0.0.1:47145"
|
|
}
|
|
```
|
|
|
|
## Initialisierungsablauf des Clients
|
|
|
|
1. statischer Initialisierungsbildschirm erscheint ohne Bibliotheksabhängigkeit,
|
|
2. lokale jQuery-Datei wird geladen und auf Version 4.0.0 geprüft,
|
|
3. lokales jQuery UI 1.14.2 samt Base-Theme wird geladen und über `jQuery.ui.version` geprüft,
|
|
4. die Clientmodule werden sequenziell geladen,
|
|
5. `/api/health` prüft Server und SQLite,
|
|
6. der Client lädt die Routenliste,
|
|
7. anschließend wird die Position ermittelt; daraus entstehen nahe Empfehlungen, während die Gesamtliste vollständig erhalten bleibt,
|
|
8. 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:
|
|
|
|
```text
|
|
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`](docs/REST-API.md) dokumentiert. Die README beschreibt bewusst nur Installation, Architektur und Bedienverhalten.
|
|
|
|
## Dateistruktur
|
|
|
|
```text
|
|
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/ Basistests
|
|
```
|
|
|
|
## Technische Hinweise
|
|
|
|
- Medienpfade werden relativ zu `storage/` gespeichert. So bleibt das Projekt verschiebbar. Bild- und Audiodateien werden der Clientanwendung ausschließlich über `/api/routes/:id/pictures/:pictureId` beziehungsweise `/api/routes/:id/audio?poiId=:poiId` bereitgestellt.
|
|
- 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.
|
|
- Schreibzugriffe sind noch nicht authentifiziert. Vor einem öffentlichen Einsatz sind Rollen, Login, CSRF-Schutz, Rate-Limits, Dateisignaturprüfung und ein Moderationsworkflow zwingend zu ergänzen.
|
|
- 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:
|
|
|
|
```javascript
|
|
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.
|