# 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?