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

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?