MUC4TAXI Frontend & PWA

Dieses Dokument fasst zusammen, wie die aktuelle Web-App gebaut, getestet und deployed wird – inklusive der Migration auf /api/v3 und dem Legacy-Update-Flow.

Überblick

• Framework: Svelte + Vite
• PWA: Workbox (Inject Manifest) + virtual:pwa-register
• API-Basis: standardmäßig /api/v3 (konfigurierbar über VITE_API_PREFIX)
• Legacy-Erkennung: Service Worker wertet 426-Antworten bzw. X-Legacy-Client-Header aus und zeigt legacy-update.html an.

Voraussetzungen

• Node.js ≥ 18 (lokal verwendet: 20.x)
• PNPM/NPM/Yarn – wir nutzen NPM-Skripte
• Zugriff auf die passenden .env*-Dateien

Setup & Entwicklung

cd frontend
npm install

# Lokale Entwicklung (verwendet .env)
npm run dev

# Tests (Vitest)
npm run test -- --run

Umgebungen & ENV-Dateien

Wichtig: Die VITE_API_PREFIX-Variable muss immer vorhanden sein, damit Build-Artefakte garantiert /api/v3 ansprechen.

PWA-Details

• Registrierung erfolgt in src/main.js über registerSW({ immediate: true }).
• Der Service Worker (src/service-worker.js) nutzt Workbox und wird über vite-plugin-pwa eingebunden.
• Legacy-Erkennung:
  1. Server antwortet mit 426 + X-Legacy-Client.
  2. Runtime-Handler setzt LEGACY_REQUIRED.
  3. Navigations-Requests werden zu /legacy-update.html umgeleitet.
  4. App.svelte zeigt eine Blocking-Meldung für betroffene Benutzer.

Build & Deployment

# Standard-Build
npm run build

# Ziel-spezifisch (setzt NODE_ENV=production)
npm run build:coding60
npm run build:muc4taxi

Checkliste vor dem Deployment:

1. Passende .env.*-Datei vorhanden und vom CI/CD-Job übernommen.
2. Keine alten Service-Worker-Artefakte (public/serviceWorker.js aus Scripts) deployen.
3. Nach dem Release einmal npm run test -- --run (Vitest) sowie einen manuellen Smoke-Test durchführen:
   • Aktuelles Bundle lädt Daten über /api/v3.
   • Öffnen eines alten Bundles (falls möglich) → Update-Seite erscheint.

Legacy-Flow testen

1. Server: curl -i https://<host>/api/health → 426 + X-Legacy-Client + X-Legacy-Count.
2. Frontend: Lokales Build ohne VITE_API_PREFIX erzeugen oder die Network-Tab-Anfragen auf /api umschreiben. Erwartung: Service Worker zeigt Update-Seite, App blockiert mit Hinweis.
3. Modern Build: Alles läuft über /api/v3, keine Legacy-Hinweise im Log.

Weitere Aufgaben

• README (dieses Dokument) bei zukünftigen Änderungen am Update-Flow mitführen.
• Support- bzw. Onboarding-Mail-Templates sollen den Hinweis enthalten, dass Legacy-Clients automatisch auf eine Update-Seite weitergeleitet werden.

Mit dieser Dokumentation sollte ein Handover für das Frontend + PWA sowie den /api/v3-Umstieg reibungslos möglich sein.