2nd Brain

README

/home/darth/Documents/Mardowns/10_Projekte/aktuell_27.11/frontend/README.md

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

DateiZweckBeispielwerte
.envlokale EntwicklungVITE_BASE_URL_BACK=http://localhost:5500, VITE_API_PREFIX=/api/v3
.env.coding60Staging/PreviewVITE_BASE_URL_BACK=https://coding60.plus, VITE_API_PREFIX=/api/v3
.env.muc4taxiProduktionVITE_BASE_URL_BACK=https://muc4taxi.eu, VITE_API_PREFIX=/api/v3

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.

Attachments
Noch keine.