localer plan

planung/datenbank-aufbau.md

@@ -0,0 +1,308 @@
+# Datenbank-Aufbau (Appwrite, self-hosted)
+
+**Stand:** Juli 2026 · basiert auf Appwrite TablesDB (Tabellen/Zeilen/Relationen), Functions, Storage mit S3-Adapter, Realtime, Auth + Teams, Messaging.
+
+**Grundsatz:** Die `brand-knowledge/`-Ordnerstruktur aus dem Konzept wird 1:1 in Tabellen abgebildet. Die .md-Textebenen (Beschreibung, Essenz, Details) bleiben als Markdown-Felder erhalten – strukturierte Daten (Scores, Zähler, Status) werden eigene Spalten, damit man danach filtern und sortieren kann.
+
+> **Update Juli 2026 – Bild-Modus, Feed & Ordner** (Konzept: `konzept-bilder-feed.md`)
+> Zwei strukturelle Änderungen, keine reinen Ergänzungen:
+> 1. **`attributes` ist aufgetrennt.** Scores und Zähler liegen jetzt in `attribute_scores` – ein Attribut trägt **mehrere Scores, einen je Ordner**. Ohne diesen Schnitt gäbe es keine ordnerbezogene Wissens-Segmentierung.
+> 2. **`assets` heißt fachlich „Modelle"** und kennt den neuen Typ `kulisse`. Der Begriff „Modell" meint in diesem Projekt durchgehend das Asset (Person, Produkt, Kulisse) – **nie** das KI-Modell (Seedance, Veo, Sora). Diese Sprachregelung gilt für Doku und Code.
+>
+> Neu dazu: `folders`, `attribute_scores`, `posts`, `post_images`, `post_folders`, `post_metrics`.
+
+---
+
+## 1. Appwrite-Features → unsere Nutzung
+
+| Appwrite-Feature | Wofür wir es nutzen |
+|---|---|
+| **Auth + Teams** | Jede Brand = ein Team. Zeilen-Rechte pro Team → sauberes Multi-Tenant ohne eigene Logik. Internes Admin-Team für den Dev-Modus. |
+| **TablesDB + Relationen** | Alle Tabellen unten; 4 Relationstypen decken Kategorie→Attribut, Attribut→Unter-Attribut (self-relation), Szene→Videos ab. |
+| **Storage (S3-Adapter!)** | Buckets laufen direkt auf **Hetzner Object Storage** als Backend – Appwrite verwaltet Rechte/Uploads, Hetzner speichert. Kein doppeltes System. |
+| **Functions** | Alle deterministischen Abläufe (Elo, Cron-Jobs) + Auslöser für LLM-Jobs. Event-getriggert oder geplant. |
+| **Realtime** | Live-Status in der App: „Script fertig → generiere Video 2/4 → Analyse läuft" ohne Polling. |
+| **Messaging** | Push/E-Mail: „Deine 4 Videos sind fertig – wähle das Beste." |
+
+---
+
+## 2. Tabellen
+
+### Mandant & Konfiguration
+
+**`brands`** – eine Zeile pro Kunde
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| team_id | string | Appwrite-Team (Rechte) |
+| label_name, produkte, zielgruppe, brand_worte[3], am_markt_seit | string | aus dem Onboarding (6 Pflichtfragen) |
+| **nische** | enum: kosmetik/auto/gastro/fitness/mode/… | **neu** – feste Branchenliste, Pflichtfrage im Onboarding. Filtert den Feed und steuert die Kopier-Kompatibilität |
+| stripe_customer_id | string | Payment |
+| default_video_count | int (3–6) | einstellbare Videoanzahl |
+| **plan** | enum: bild/video | **neu** – Bild-Modus ist die günstige Einstiegsstufe (Preismodell noch offen) |
+| status | enum: trial/aktiv/pausiert | |
+
+**`rules`** – feste Regeln (Dev-Modus) 🔒 *nur internes Team*
+| Spalte | Typ |
+|---|---|
+| brand_id | rel → brands (null = global für alle Brands) |
+| titel, prompt_text | string |
+| aktiv, sortierung | bool, int |
+
+**`prompt_templates`** – die statischen Prompts P1–P22 (Dev-Modus) 🔒 *nur internes Team*
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| key | enum P1…**P22** | siehe Prompt-Inventar (P19–P22 = Bild-Modus & Feed) |
+| version | int | Prompts sind versioniert – man muss zurückrollen können |
+| static_core_md | string | der statische Kern |
+| slots | json | welche Slots injiziert werden (REGELN, ASSETS, …) |
+| model_adapter | enum: null/seedance/veo/sora/wan | P8-Familie: ein Kern, mehrere Dialekte |
+| aktiv | bool | |
+
+### Knowledge Base
+
+**`folders`** – Wissens-Scope (neu)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| brand_id | rel → brands | **privat pro Brand** – Ordner sind kein soziales Objekt |
+| name, theme_md | string, string (Markdown) | „Dark Studio"; theme_md schreibt P20 beim Anlegen |
+| **zweck** | enum: sammlung / wissens_scope | `sammlung` = nur kategorisieren, keine Scores, kein Einfluss auf Generierung. `wissens_scope` = aus dem Ordner heraus wird erstellt |
+| **startwert_modus** | enum: erben / aus_posts | nur bei `wissens_scope`. `erben` = Kopie der brand-weiten Scores beim Anlegen · `aus_posts` = nur was in den gesammelten Posts steckt, Startwert = Kategorie-Ø **innerhalb des Ordners** |
+| ist_default | bool | Anzeige-Ordner „Allgemein" im UI. **Die brand-weite Basisebene ist keine Ordner-Zeile, sondern `folder_id = null` in `attribute_scores`** – der Default-Ordner zeigt sie nur an, er speichert sie nicht |
+| post_count, signal_count | int | Reifegrad – steuert den K-Faktor und die UI-Anzeige „Ordner lernt noch" |
+| created_at | datetime | |
+
+> **Kaltstart:** keine Mindestanzahl an Posts, keine Sperre. Ein Ordner ist ab dem Anlegen nutzbar; die statistische Unsicherheit steckt im K-Faktor (32 → 8), nicht in einer Sperre. Das ist dieselbe Regel wie in `projekt-uebersicht.md` §5, nur auf Ordner-Ebene.
+
+**`categories`**
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| brand_id | rel | |
+| name | string (location, licht, farben, kamera, voice, geraeusche, texte-hooks, handlungen) | |
+| **folder_id** | rel → folders (null = brand-weit) | **neu** – `avg_score` ist scope-abhängig, also gibt es die Zeile je Ordner |
+| avg_score | int | **Cache für Startwerte neuer Einträge** – per Function aktualisiert, nicht live berechnet |
+| attribute_count | int | |
+
+**`attributes`** – nur noch die **Definition** (Scores siehe unten)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| brand_id, category_id | rel | |
+| parent_id | rel → attributes (self) | Unter-Attribute (kaiserslautern--stadion) |
+| name, slug | string | |
+| status | enum: aktiv/archiviert | **nie löschen** |
+| tags | string[] | Volltext-Index |
+| beschreibung_md, essenz_md, details_md | string (Markdown) | die drei Textebenen |
+| prompt_bausteine, negativ_prompts | string[] | gehen direkt in P7/P8-Slots |
+
+> **Warum aufgetrennt:** Ein Attribut („badezimmer") ist einmal definiert, trägt aber **mehrere Scores** – einen brand-weit und je einen pro Ordner. „Warmes Abendlicht" kann im Ordner *Sommerkampagne* auf 6800 stehen und im Ordner *Dark Studio* gar nicht existieren. Die Textebenen bleiben bewusst am Attribut, nicht am Score: die Beschreibung ändert sich nicht mit dem Scope.
+
+**`attribute_scores`** – Score je Attribut je Ordner (neu, Herzstück)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| attribute_id | rel → attributes | |
+| **folder_id** | rel → folders (**null = brand-weite Basisebene**) | Unique-Constraint auf (attribute_id, folder_id) |
+| brand_id, category_id | rel | denormalisiert. **Index: (brand, folder, category, score ↓)** – das ist die Top-N-Abfrage, die P4 bei jeder Generierung fährt |
+| score | int (0–10.000) | |
+| k_factor | int | 32 neu → 8 etabliert; bleibt hoch, solange `folders.signal_count` niedrig ist |
+| start_value, start_quelle | int, enum: kategorie_avg / geerbt / feed_import | dokumentiert, woher der Startwert kam – ohne das ist später nicht nachvollziehbar, warum ein Score dort steht |
+| used_count, wins, losses | int | |
+| last_used_at | datetime | |
+
+**`score_events`** – das Log (append-only, nie ändern)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| attribute_id | rel | Index: (attribute, created_at) |
+| **folder_id** | rel → folders (null = brand-weit) | **neu und zwingend** – ohne den Scope ist nicht nachvollziehbar, in welcher Wissensinsel ein Punkt vergeben wurde |
+| video_id, **post_id**, opponent_attribute_id | rel | |
+| event_type | enum: vote / vote_favorit_bestaetigt / performance / gezielte_frage / llm_vergleich / **feed_import** / **post_reichweite** | die zwei neuen Typen kommen aus dem Bild-Modus |
+| delta, new_score, weight | int, int, float | weight: ×0,3 / ×1 / ×2 · `feed_import` und `post_reichweite` laufen mit **×0,3** |
+| kommentar | string | z. B. P12-Erkenntnis („Stadion war der Unterschied") |
+
+### Assets / „Modelle" (Release-Prinzip)
+
+**`assets`** – im UI **„Modelle"**
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| brand_id | rel | |
+| typ | enum: gesicht/produkt/**kulisse**/logo/sonstiges | **`kulisse` ist neu** – die Umgebung ist ein eigenständiges, einzeln austauschbares Modell |
+| name | string | „kleine Kerze" |
+| **nische** | enum wie `brands.nische` | Feed-Filter |
+| **typ_tags** | string[] (Enum-Zwang) | fahrzeug, getraenk, tube, person_weiblich, innenraum, … – **gegen diese Liste prüft die Slot-Kompatibilität beim Kopieren**. Feste Liste + Code-Validator, keine freie KI-Vergabe |
+| **feed_score, feed_score_updated_at** | float, datetime | Modelle werden getrennt von Posts gerankt (siehe `post_metrics`) |
+| **ist_teilbar** | bool (default **false**) | Modelle werden grundsätzlich **nicht** geteilt. Das Feld existiert nur, um die Regel explizit und prüfbar zu machen |
+| released_version_id | rel → asset_versions (**nur diese wird in Videos und Bildern verwendet**) | |
+
+> **Regel:** Ein Kopierer bringt immer eigene Modelle mit. Fremde Modelle erscheinen nur als **Beschriftung** im Kopier-Screen („Modell: kleine Kerze"), damit klar ist, was das Rezept braucht – nie als nutzbares Asset. Begründung in `konzept-bilder-feed.md` §3 (Marken-/Designrecht bei Produkten, Konsistenzentwertung bei Personen).
+
+**`asset_versions`** – Versionskette
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| asset_id, version_no | rel, int | |
+| status | enum: entwurf/freigegeben/archiviert | |
+| beschreibung_md, merkmale | string, string[] | |
+| change_reason | string | „Haare dunkler, natürlicher" |
+| won_against_version_id | rel | Vorher/Nachher-Vote |
+| reference_file_ids | string[] | → Storage-Bucket |
+| einwilligung_file_id | string | dokumentierte Einwilligung bei echten Gesichtern |
+
+### Produktion
+
+**`scenes`**
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| brand_id | rel | |
+| **folder_id** | rel → folders (null = brand-weit) | **neu** – der Scope wird **vor** der Generierung gewählt und bestimmt, welches Wissen P4 zieht |
+| user_prompt | string | Original, unverändert aufheben |
+| selected_context | json | was P4 injiziert hat (Attribute + Scores zum Zeitpunkt!) |
+| script_md, script_final_md | string | Original vs. vom Nutzer bearbeitet → Diff = P6-Signal |
+| status | enum: entwurf/script/generiert/voting/fertig | **Realtime-Kanal fürs UI** |
+| video_count | int | |
+
+**`videos`**
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| scene_id, brand_id | rel | |
+| ki_model | enum: seedance/veo/sora/wan | |
+| prompt_sent | string 🔒 | exakt was ans KI-Modell ging (Dev-Modus „Prompt-Einblick") |
+| storage_file_id | string | → Bucket generated-videos |
+| tags | json | P9-Analyse |
+| attribute_ids | rel many→many | für Attribution |
+| asset_version_ids | string[] | welche Versionen genau (v3? v4?) |
+| is_system_favorite, vote_result | bool, enum: gewonnen/verloren/– | |
+| published, platforms, published_at | bool, string[], datetime | |
+
+**`video_metrics`** – Zeitreihe (Cron-Function, Ads-APIs)
+| Spalte | Typ |
+|---|---|
+| video_id, fetched_at | rel, datetime |
+| ctr, thumbstop, roas, follower_gained, spend | float |
+
+**`votes`**
+| Spalte | Typ |
+|---|---|
+| scene_id, winner_video_id | rel |
+| favorit_bestaetigt | bool (→ Gewichtung ×0,3) |
+| created_at | datetime |
+
+**`questions`** – gezielte Fragen (P13)
+| Spalte | Typ |
+|---|---|
+| brand_id, scene_id | rel |
+| frage, attribute_a_id, attribute_b_id | string, rel, rel |
+| antwort | enum: a/b/egal/offen |
+
+### Bild-Modus: Posts, Feed & Ordner
+
+**`posts`** – das Slot-Rezept (neu)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| brand_id | rel | Ersteller |
+| **format** | enum: 1_1 / 4_5 / 9_16 | gilt für die ganze Kette. Beim Kopieren **deterministisch** übernommen – kein LLM |
+| **nische** | enum wie `brands.nische` | Feed-Filter |
+| kulisse_asset_id, person_asset_id, produkt_asset_id | rel → assets | die Modell-Slots |
+| asset_version_ids | string[] | welche Versionen genau – wie bei `videos` |
+| attribute_ids | rel many→many → attributes | Licht / Kamera / Farbe als Slots |
+| werbetext | string | Inhalt des Text-Overlay-Bildes |
+| prompt_sent | string 🔒 | exakt was ans Bildmodell ging – **nur internes Team**, nie im Kopier-Screen |
+| **slot_summary** | json | die vereinfachte Chip-Darstellung für den Kopier-Screen (Output von P19). **Das ist das Einzige, was ein fremder Nutzer sieht** – eine Abstraktion, keine Offenlegung |
+| **copied_from_post_id** | rel → posts (self) | Herkunftskette – erlaubt später „dieses Rezept wurde 400× kopiert" |
+| **sichtbarkeit** | enum: privat / oeffentlich (default **privat**) | Veröffentlichen ist ein aktiver Schritt |
+| published_at | datetime | |
+| social_permalink, social_plattform | string, enum: instagram/tiktok/… | Grundlage für den Reichweiten-Abgleich |
+| **feed_score, feed_score_updated_at** | float, datetime | Cache, per Cron berechnet – nie live |
+| ki_kennzeichnung | bool | EU AI Act – im Feed sichtbar, nicht nur beim Export |
+
+**`post_images`** – die Bilderkette
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| post_id, position | rel, int | Reihenfolge im Karussell |
+| typ | enum: motiv / **text_overlay** | Das Text-Overlay ist ein **eigenes Bild**, keine Ebene auf dem Motiv – so lässt sich der Text tauschen, ohne die Motive neu zu generieren |
+| storage_file_id | string | → Bucket `generated-images` |
+| winkel, position_beschreibung | string | über die Kette variiert **nur** Position/Winkel; Modelle, Kulisse, Licht, Farbe und Text bleiben konstant |
+| tags | json | P22-Analyse (Bild-Tagger) |
+
+**`post_folders`** – Zuordnung (m:n, neu)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| post_id, folder_id | rel, rel | Unique auf (post_id, folder_id) |
+| **ist_fremd** | bool | Post stammt nicht vom Ordner-Besitzer. Ordner nehmen **eigene und fremde** Posts auf – Wissen entsteht durch Sammeln, nicht erst durch Ausgeben |
+| quelle | enum: eigen / feed_gespeichert / kopiert | |
+| zugeordnet_von | enum: nutzer / p20_vorschlag | P20 schlägt vor, der Nutzer bestätigt |
+| created_at | datetime | |
+
+**`post_metrics`** – Feed-Signale (Zeitreihe, append-only)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| post_id, fetched_at | rel, datetime | |
+| views, likes, **kopien** | int | In-App-Signale |
+| social_reach, social_engagement | int | von verbundenen Accounts |
+| ist_verifiziert | bool | nur verifizierte Konten zählen voll – Manipulationsschutz |
+
+> **Gewichtung Feed-Score:** Views ×0,1 · Likes ×0,5 · **Kopien ×1** · Social-Reichweite ×2. Eine Kopie wiegt mehr als ein Like – ein Like ist eine Meinung, eine Kopie eine Handlung mit Aufwand.
+>
+> **Der Feed-Score ist kein Elo.** Elo braucht Duelle; hier werden Zähler aufsummiert. Deshalb eigene Tabelle, eigener Name, eigene Function. Details und Begründung: `konzept-bilder-feed.md` §8.
+
+---
+
+### Betrieb
+
+**`jobs`** – jede KI-Aktion als Zeile (Warteschlange + Kostenkontrolle)
+| Spalte | Typ | Hinweis |
+|---|---|---|
+| brand_id, typ | rel, enum: bild_gen/video_gen/tagging/vergleich/script/**slot_analyse**/**ordner_vorschlag**/**werbetext** | die drei neuen Typen kommen aus dem Bild-Modus (P19, P20, P21) |
+| prompt_template_key, prompt_template_version | string, int | **welcher Prompt in welcher Version lief** – ohne das ist kein Prompt-Debugging möglich |
+| status | enum: wartend/läuft/fertig/fehler | |
+| cost_usd, tokens | float, int | speist die Beispielrechnung mit echten Zahlen |
+| error, refs | string, json | |
+
+**`usage_records`** – für Stripe (metered billing: Preis pro Video)
+| Spalte | Typ |
+|---|---|
+| brand_id, periode, videos_generiert, kosten_usd | rel, string, int, float |
+
+---
+
+## 3. Storage-Buckets (Backend: Hetzner Object Storage via S3-Adapter)
+
+| Bucket | Inhalt | Rechte |
+|---|---|---|
+| `uploads` | Onboarding: Logo, Produktbilder, Top-Ads; Referenzen beim Verbessern | Team der Brand |
+| `asset-references` | generierte Referenzbilder der Asset-Versionen | Team der Brand |
+| `generated-videos` | alle generierten Videos | Team der Brand |
+| **`generated-images`** | alle generierten Bilder (Motive + Text-Overlays) | Team der Brand; **öffentlich lesbar, sobald `posts.sichtbarkeit = oeffentlich`** |
+| `consents` | Einwilligungs-Dokumente (Gesichter) | Team + intern |
+
+---
+
+## 4. Functions (deterministisch – die ⚙️-Punkte aus dem Prompt-Inventar)
+
+| Function | Trigger | Macht |
+|---|---|---|
+| `elo-update` | Event: votes.create / video_metrics.create | Elo-Mathe, K-Faktor, Gewichtung, schreibt score_events – **jetzt scope-bewusst: schreibt in `attribute_scores` der passenden `folder_id`** |
+| `favorit-berechnen` | Event: alle Videos einer Szene getaggt | Score-Summe → is_system_favorite |
+| `ads-metriken-holen` | Cron täglich | Meta/TikTok-API → video_metrics |
+| `kategorie-durchschnitt` | Cron täglich | avg_score-Cache für Startwerte – **je Ordner** |
+| `archivierung` | Cron wöchentlich | Score unter Schwelle + inaktiv → Status archiviert |
+| `job-dispatcher` | Event: jobs.create | ruft OpenRouter, schreibt Ergebnis + Kosten zurück |
+| **`ordner-initialisieren`** | Event: folders.create | Bei `startwert_modus = erben` die brand-weiten Scores nach `attribute_scores` kopieren; bei `aus_posts` nur die Attribute der zugeordneten Posts anlegen, Startwert = Kategorie-Ø im Ordner. Setzt `start_quelle` |
+| **`feed-score-berechnen`** | Cron stündlich | Gewichtete Summe aus `post_metrics` + **exponentieller Zeit-Decay** (Halbwertszeit-Parameter, Startwert 30 Tage) → `posts.feed_score` und aggregiert → `assets.feed_score`. **Rein deterministisch, kein LLM** |
+| **`feed-import`** | Event: post kopiert | Legt die Slots des Originals als Attribute in der KB des Kopierers an (Scope = gewählter Ordner), `start_quelle = feed_import`, schreibt `score_events` |
+| **`social-reichweite-holen`** | Cron täglich | Instagram/TikTok-API → `post_metrics.social_reach`; löst Rückfluss mit ×0,3 in die KB aus |
+
+---
+
+## 5. Rechte-Modell
+
+- **Brand-Team:** sieht nur eigene Zeilen (Appwrite Row-Level-Permissions pro Team) – Multi-Tenant ohne Extra-Code.
+- **Internes Team (Dev-Modus):** exklusiver Zugriff auf `rules`, `prompt_templates`, `jobs.prompt_sent`, **`posts.prompt_sent`** – das App-Geheimnis liegt in den Rechten, nicht nur im UI.
+- **append-only:** `score_events`, `video_metrics`, **`post_metrics`**, `jobs` werden nie geändert oder gelöscht – das ist die Log-Anforderung aus dem Konzept.
+
+**Neu mit dem Feed – die einzige öffentlich lesbare Ebene:**
+
+| Öffentlich lesbar | Bleibt privat |
+|---|---|
+| `posts` bei `sichtbarkeit = oeffentlich`: Bilder, `slot_summary`, `werbetext`, `nische`, `feed_score` | `posts.prompt_sent` 🔒 · `attribute_scores` · `folders` (immer privat) · `rules` · alle Modelle als **Assets** |
+| `assets`: nur Name, Typ und Typ-Tags als **Beschriftung** im Kopier-Screen | die Asset-Version selbst, Referenzbilder, `einwilligung_file_id` |
+
+> Das ist die kritische Grenze des ganzen Features: Der Kopier-Screen zeigt **`slot_summary`**, nie `prompt_sent`. Eine Abstraktion, keine Offenlegung – sonst wandert die Knowledge Base fremder Brands nach außen.
+
+**Zusätzlich nötig, weil der Feed öffentlich ist:** Rate-Limits auf `post_metrics`-Signale pro Konto und eine Melde-/Moderationsfunktion (DSA). Beim geschlossenen B2B-Produkt gab es beides nicht.