APP als Hybrid Version - Anbindung an API

frontend/dev/db-api-connect/README.md

@@ -0,0 +1,303 @@
+# Entwicklungsplan DB/API-Anbindung
+
+Version: `0.0.1`
+
+Status: Konzept und Umsetzungsplan fuer die Anbindung der Quasar-App an das Laravel-Backend mit MySQL.
+
+## Zielbild
+
+Die App soll nicht mehr primaer auf browserlokaler Persistenz basieren. Laravel mit MySQL wird die fuehrende Datenquelle fuer User, Settings, Events, Presets und Medien. IndexedDB und `localStorage` duerfen spaeter weiter als Cache und Offline-Schicht genutzt werden, aber nicht als alleinige Wahrheit.
+
+Das System geht konsequent vom eingeloggten User aus:
+
+- Jeder User besitzt eigene Settings.
+- Jeder User besitzt eigene Timeline-Daten.
+- Jeder User besitzt eigene Events.
+- Jeder User besitzt eigene Medien, Images, Presets und spaeter Videos, Audios und Texte.
+- Kein User darf Medien, Events oder Settings eines anderen Users direkt oder indirekt lesen.
+- Teilen und Veröffentlichen wird spaeter bewusst als eigener Rechte- und Freigabeprozess umgesetzt.
+
+## Versionsregel
+
+Die aktuelle App-Version ist `0.0.1`.
+
+Bei jeder weiteren Entwicklungsrunde muessen folgende Stellen mitgefuehrt werden:
+
+- `frontend/package.json`
+- `frontend/src/config/appVersion.js`
+- `frontend/README.md`
+- dieses Planungsdokument, sofern sich Architektur, Datenmodell oder API-Verhalten aendern
+- spaetere Release Notes oder Migrationsdokumente
+
+Versionen in der `0.x`-Phase duerfen Breaking Changes enthalten. Jede Aenderung am Datenmodell oder an API-Kontrakten muss trotzdem dokumentiert werden.
+
+## Grundentscheidung
+
+Wir verwenden direkt MySQL im Laravel-Backend. SQLite wird nicht als Zielsystem genutzt, weil die Anwendung mehrere Benutzer, geschuetzte Medien, Sync und spaetere Sharing-/Invite-Funktionen benoetigt. MySQL passt besser zu dauerhaftem Betrieb, Indizes, Relationen und wachsendem Medien-Metadatenbestand.
+
+## Sicherheitsprinzip
+
+Die Datenhoheit liegt beim User. Alle API-Abfragen muessen serverseitig ueber den authentifizierten User eingeschraenkt werden. Das Frontend darf keine fremden IDs als Vertrauensbasis liefern.
+
+Regeln:
+
+- Jede userbezogene Tabelle enthaelt `user_id`.
+- API-Controller filtern immer ueber `$request->user()`.
+- Policies pruefen Zugriff auf Events, Medien, Presets und Settings.
+- Storage-Pfade enthalten keine erratbaren oeffentlichen URLs.
+- Originalmedien werden nicht aus einem public disk ausgeliefert.
+- Medien werden ueber autorisierte Backend-Routen oder signierte, kurzlebige URLs bereitgestellt.
+- Thumbnails duerfen ebenfalls nur nach Berechtigungspruefung ausgeliefert werden.
+
+## Datenmodell
+
+Bestehende Basis:
+
+- `users` existiert bereits.
+- `events` existiert bereits und hat bereits `user_id`.
+
+Geplante Erweiterungen:
+
+- `user_settings`
+  - `user_id`
+  - `settings` als JSON
+  - `timeline_zoom`
+  - `timeline_scroll_left`
+  - `active_preset_id`
+  - Timestamps
+
+- `setting_presets`
+  - `user_id`
+  - `name`
+  - `settings` als JSON
+  - `is_public` fuer spaeteres Veröffentlichen von reinen Timeline-/Visual-Presets
+  - Timestamps
+
+- `events`
+  - weiterhin strikt usergebunden
+  - Erweiterung um Felder aus dem aktuellen Frontend, z. B. Key-Image-Titel, Farbdaten, Notizen und spaetere Event-Metadaten
+  - `client_id` bleibt wichtig fuer Offline-/Sync-Kompatibilitaet
+
+- `event_media`
+  - `user_id`
+  - `event_id`
+  - `type`: image, video, audio, text
+  - `title`
+  - `original_path`
+  - `thumbnail_path`
+  - `mime_type`
+  - `size`
+  - `width`
+  - `height`
+  - `duration`
+  - `sort_order`
+  - `metadata` als JSON
+  - Timestamps
+
+- `event_media_variants`
+  - optional spaeter, wenn mehrere Bildgroessen benoetigt werden
+  - z. B. thumbnail, preview, original
+
+- `timeline_shares`
+  - spaeter
+  - Einladung oder Share-Link fuer eine komplette Timeline
+  - getrennt von Preset-Sharing
+  - eigene Berechtigungen und Ablaufdaten
+
+## Medienkonzept
+
+Medien werden nicht als Data-URL in der Datenbank gespeichert. Die Datenbank speichert nur Metadaten und Storage-Pfade.
+
+Upload-Ablauf:
+
+1. Frontend laedt Datei an Laravel hoch.
+2. Backend validiert User, Dateityp und Groesse.
+3. Backend speichert Originaldatei in einem geschuetzten Storage-Bereich.
+4. Backend erzeugt Thumbnail oder Preview.
+5. Backend speichert Metadaten in `event_media`.
+6. API gibt Media-Objekt mit Thumbnail-Endpunkt zurueck.
+
+Performance-Regel:
+
+- Timeline und Event-Panel laden zuerst nur Thumbnails.
+- Originaldateien werden erst bei grosser Betrachtung oder Download geladen.
+- Videos und Audios bekommen spaeter eigene Preview-/Poster-Strategien.
+- Texte werden spaeter als eigener Media-Typ behandelt, nicht als Bilderspezialfall.
+
+## API-Konzept
+
+Geplante API-Gruppen unter `/api`:
+
+- Auth
+  - Login
+  - Logout
+  - aktueller User
+
+- Settings
+  - `GET /settings`
+  - `PUT /settings`
+
+- Presets
+  - `GET /setting-presets`
+  - `POST /setting-presets`
+  - `PUT /setting-presets/{preset}`
+  - `DELETE /setting-presets/{preset}`
+  - spaeter: `POST /setting-presets/{preset}/publish`
+
+- Events
+  - `GET /events`
+  - `POST /events`
+  - `GET /events/{event}`
+  - `PUT /events/{event}`
+  - `DELETE /events/{event}`
+  - `POST /events/sync`
+
+- Event-Medien
+  - `GET /events/{event}/media`
+  - `POST /events/{event}/media`
+  - `PUT /events/{event}/media/{media}`
+  - `DELETE /events/{event}/media/{media}`
+  - `GET /media/{media}/thumbnail`
+  - `GET /media/{media}/original`
+
+Alle Endpunkte muessen authentifiziert sein. Jeder Zugriff auf `{event}`, `{media}` oder `{preset}` muss serverseitig gegen `user_id` abgesichert werden.
+
+## Frontend-Migration
+
+Aktueller Zustand:
+
+- Auth liegt in `localStorage`.
+- Zusaetzlich angelegte lokale Test-User liegen in `localStorage` unter `thatsme-users`.
+- Settings liegen in `localStorage`.
+- Events, SyncQueue und Medien liegen in IndexedDB.
+
+Zwischenstand in Version `0.0.1`:
+
+- Die urspruenglichen Demo-User `user1` bis `user5` behalten ihre bestehenden lokalen Daten.
+- Neue lokale User koennen auf der Login-Seite ueber den Plus-Button angelegt werden.
+- Neue lokale User starten mit leerer Timeline und bekommen keine automatisch generierten Test-Events.
+- Diese lokale User-Verwaltung ist nur eine Uebergangsloesung bis zur Laravel/MySQL-Auth.
+
+Zielzustand:
+
+- Auth laeuft ueber Laravel API.
+- Settings werden nach Login vom Backend geladen.
+- Events werden vom Backend geladen und im Store gehalten.
+- IndexedDB bleibt als Cache und optionale Offline-Queue.
+- Medien werden als Backend-URLs/IDs verwaltet, nicht mehr als Data-URLs im Event.
+
+Schrittweise Migration:
+
+1. API-Client im Frontend anlegen.
+2. Auth-Store auf Backend-Login vorbereiten.
+3. Settings-Store mit Backend-Laden/Speichern erweitern.
+4. Events-Store auf Backend-CRUD umstellen.
+5. Media-Upload ueber Backend einbauen.
+6. IndexedDB als Cache neu definieren und nicht mehr als Primaerspeicher behandeln.
+7. SyncQueue mit Server-Status und Konfliktregeln ueberarbeiten.
+
+## Konflikt- und Sync-Regeln
+
+Da spaeter Offline-Faehigkeit weiter sinnvoll ist, bleibt `client_id` wichtig.
+
+Regeln:
+
+- Jeder lokal erzeugte Datensatz bekommt eine stabile `client_id`.
+- Backend antwortet mit Server-ID und `updated_at`.
+- Bei Updates wird `updated_at` fuer Konflikterkennung genutzt.
+- Bei Medien wird Upload nicht stillschweigend ueberschrieben.
+- Konflikte werden spaeter sichtbar gemacht, nicht automatisch fremd geloest.
+
+## Sharing spaeter
+
+Preset-Sharing und Timeline-Sharing werden getrennt.
+
+Preset-Sharing:
+
+- Nur visuelle Timeline-/LifeWave-Einstellungen.
+- Keine Events.
+- Keine Medien.
+- Keine personenbezogenen Inhalte.
+
+Timeline-Sharing:
+
+- Spaeter ueber Einladung, Token oder freigegebene Empfaenger.
+- Enthält Settings, Events und Medien nur im explizit freigegebenen Umfang.
+- Zugriff muss widerrufbar sein.
+- Keine oeffentlichen, erratbaren Medienlinks.
+
+## Umsetzungsphasen
+
+Phase 1: Backend-Datenmodell
+
+- Bestehende `events`-Tabelle mit aktuellem Frontend-Modell abgleichen.
+- Migrationen fuer `user_settings`, `setting_presets` und `event_media` erstellen.
+- Models, Relationships, Factories und Policies anlegen.
+- Tests fuer User-Isolation erstellen.
+
+Phase 2: API-Basis
+
+- API Resources und Form Requests erstellen.
+- Settings- und Preset-Endpunkte implementieren.
+- Event-Endpunkte usergesichert vervollstaendigen.
+- Tests fuer CRUD und Fremdzugriff schreiben.
+
+Phase 3: Media Storage
+
+- Geschuetzten Storage-Disk konfigurieren.
+- Upload-Endpunkte implementieren.
+- Thumbnail-Erzeugung vorbereiten.
+- Autorisierte Auslieferung fuer Thumbnail und Original bauen.
+- Tests fuer Zugriffsschutz und Dateitypen schreiben.
+
+Phase 4: Frontend-Anbindung
+
+- API-Service im Frontend erstellen.
+- Auth-Store an Backend anbinden.
+- Settings-Store vom Backend laden und speichern.
+- Events-Store CRUD und Sync an Backend anbinden.
+- EventPanel-Medienupload auf Server umstellen.
+
+Phase 5: Migration aus Browserdaten
+
+- Einmalige Importstrategie fuer lokale Demo-Daten definieren.
+- Pro User lokale Settings und Events optional zum Backend hochladen.
+- Danach lokale Daten nur noch als Cache nutzen.
+
+Phase 6: Dokumentation und Stabilisierung
+
+- API-Kontrakte dokumentieren.
+- Datenmodell dokumentieren.
+- Version aktualisieren.
+- Manuelle QA-Schritte dokumentieren.
+- Bekannte Grenzen und Folgeaufgaben festhalten.
+
+## Dokumentationspflicht pro Schritt
+
+Jede Umsetzung in diesem Bereich muss dokumentiert werden.
+
+Pflicht je Schritt:
+
+- Was wurde geaendert?
+- Welche Version betrifft es?
+- Welche Tabellen/API-Endpunkte sind betroffen?
+- Welche Sicherheitsregel wurde umgesetzt oder geprueft?
+- Welche Tests wurden ausgefuehrt?
+- Welche offenen Punkte bleiben?
+
+Empfohlene Struktur fuer neue Dokumente in diesem Ordner:
+
+- `README.md`: Gesamtplan und aktueller Stand
+- `data-model.md`: finale Tabellen und Beziehungen
+- `api-contract.md`: Request-/Response-Strukturen
+- `migration-log.md`: chronologische Umsetzungsschritte
+- `security-checklist.md`: Zugriffsschutz und Storage-Regeln
+
+## Offene Entscheidungen
+
+- Welche Laravel-Auth-Variante wird fuer die App final verwendet: vorhandenes Passport-Setup oder eine gezielte API-Token-Strategie?
+- Welche maximale Upload-Groesse gilt pro Datei und pro User?
+- Wo werden Originaldateien langfristig gespeichert: lokaler Storage, S3-kompatibel oder Synology C2?
+- Wann wird echte Offline-Synchronisation wieder aktiviert?
+- Wie detailliert soll spaeteres Timeline-Sharing steuerbar sein?
+