Erster Commit

knowledge/directus_struktur.md

@@ -0,0 +1,375 @@
+# Directus Datenbankstruktur — Language App
+
+**Domain:** https://db.hejyou.com
+**Stand:** 2026-04-23
+**Eigene Collections:** 10 (inkl. Junction `questions_words`)
+**Frontend:** React 19 + Vite, kein Router-Package (State-basiertes Routing)
+
+---
+
+## App-Konzept (Kurzfassung)
+
+Social-Media-Feed-Style-Sprachlern-App mit Fokus auf "Language Parenting" (Kontext & Immersion statt Grammatikdrill).
+
+**Datenfluss:**
+1. Ein Bild wird in `pictures` hochgeladen
+2. KI-Analyse erkennt Objekte → werden in `objects` gespeichert (mit bbox, confidence, Label-Wort)
+3. Zum Bild werden `questions` generiert (z. B. "Kannst du die Möwe fliegen sehen?")
+4. Jedes Wort der Frage wird in `words` gespeichert und per M2M (`questions_words`) verknüpft
+
+**Lern-Flow in der App:**
+- User scrollt durch Feed-Kacheln
+- Kacheln existieren **nicht als DB-Einträge**, sondern werden dynamisch aus `words` / `questions` generiert
+- Kachel-Typen: `listen`, `speak`, `write`, `multiple_choice`, `image_match`, `sentence_fill`
+- 1 EP pro gelöster Kachel
+- Erst alle Wörter einer Frage auf Ziellevel → dann Satzfrage freischalten
+- Danach gemischter Feed
+
+---
+
+## Sprachrichtung
+
+- **Zielsprachen:** Alle drei gegenseitig (DE/EN/SE × DE/EN/SE)
+- Gespeichert in `directus_users.language_native` + `language_target` (M2O → `language_options`)
+- Zusätzlich `learning_pairs` pro aktive Sprachrichtung (mit eigenem Level + Punkten)
+
+---
+
+## App-Architektur (Frontend)
+
+### Navigation
+4 Seiten, über `BottomNav` (Tabs) gesteuerter `useState`-Router in `App.jsx`:
+
+| Tab | Seite | Status |
+|-----|-------|--------|
+| Feed   | `pages/Feed.jsx`   | Implementiert, Directus-Daten |
+| Game   | `pages/Game.jsx`   | Placeholder |
+| Pro    | `pages/Pro.jsx`    | Placeholder |
+| Profil | `pages/Profil.jsx` | Implementiert, Directus-Daten |
+
+`App.jsx` zeigt `<AuthScreen />` wenn `!user.username || !user.language_native || !user.language_target`.
+
+### Auth-Flow (2 Schritte)
+
+```
+RegisterStep1 (E-Mail + Passwort)
+  → registerUser() + login() → Token in localStorage (hejyou_token)
+  → onSuccess(userId, token) → RegisterStep2
+
+RegisterStep2 (Username + Muttersprache + Zielsprache)
+  → checkUsername() → createProfile()
+    → POST /items/users_language
+    → PATCH /users/:id  (username, language_native, language_target)
+    → PATCH /items/users_language/:id  (user-Verknüpfung)
+    → POST /items/learning_pairs
+  → setUser() → AuthScreen zeigt Erfolgsscreen
+
+AuthContext überwacht Token, ruft getMe() beim Start
+```
+
+Token-Key im localStorage: `hejyou_token`
+
+### Frontend API-Funktionen (`src/api/directus.js`)
+
+| Funktion | Endpoint | Zweck |
+|----------|----------|-------|
+| `login(email, pw)` | POST `/auth/login` | Token holen |
+| `getMe(token)` | GET `/users/me` | Basisfelder für Auth-Check |
+| `getProfilData(token)` | GET `/users/me` (erweitert) | Profil inkl. username-Objekt, points_total, streak_days |
+| `registerUser(email, pw)` | POST `/users` | Neuen Directus-User anlegen |
+| `checkUsername(name)` | GET `/items/users_language` (filter) | Verfügbarkeit prüfen |
+| `createProfile(...)` | 4 PATCH/POST-Calls | Vollständiges Onboarding |
+| `getActiveLearningPair(profileId)` | GET `/items/learning_pairs` (filter active) | Aktives Lernpaar des Nutzers |
+| `getWords(limit)` | GET `/items/words` | Wörter für Feed-Karten |
+| `langById(id)` | lokal | LANGUAGE_OPTIONS-Lookup per UUID |
+
+### LANGUAGE_OPTIONS (Frontend-Konstante)
+
+```js
+// Felder pro Sprache:
+{ id, label, flag, suffix, speech }
+```
+
+| Sprache | suffix | speech |
+|---------|--------|--------|
+| Deutsch | `de` | `de-DE` |
+| Englisch | `en` | `en-US` |
+| Schwedisch | `se` | `sv-SE` |
+
+`suffix` wird genutzt um DB-Felder dynamisch zu bauen: `title_${suffix}` (z.B. `title_de`).
+`speech` wird an die Web Speech API (SpeechRecognition) übergeben.
+
+### Feed-Karten-Generierung
+
+`buildCards(words, fromLang, toLang)` erzeugt pro Wort bis zu 3 Kacheln:
+
+| Kachel-Typ | Komponente | Bedingung |
+|------------|-----------|-----------|
+| `text`   | `NewWordTextCard`  | immer |
+| `voice`  | `NewWordVoiceCard` | immer |
+| `letter` | `LetterOrderCard`  | `word.length >= 4` |
+
+Felder aus DB: `word = words.title_${to.suffix}`, `translation = words.title_${from.suffix}`
+
+Zusätzlich werden Demo-Karten (`DEMO_EXTRA`) an den echten Feed angehängt, solange Bilder/Audio noch nicht in der DB vorhanden sind (ImagePickCard, AudioQuizCard, ImageQuizCard).
+
+> **Noch nicht implementiert:** Nach Kartenabschluss wird aktuell **kein** `user_progress`-Eintrag angelegt und `learning_pairs.points` wird nicht aktualisiert. Das ist der nächste Schritt.
+
+---
+
+## Collections im Überblick
+
+| Collection | Zweck |
+|---|---|
+| `categories` | Kategorien für Wörter/Objekte (Farben, Zuhause, Tiere, …) |
+| `language_options` | Verfügbare Sprachen (DE/EN/SE) |
+| `learning_pairs` | Aktive Sprachrichtungen pro Nutzer, mit Level & Punkten |
+| `objects` | Von KI erkannte Objekte in Bildern (bbox, confidence) |
+| `pictures` | Bilder, Ausgangspunkt für Fragen |
+| `questions` | Fragen/Sätze für den Lernfeed |
+| `questions_words` | Junction: M2M Fragen ↔ Wörter |
+| `user_progress` | Lernfortschritt pro Nutzer × Kachel |
+| `users_language` | Öffentliches Profil (Username, Avatar) |
+| `words` | Vokabeln in DE/EN/SE mit Level & Kategorie |
+
+---
+
+## Collection-Details
+
+### `categories`
+Kategorien für Wörter und Objekte.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `status` | string | draft/published/archived |
+| `sort` | integer | Sortierreihenfolge |
+| `Icon` | string | Material-Icon-Name |
+| `type` | string | Dropdown, Werte undefiniert |
+| `title_en/de/se` | string | Titel in 3 Sprachen |
+
+---
+
+### `language_options`
+Verfügbare Sprachen.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `status` | string | |
+| `short` | string | Kurzcode: `de`, `en`, `se` |
+| `title_en/de/se` | string | |
+
+> Frontend-Mapping: `LANGUAGE_OPTIONS` in `directus.js` ergänzt die DB-Werte um `suffix` (= `short`), `speech` (Web Speech API Code), `flag` (Emoji) und `label` (Anzeigename auf Deutsch).
+
+**Aktuelle Einträge:**
+- DE: `88053026-3d7e-4799-b10d-67187f7c1709`
+- EN: `99fbaa9d-3cac-48cb-a5e2-dcb320e913e4`
+- SE: `25350b32-e9ab-4fec-946e-c0f11eff70dd`
+
+---
+
+### `learning_pairs`
+Welche Sprachrichtungen ein Nutzer aktiv lernt.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `user` | uuid M2O → `users_language` | |
+| `language_from` | uuid M2O → `language_options` | Ausgangssprache |
+| `language_to` | uuid M2O → `language_options` | Zielsprache |
+| `active` | boolean | Aktuell aktiv? |
+| `current_level` | integer (1–10) | Aktuelles Level in dieser Richtung |
+| `points` | integer | Punkte in dieser Richtung |
+
+---
+
+### `words`
+Vokabeln in 3 Sprachen.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `status` | string | |
+| `title_de/en/se` | string | Wort in 3 Sprachen |
+| `categories` | uuid M2O → `categories` | Ein Wort gehört zu einer Kategorie |
+| `image` | uuid file → `directus_files` | Bild zum Wort (optional) |
+| `audio_de/en/se` | uuid file → `directus_files` | Aussprache pro Sprache |
+| `level` | integer (1–10) | Schwierigkeitslevel |
+| `times_learned` | integer | Global, wie oft insgesamt gelernt |
+| `related_questions` | alias M2M → `questions` | Alle Fragen, in denen das Wort vorkommt |
+
+> `getWords()` fetcht aktuell nur `id, title_de, title_en, title_se, level`. `image` und `audio_de/en/se` werden noch nicht geladen → ImagePickCard und AudioQuizCard laufen noch mit Demo-Daten.
+> **Hinweis (2026-04-23):** Felder `categories`, `image`, `audio_de`, `audio_en`, `audio_se` wurden mit korrekten FK-Relationen und `special`-Markierungen angelegt.
+
+---
+
+### `questions`
+Fragen/Sätze, die im Feed erscheinen.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `status` | string | |
+| `question_de/en/se` | string | Frage in 3 Sprachen |
+| `answer_de/en/se` | string | Korrekte Antwort |
+| `level` | integer (1–10) | Schwierigkeitslevel |
+| `related_words` | alias M2M → `words` | Alle Wörter der Frage |
+
+> Hinweis: `questions.type` (Kachel-Typen) wurde entfernt – Kacheln werden dynamisch in der App generiert, nicht pro Frage gespeichert.
+
+---
+
+### `questions_words`  (Junction-Collection für M2M)
+Verknüpft Fragen und Wörter (M:N).
+
+| Feld | Typ |
+|---|---|
+| `id` | integer (PK, auto) |
+| `questions_id` | uuid → `questions` (CASCADE) |
+| `words_id` | uuid → `words` (CASCADE) |
+
+---
+
+### `pictures`
+Bilder als Ausgangspunkt für Fragen.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `media` | uuid → directus_files | Das eigentliche Bild |
+| `type` | string | `simple_object` / `multi_object` |
+| `season` | string | `spring`/`summer`/`fall`/`winter` |
+| `objects` | uuid M2O → `objects` | Legacy-Feld (zeigt auf ein einzelnes Objekt, nicht mehr nutzen) |
+| `objects` (O2M alias) | alias O2M ← `objects.picture` | Alle Objekte dieses Bildes — über `objects.picture` Relation |
+
+> **Hinweis:** Die korrekte Beziehung läuft über `objects.picture` (M2O von objects zu pictures). Das alte `pictures.objects`-Feld ist ein Legacy-FK und wird nicht mehr befüllt.
+
+---
+
+### `objects`
+Von der KI erkannte Objekte innerhalb eines Bildes.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `picture` | uuid M2O → `pictures` | Bild, zu dem dieses Objekt gehört (O2M-Seite: `pictures.objects`) |
+| `media` | uuid → directus_files | Optionaler Zuschnitt des Objekts im Bild |
+| `categories` | uuid M2O → `categories` | |
+| `label` | uuid M2O → `words` | Name des Objekts als Wort |
+| `color` | uuid M2O → `words` | Farbe des Objekts (optional) |
+| `action` | uuid M2O → `words` | Aktion des Objekts (z. B. "fliegen") |
+| `questions` | uuid M2O → `questions` | Generierte Frage zum Objekt |
+| `resolution` | string | z. B. `1920x1080` |
+| `confidence` | float | KI-Konfidenz 0–1 |
+| `bbox` | json | `{x, y, w, h}` |
+| `polygon` | json | Polygon-Koordinaten |
+| `parent` | uuid M2O → `objects` | Hierarchie (Szene → Teilobjekte) |
+
+> **Hinweis (2026-04-23):** `objects.picture` wurde ergänzt, um die O2M-Beziehung zu `pictures` herzustellen. Ein Bild kann nun mehrere Objekte haben. Bestehende Testdaten (Möwen-Objekt) wurden verknüpft.
+
+---
+
+### `users_language`
+Öffentliches Nutzerprofil (gekoppelt mit `directus_users`).
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `username_public` | string | Angezeigter Name |
+| `username_lowercases` | string | Für Suche/Eindeutigkeit |
+| `user` | uuid M2O → `directus_users` | Verknüpfung zum System-User |
+
+---
+
+### `directus_users` (System-Collection, custom fields)
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `app_type` | string | `socialmedia` / `language` |
+| `language_native` | uuid M2O → `language_options` | Muttersprache |
+| `language_target` | uuid M2O → `language_options` | Zielsprache |
+| `username` | uuid M2O → `users_language` | Verknüpfung zum Profil |
+| `points_total` | integer | Gesamtpunkte über alle Richtungen |
+| `streak_days` | integer | Aktuelle Lernserie (Tage) |
+| `streak_last_activity` | date | Für Streak-Berechnung |
+
+---
+
+### `user_progress`
+Trackt jede gelöste/übersprungene Kachel pro Nutzer.
+
+> **Status:** Schema definiert, aber noch **nicht in der App implementiert**. Karten-Ergebnisse werden aktuell nur lokal angezeigt, nicht in die DB geschrieben. Nächster Schritt: `saveProgress()`-Funktion in `directus.js` + Aufruf nach Kartenabschluss.
+
+| Feld | Typ | Notiz |
+|---|---|---|
+| `id` | uuid (PK) | |
+| `user` | uuid M2O → `users_language` | Nutzerprofil |
+| `question` | uuid M2O → `questions` | Wenn Kachel zu einer Frage gehört |
+| `word` | uuid M2O → `words` | Wenn Kachel zu einem Einzelwort gehört |
+| `card_type` | string | `listen` / `speak` / `write` / `multiple_choice` / `image_match` / `sentence_fill` |
+| `result` | string | `correct` / `wrong` / `skipped` |
+| `points_earned` | integer | Verdiente EP (1 pro gelöster Kachel) |
+| `language_from` | uuid M2O → `language_options` | Ausgangssprache |
+| `language_to` | uuid M2O → `language_options` | Zielsprache |
+
+> Entweder `word` ODER `question` ist gesetzt, je nachdem ob die Kachel ein Einzelwort oder eine Satzfrage trainiert.
+
+---
+
+## Beziehungs-Diagramm
+
+```
+users_language ──┬── learning_pairs (pro Sprachrichtung)
+                 ├── user_progress (pro Kachel)
+                 └── directus_users (System-User)
+
+pictures ──── objects (O2M via objects.picture) ──── questions
+   │              │                                       │
+   └── media      ├── picture → pictures (M2O)            ├── related_words (M2M via questions_words)
+                  ├── label → words                       └── answer (de/en/se)
+                  ├── color → words
+                  └── action → words
+
+words ──── categories (M2O)
+      ├── image → directus_files
+      └── audio_de/en/se → directus_files
+```
+
+---
+
+## Testdaten (Tim, Stand 2026-04-22)
+
+- **User (users_language):** `24f9a499-e36d-4df8-91f7-6a7abc6f42ce` (Tim1505)
+- **3 Kategorien:** Farben, Zuhause, Tiere
+- **12 Wörter** (Rot, Blau, Grün, Tisch, Stuhl, Fenster, Hund, Katze, Vogel, Möwe, fliegen, sehen)
+- **8 Fragen** (7 Single-Word + 1 komplexe Möwen-Frage mit 3 verknüpften Wörtern)
+- **1 Bild** im Herbst (`multi_object`) mit erkanntem Möwen-Objekt (94% confidence)
+- **2 learning_pairs:** DE→SE (aktiv, 30P), DE→EN (inaktiv, 10P)
+- **6 user_progress-Einträge** mit verschiedenen card_types (listen/speak/write/multiple_choice/image_match)
+
+---
+
+## Offene Punkte / Nächste Schritte
+
+| Priorität | Aufgabe |
+|-----------|---------|
+| 🔴 | `user_progress` schreiben nach Kartenabschluss |
+| 🔴 | `learning_pairs.points` + `directus_users.points_total` updaten |
+| 🟠 | `words.image` + `words.audio_*` in `getWords()` laden → echte ImagePickCard / AudioQuizCard |
+| 🟠 | `directus_users.streak_days` + `streak_last_activity` serverseitig aktualisieren |
+| 🟡 | `questions` Collection in Feed integrieren (Satzlevel-Kacheln) |
+| 🟡 | Game und Pro Pages implementieren |
+
+---
+
+## Kachel-Logik (für die App)
+
+Die App generiert Kacheln dynamisch aus den vorhandenen Daten eines Wortes:
+
+- `audio_de/en/se` vorhanden → `listen`, `speak` möglich
+- `image` vorhanden → `image_match` möglich
+- Mindestens 3 Wörter in gleicher Kategorie → `multiple_choice` möglich
+- Zielsprache setzen via `learning_pairs.language_to`
+
+Pro Abschluss: +1 EP in `user_progress.points_earned` + Update in `learning_pairs.points`.