303 lines
10 KiB
Markdown
303 lines
10 KiB
Markdown
# 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?
|
|
|