wiki/z-archive/concepts/Multi-Mandate-Umsetzungsplan.md

Umsetzungsplan: Multi-Mandate Onboarding, Store und Unified Data Layer

Grundlage: Multi-Mandate-Onboarding-und-Store-Konzept.md v4

Struktur: Der Plan folgt den drei Phasen aus dem Konzept. Jede Phase ist in konkrete Arbeitspakete (AP) zerlegt. Jedes AP enthält: betroffene Dateien, Abhängigkeiten und Akzeptanzkriterien.

Legende: [BE] = Backend, [FE] = Frontend, [DB] = Datenbank/Migration, [OPS] = Betrieb/Infrastruktur

---

Phase 1 — Mandate-per-Registration und Own-Instance-Pattern

Ziel: Saubere Mandanten-Grenze, eigene Instanzen pro Mandant, Root nur noch technisch. FeatureInstance = Datengrenze.

---

AP 1.1 — [DB] Datenmodell: mandateType Enum auf Mandate

Beschreibung: Neues Feld mandateType auf dem Mandate-Modell. Enum mit Werten system, personal, company. Mutabel und rein informativ — keine Geschäftslogik daran gebunden.

Dateien:

• gateway/modules/datamodels/datamodelUam.py — Enum MandateType hinzufügen, Feld mandateType auf Mandate

Schritte:

1. Enum MandateType definieren (system, personal, company)
2. Feld mandateType: MandateType auf Mandate mit Default company
3. Bestehende Mandanten erhalten via DB-Update Default company
4. Root-Mandant explizit auf system setzen (im Bootstrap)

Akzeptanz:

• Alle bestehenden Mandanten haben mandateType=company
• Root-Mandant hat mandateType=system
• Keine Geschäftslogik prüft mandateType für Feature-Gates oder Kapazität

Abhängigkeiten: Keine

---

AP 1.2 — [BE] Subscription-Timing: PENDING → ACTIVE

Beschreibung: MandateSubscription wird bei Registrierung mit Status PENDING erstellt. Aktivierung auf ACTIVE erfolgt bei erstem Login. Trial-Periode beginnt erst ab Aktivierung.

Dateien:

• gateway/modules/datamodels/datamodelSubscription.py — Status PENDING in die State Machine aufnehmen
• gateway/modules/routes/routeSecurityLocal.py — Subscription mit PENDING erstellen
• gateway/modules/routes/routeSecurityGoogle.py — Subscription mit PENDING erstellen
• Login-Logik (Local + OAuth) — bei erstem Login PENDING → ACTIVE Transition auslösen

Schritte:

1. PENDING als neuen Status in SubscriptionStatus Enum hinzufügen
2. State-Machine-Transition PENDING → ACTIVE definieren
3. Bei Registrierung: MandateSubscription mit status=PENDING, trialStartDate=null
4. Bei erstem Login: Status auf ACTIVE setzen, trialStartDate=now()
5. Bestehende Subscriptions bleiben unverändert (ACTIVE)

Akzeptanz:

• Neue Registrierungen erhalten PENDING-Subscription
• Erster Login setzt auf ACTIVE und startet Trial
• Kein User verliert Trial-Tage durch Magic-Link-Delay

Abhängigkeiten: AP 1.1

---

AP 1.3 — [BE] Interne Provisionierungsroutine _provisionMandateForUser

Beschreibung: Zentrale atomare Funktion, die nach createUser ein komplettes Mandate mit Subscription und Feature-Instanzen erstellt. Umgeht RBAC (Root-privilegiert), da der User noch keine Rechte hat.

Dateien:

• gateway/modules/interfaces/interfaceDbApp.py — neue Funktion _provisionMandateForUser()

Schritte:

1. Funktion _provisionMandateForUser(userId, mandateType, mandateName, planKey) erstellen
2. Atomare Transaktion: a. createMandate (mit mandateType, ohne RBAC-Check) b. System-Rollen kopieren (_copySystemRolesToMandate) c. createUserMandate mit Admin-Rolle d. MandateSubscription erstellen (mit PENDING) e. Für Features mit autoCreateInstance: createFeatureInstance + FeatureAccess mit Admin-Instanzrolle
3. Rollback bei Fehler in einem Schritt
4. Logging aller Aktionen

Akzeptanz:

• Ein Aufruf erstellt alles atomar (Mandate + UserMandate + Subscription + Instanzen)
• Bei Fehler: kein Halbzustand (keine verwaisten Mandate)
• RBAC wird nicht geprüft (interne Routine)

Abhängigkeiten: AP 1.1, AP 1.2

---

AP 1.4 — [BE] Registrierung Local: Mandate-Provisionierung

Beschreibung: POST /api/local/register erweitern um registrationType und companyName. Nach createUser wird _provisionMandateForUser aufgerufen.

Dateien:

• gateway/modules/routes/routeSecurityLocal.py — Register-Endpoint erweitern

Schritte:

1. Request-Body erweitern: registrationType (personal/company), companyName (optional)
2. Validierung: company erfordert companyName
3. Nach createUser: _provisionMandateForUser aufrufen mit:
   • personal → mandateType=personal, planKey=TRIAL_7D, mandateName=username
   • company → mandateType=company, planKey=STANDARD_MONTHLY, mandateName=companyName
4. Response erweitern um mandateId

Akzeptanz:

• Registrierung erstellt User + Mandate + Subscription + Instanzen in einem Flow
• Personal → Trial, Company → Standard
• Fehler bei Provisionierung → User wird nicht erstellt (oder cleanup)

Abhängigkeiten: AP 1.3

---

AP 1.5 — [BE] Registrierung OAuth: Onboarding-Wizard

Beschreibung: Bei OAuth-Registrierung (Google, MSAL) gibt es kein Formular. Stattdessen wird beim allerersten Login erkannt, dass kein Mandate existiert, und ein Onboarding-Wizard-Flag gesetzt.

Dateien:

• gateway/modules/routes/routeSecurityGoogle.py — Erkennung „erster Login ohne Mandate"
• Analoge Logik für MSAL-Route

Schritte:

1. Nach OAuth-Login prüfen: Hat der User mindestens ein Mandate?
2. Falls nein: Response-Flag requiresOnboarding=true setzen
3. Frontend zeigt Onboarding-Wizard (siehe AP 1.12)
4. Wizard-Submit ruft neuen Endpoint auf: POST /api/onboarding/provision mit mandateType + companyName
5. Endpoint nutzt _provisionMandateForUser

Akzeptanz:

• OAuth-User ohne Mandate wird erkannt
• Wizard erscheint nur beim allerersten Login
• Nach Wizard-Abschluss hat der User ein vollständiges Mandate

Abhängigkeiten: AP 1.3

---

AP 1.6 — [BE] Feature Store: Refactoring auf Own Instance Pattern

Beschreibung: Store erstellt eigene FeatureInstance im Ziel-Mandanten statt Shared Instance im Root. Explizites mandateId in allen Store-APIs. Mehrere Instanzen desselben Features sind erlaubt.

Dateien:

• gateway/modules/routes/routeStore.py — komplettes Refactoring

Schritte:

1. POST /api/store/activate:
   • Body: featureCode + mandateId (explizit, nie implizit)
   • Prüfungen: User ist Admin im Ziel-Mandat, Subscription-Kapazität (maxFeatureInstances)
   • Neue FeatureInstance im Ziel-Mandat erstellen (auch wenn bereits eine gleiche existiert)
   • FeatureAccess + Admin-Instanzrolle für den User
   • Stripe-Quantity sync
2. POST /api/store/deactivate:
   • Body: featureCode + mandateId + instanceId
   • Eigenen FeatureAccess entfernen
   • Orphan-Check: Keine FeatureAccess-Records mehr → Instanz löschen + Stripe-Quantity sync
3. GET /api/store/features:
   • Zeigt verfügbare Features mit Status pro Mandat des Users
   • Für jeden Mandanten des Users: Anzahl aktiver Instanzen
4. Alte Shared-Instance-Logik entfernen

Akzeptanz:

• Aktivierung erstellt immer eine neue Instanz im expliziten Mandat
• Mehrere Instanzen desselben Features pro Mandat möglich
• Orphan Control: letzte Deaktivierung löscht Instanz
• Kein mandateId-Guessing, kein implizites Primary-Mandate

Abhängigkeiten: AP 1.1, AP 1.3

---

AP 1.7 — [BE] Store: Auto-Mandate für User ohne Admin-Mandate

Beschreibung: User, die nur als Mitglieder (nicht Admin) in fremden Mandanten sind, können über den Store ein eigenes Mandate erstellen lassen.

Dateien:

• gateway/modules/routes/routeStore.py — Activate-Endpoint erweitern

Schritte:

1. Bei activate: Prüfen ob User mindestens ein Mandate hat, in dem er Admin ist
2. Falls kein Admin-Mandate vorhanden und mandateId nicht angegeben:
   • _provisionMandateForUser aufrufen (personal, TRIAL_7D)
   • Feature-Instanz im neuen Mandate erstellen
   • Response enthält neues mandateId
3. Falls mandateId angegeben aber User kein Admin dort: Fehler (403)

Akzeptanz:

• User ohne Admin-Mandate kann Feature im Store aktivieren → Auto-Mandate
• User wird automatisch Admin des neuen Mandanten
• Bestehende Admins nutzen weiterhin den normalen Flow

Abhängigkeiten: AP 1.6, AP 1.3

---

AP 1.8 — [BE] Subscription: maxDataVolumeMB Parameter

Beschreibung: Neuer Parameter maxDataVolumeMB in der Subscription für Kapazitätsplanung (Soft-Limit).

Dateien:

• gateway/modules/datamodels/datamodelSubscription.py — BUILTIN_PLANS erweitern
• gateway/modules/interfaces/interfaceDbApp.py — Volumen-Berechnung

Schritte:

1. maxDataVolumeMB als Parameter in SubscriptionPlan hinzufügen
2. Default-Werte pro Plan definieren (z. B. TRIAL_7D: 500 MB, STANDARD: 10 GB)
3. API-Endpoint für aktuelle Nutzung: GET /api/mandate/{id}/data-usage
4. Berechnung: Summe aller Dateigrössen im Mandate

Akzeptanz:

• Subscription-Pläne enthalten maxDataVolumeMB
• Aktuelle Nutzung ist abrufbar
• Kein Schreib-Block bei Überschreitung (Soft-Limit)

Abhängigkeiten: AP 1.2

---

AP 1.9 — [DB] Migrations-Script: Root-Mandant bereinigen

Beschreibung: Separates Script, das alle Endkunden-Daten aus dem Root-Mandate in eigene Mandate migriert. Einmalig im Bootstrap aufgerufen.

Dateien:

• gateway/scripts/script_migrate_root_users.py (oder gateway/modules/migration/migrateRootUsers.py) — NEU
• gateway/modules/interfaces/interfaceBootstrap.py — Aufruf einhängen

Schritte:

1. Script erstellen mit Dry-Run-Modus
2. Schritt 1 — Feature-Daten migrieren:
   • Für jeden User mit FeatureAccess auf Root-Instanzen:
     • Hat User eigenes Mandate? → Ziel-Mandate setzen
     • Kein Mandate? → _provisionMandateForUser (personal)
     • Pro FeatureAccess: Neue Instanz im Ziel-Mandat erstellen, Daten umschreiben (featureInstanceId), FeatureAccess transferieren
3. Schritt 2 — Root bereinigen:
   • Alle Feature-Instanzen im Root entfernen
   • UserMandate zum Root entfernen (ausser isSysAdmin=true)
4. Root-Mandate: mandateType=system setzen
5. Flag in DB setzen: Migration abgeschlossen (verhindert Doppelausführung)
6. Im Bootstrap einhängen nach initRootMandateFeatures

Akzeptanz:

• Dry-Run zeigt alle Aktionen ohne Änderungen
• Alle User haben eigene Mandate mit migrierten Daten
• Root enthält nur sysadmin-User, keine Feature-Instanzen
• Script läuft nur einmal (Flag-Check)

Abhängigkeiten: AP 1.1, AP 1.3

---

AP 1.10 — [BE] Mandanten-Löschung: Kaskade

Beschreibung: Vollständige Lösch-Kaskade für Mandanten mit Soft-Delete und Schutzmechanismen.

Dateien:

• gateway/modules/interfaces/interfaceDbApp.py — neue Funktion _deleteMandate()
• gateway/modules/shared/gdprDeletion.py — erweitern
• API-Endpoint: DELETE /api/mandates/{mandateId}

Schritte:

1. Schutzmechanismen:
   • isSystem=true → Löschung verweigern
   • Nur Mandanten-Admin oder sysadmin darf löschen
   • Bestätigung via confirmMandateName im Request-Body
2. Soft-Delete:
   • deletedAt Timestamp auf Mandate setzen
   • Alle Zugriffe sofort sperren (RBAC-Check auf deletedAt)
   • 30-Tage Retention
3. Kaskade (bei endgültiger Löschung):
   • FeatureInstances → FeatureAccess → Instanz-Daten (Chats, Dokumente, Extraktionen)
   • DataNeutralizerAttributes (Mapping-Tabelle)
   • RAG-Index-Einträge mit mandateId
   • UserMandate-Zuordnungen (User bleiben bestehen)
   • MandateSubscription → Stripe-Subscription kündigen
   • Mandate-Konfigurationen (Rollen, Settings)
   • Mandate-Record
4. Batch-Job für endgültige Löschung nach Retention

Akzeptanz:

• Root-Mandate nicht löschbar
• Soft-Delete mit sofortiger Zugriffssperre
• Vollständige Kaskade ohne verwaiste Daten
• Stripe-Subscription wird gekündigt

Abhängigkeiten: AP 1.1

---

AP 1.11 — [FE] Register-Seite: Zwei Flows

Beschreibung: Register-Formular unterstützt type=personal und type=company via Query-Parameter.

Dateien:

• frontend_nyla/src/pages/Register.tsx — type Query-Parameter
• frontend_nyla/src/api/authApi.ts — registerApi erweitern

Schritte:

1. Query-Parameter type auslesen (personal / company)
2. Bei company: Zusatzfeld „Firmenname" anzeigen
3. API-Call erweitern: registrationType + companyName im Body
4. Erfolgsseite anpassen: „Dein Mandant wurde erstellt"
5. Redirect nach Login auf Dashboard (nicht Store, da Instanzen via autoCreate existieren)

Akzeptanz:

• /register?type=personal zeigt Personal-Flow
• /register?type=company zeigt Company-Flow mit Firmenname
• API-Body enthält neue Felder

Abhängigkeiten: AP 1.4

---

AP 1.12 — [FE] Login-Seite: Zwei CTAs + OAuth Onboarding-Wizard

Beschreibung: Login/Landing-Seite mit zwei prominenten Call-to-Actions und Onboarding-Wizard für OAuth-Erstregistrierungen.

Dateien:

• frontend_nyla/src/pages/Login.tsx — CTAs hinzufügen
• frontend_nyla/src/components/OnboardingWizard.tsx — NEU

Schritte:

1. Login-Seite: Zwei CTAs
   • „Kostenlos testen" → /register?type=personal
   • „Für Unternehmen" → /register?type=company
2. Onboarding-Wizard Komponente:
   • Schritt 1: „Wie möchtest du PowerON nutzen?" (Personal / Unternehmen)
   • Schritt 2: Bei Company → Firmenname eingeben
   • Submit → POST /api/onboarding/provision
3. Nach OAuth-Login: Prüfen ob requiresOnboarding=true in Response → Wizard anzeigen

Akzeptanz:

• Zwei CTAs sichtbar auf Login-Seite
• OAuth-User ohne Mandate sieht Wizard
• Wizard erstellt Mandate und leitet zum Dashboard

Abhängigkeiten: AP 1.5

---

AP 1.13 — [FE] Store-Seite: Mandanten-Auswahl

Beschreibung: Store zeigt explizite Mandanten-Auswahl bei Aktivierung. Alle User sehen den Store.

Dateien:

• frontend_nyla/src/pages/Store.tsx — Refactoring

Schritte:

1. Store für alle User zugänglich machen (kein Admin-Gate)
2. Pro Feature: Mandanten-Auswahl anzeigen (Dropdown bei Multi-Mandate, auto-select bei Solo)
3. „Aktivieren für [Mandantenname]" statt nur „Aktivieren"
4. Bei User ohne Admin-Mandate: „Eigenen Mandanten erstellen und Feature aktivieren" als Option
5. Deaktivierung: Pro Instanz mit Orphan-Warnung („Du bist der letzte User — Instanz wird gelöscht")
6. Anzeige aktiver Instanzen pro Mandate mit Instanz-Anzahl

Akzeptanz:

• Mandanten-Auswahl bei jeder Aktivierung
• Auto-Mandate-Option für User ohne eigenes Mandate
• Orphan-Warnung bei letzter Deaktivierung

Abhängigkeiten: AP 1.6, AP 1.7

---

AP 1.14 — [FE] Subscription-Datenvolumen: UI-Hinweis

Beschreibung: Anzeige der Datenvolumen-Nutzung im Billing-Bereich.

Dateien:

• frontend_nyla/src/pages/billing/BillingDataView.tsx — Datenvolumen-Anzeige

Schritte:

1. API-Aufruf: GET /api/mandate/{id}/data-usage
2. Fortschrittsbalken: genutzt / maximal (z. B. „3.2 GB / 10 GB")
3. Warnung bei > 80%: „Du näherst dich dem Datenvolumen-Limit"
4. Upgrade-Link bei hoher Nutzung

Akzeptanz:

• Datenvolumen sichtbar im Billing-Bereich
• Warnung bei > 80%
• Kein Block, nur Hinweis

Abhängigkeiten: AP 1.8

---

AP 1.15 — [BE] Bootstrap: Root-Mandant mandateType=system setzen

Beschreibung: Im Bootstrap den Root-Mandanten explizit auf mandateType=system setzen.

Dateien:

• gateway/modules/interfaces/interfaceBootstrap.py — initRootMandate() erweitern

Schritte:

1. In initRootMandate(): mandateType=system setzen
2. initRootMandateFeatures() bleibt für System-Instanzen (aber keine Endkunden-Instanzen mehr nach Migration)

Akzeptanz:

• Root-Mandant hat mandateType=system nach Bootstrap
• Keine Endkunden-Feature-Instanzen im Root (nach Migration)

Abhängigkeiten: AP 1.1, AP 1.9

---

Phase 2 — UDB + Shared Data Scope

Ziel: UDB als plattformweite Komponente, mandantenweiter Datenzugriff via Scopes. FeatureInstance = Datengrenze + mandantenweiter Zugriff.

Voraussetzung: Phase 1 vollständig abgeschlossen.

---

AP 2.1 — [BE] Datenmodell: Scope- und Neutralisierungs-Felder auf DataSources

Beschreibung: Bestehende Datenquellen-Modelle um scope und neutralize Felder erweitern. RAG-Index um Scope-Metadaten erweitern.

Dateien:

• Bestehende Datenmodelle (Dokumente, Extraktionen, Konnektoren) — scope + neutralize Felder
• RAG-Index-Konfiguration — Filterbare Metadaten

Schritte:

1. Enum DataScope definieren: personal, featureInstance, mandate, global
2. Felder hinzufügen: scope: DataScope (default personal), neutralize: bool (default false), neutralizationStatus: str
3. Bestehende Daten: Default scope=featureInstance (bestehendes Verhalten)
4. RAG-Index-Metadaten erweitern: mandateId, scope, featureInstanceId, userId, isNeutralized
5. Bestehende RAG-Einträge: Backfill mit Scope-Metadaten

Akzeptanz:

• Alle DataSources haben scope und neutralize
• RAG-Index filtert korrekt nach Scope
• Bestehende Daten haben konsistente Defaults

Abhängigkeiten: Phase 1 abgeschlossen

---

AP 2.2 — [BE] RAG-Query: Scope-basierte Filterung

Beschreibung: RAG-Queries filtern Ergebnisse basierend auf dem effektiven Scope des anfragenden Users.

Dateien:

• RAG-Query-Logik — Scope-Filter aufbauen

Schritte:

1. Scope-Kontext aufbauen pro Query:

   personal(userId) ∪ featureInstance(instanceId) ∪ mandate(mandateId) ∪ global()
   

2. Union-Query über vier Scopes implementieren
3. scope=global nur sysadmin-setzbar (RBAC-Check beim Tagging)
4. Performance-Tests mit grossen Datenmengen

Akzeptanz:

• User sieht nur Daten seiner Scopes
• Global-Scope RBAC-geschützt
• Query-Performance akzeptabel (< 500ms)

Abhängigkeiten: AP 2.1

---

AP 2.3 — [BE] Datenquellen-Tagging API

Beschreibung: API-Endpoints für Scope- und Neutralisierungs-Tagging auf Datenquellen.

Dateien:

• Neue oder erweiterte Routes — Tagging-Endpoints

Schritte:

1. PATCH /api/datasources/{id}/scope — Scope ändern (personal → featureInstance → mandate; global nur sysadmin)
2. PATCH /api/datasources/{id}/neutralize — Neutralisierungs-Flag togglen
3. Bei Scope-Änderung: RAG-Index re-indizieren (async)
4. Bei Neutralisierungs-Änderung: Re-Neutralisierung oder De-Neutralisierung triggern (async)
5. Defaults bei Upload: scope=personal, neutralize=false

Akzeptanz:

• Scope-Änderung löst Re-Indizierung aus
• Neutralisierungs-Änderung löst Re-Verarbeitung aus
• RBAC: global nur für sysadmin

Abhängigkeiten: AP 2.1, AP 2.2

---

AP 2.4 — [FE] UDB: Extraktion aus Workspace

Beschreibung: Die bestehende Sidebar im AI Workspace (Chats, Files, Sources) wird als wiederverwendbare Plattformkomponente extrahiert.

Dateien:

• frontend_nyla/src/pages/workspace/ — Sidebar-Logik identifizieren und extrahieren
• frontend_nyla/src/components/UnifiedDataBar/ — NEU: UDB-Komponente

Schritte:

1. Bestehende Sidebar-Komponenten im Workspace identifizieren (Chats-Liste, Files-Liste, Sources-Liste)
2. Gemeinsame UDB-Komponente erstellen mit drei Tabs: Chats, Files, Sources
3. Props: mandateId, featureInstanceId, userId für Kontext
4. Workspace refactoren: UDB einbinden statt eigener Sidebar
5. Verifizieren: Workspace funktioniert identisch mit UDB-Komponente

Akzeptanz:

• UDB ist eine eigenständige Komponente in src/components/
• Workspace nutzt UDB und funktioniert wie zuvor
• Keine Duplizierung von Sidebar-Logik

Abhängigkeiten: Phase 1 abgeschlossen

---

AP 2.5 — [FE] UDB: Chats-Tab mit Baumstruktur

Beschreibung: Chat-Verläufe als hierarchischer Baum, gruppiert nach Feature-Instanzen mit Suchfunktion und Flat Mode.

Dateien:

• frontend_nyla/src/components/UnifiedDataBar/ChatsTab.tsx — NEU

Schritte:

1. API: Chats über alle Feature-Instanzen des Users laden (gruppiert)
2. Baumstruktur: Feature-Instanzen als Top-Level-Knoten, Chats darunter
3. Feature-spezifische Substrukturen (z. B. CommCoach → Coaching-Modul → Sessions)
4. Aktuelle Feature-Instanz: hervorgehoben und expandiert
5. Klick auf Chat: Navigation in den Chat (ggf. Feature-Kontext wechseln)
6. Suchfunktion: Volltextsuche über Chat-Titel, filtert Baum auf Treffer
7. Flat Mode: Toggle im Tab-Header, chronologische Liste sortiert nach letzter Aktivität

Akzeptanz:

• Alle Chats über alle Feature-Instanzen sichtbar in einem Baum
• Suche filtert korrekt
• Flat Mode zeigt chronologische Liste
• Klick navigiert zum Chat

Abhängigkeiten: AP 2.4

---

AP 2.6 — [FE] UDB: Files-Tab mit Scope- und Neutralisierungs-Symbolen

Beschreibung: Dateien mit Inline-Scope-Symbolen und Neutralisierungs-Icons.

Dateien:

• frontend_nyla/src/components/UnifiedDataBar/FilesTab.tsx — NEU

Schritte:

1. Dateien pro Mandat laden (alle Scopes, die der User sehen darf)
2. Pro Datei: Scope-Symbol (👤 personal, 👥 instanz, 🏢 mandant) + Neutralisierungs-Symbol (🔒)
3. Klick auf Scope-Symbol: Zyklisch wechseln oder Popover
4. Klick auf Neutralisierungs-Symbol: Toggle on/off
5. Default bei Upload: personal + kein 🔒
6. Legende am Tab-Footer

Akzeptanz:

• Alle Dateien mit korrekten Scope-Symbolen
• Scope- und Neutralisierungs-Toggle funktionieren mit API-Calls
• Visuell klar und unkompliziert

Abhängigkeiten: AP 2.3, AP 2.4

---

AP 2.7 — [FE] UDB: Sources-Tab mit Active/Browse

Beschreibung: Datenquellen-Tab mit Trennung zwischen Active Sources (mit Icons) und Browse Sources (Katalog ohne Icons).

Dateien:

• frontend_nyla/src/components/UnifiedDataBar/SourcesTab.tsx — NEU

Schritte:

1. Active Sources: Eingebundene Quellen mit Scope- und Neutralisierungs-Symbolen
2. Browse Sources: Verfügbare Quellen als Katalog (keine Symbole)
3. Feature Data: Daten pro Feature-Instanz (Tabellen-Übersicht)
4. Aktivierung: Drag aus Browse in Active oder Klick → Default-Scope setzen
5. Deaktivierung: x-Button bei Active Sources

Akzeptanz:

• Klare Trennung Active vs. Browse
• Symbole nur bei Active Sources
• Aktivierung setzt Defaults korrekt

Abhängigkeiten: AP 2.3, AP 2.4

---

AP 2.8 — [FE] UDB: Drag-and-Drop in Prompt

Beschreibung: Alle UDB-Elemente (Chats, Files, Sources) können per Drag-and-Drop in den Prompt gezogen werden. Bei Chats werden die RAG-Daten des Chats abgefragt, nicht der Chat-Inhalt.

Dateien:

• frontend_nyla/src/components/UnifiedDataBar/ — DnD-Logik
• Prompt-Eingabe-Komponente — Drop-Zone

Schritte:

1. Drag-Source auf allen UDB-Elementen (Chats, Files, Sources)
2. Drop-Zone im Prompt-Bereich
3. Chats: Bei Drop → RAG-Query nach Daten, die dem Chat zugeordnet sind (nicht Chat-Inhalt selbst)
4. Files: Bei Drop → Datei als Kontext-Dokument anhängen
5. Sources: Bei Drop → Datenquelle als aktiven Kontext setzen
6. Visuelles Feedback: Drag-Preview, Drop-Highlight, Kontext-Badge im Prompt

Akzeptanz:

• Drag-and-Drop funktioniert für alle drei Tabs
• Chats liefern RAG-Daten, nicht Chat-Inhalt
• Visuelles Feedback bei Drag und Drop

Abhängigkeiten: AP 2.5, AP 2.6, AP 2.7

---

AP 2.9 — [FE] UDB: Integration in alle Feature-Instanzen

Beschreibung: UDB in alle bestehenden Features einbinden (Workspace, CommCoach, Trustee, Automation).

Dateien:

• Feature-Seiten: Workspace, CommCoach, Trustee, Automation — UDB einbinden

Schritte:

1. Workspace: UDB ersetzt bestehende Sidebar (bereits in AP 2.4)
2. CommCoach: UDB als Sidebar einbinden
3. Trustee: UDB als Sidebar einbinden
4. Automation: UDB als Sidebar einbinden
5. Pro Feature: Korrekter Kontext (featureInstanceId) an UDB übergeben
6. Layout-Anpassungen pro Feature

Akzeptanz:

• Alle Features haben die UDB
• Kontext stimmt pro Feature-Instanz
• Keine Feature-eigenen Sidebar-Duplikate mehr

Abhängigkeiten: AP 2.4 — AP 2.8

---

AP 2.10 — [BE] Doppelte Strukturen konsolidieren

Beschreibung: Datensilos auflösen: Voice-Definitionen, Dokumentenkontext und Wissensbasis mandantenweit verfügbar machen.

Dateien:

• CommCoach Voice-Datenmodell — Scope-Feld hinzufügen
• Workspace Dokument-Logik — Scope-basierte Queries

Schritte:

1. Voice-Definitionen: Von instanz-zentriert auf mandantenweit umstellen (scope=mandate)
2. Wissensbasis: Von instanz-zentriert auf scope-basiert (User wählt Scope)
3. Dokumenten-Kontext: Mandantenweite Suche mit Scope-Filter
4. Feature-spezifische Daten-Tabellen: scope-Feld wo nötig
5. Migration bestehender Daten: Default-Scope setzen

Akzeptanz:

• Voice-Definitionen mandantenweit nutzbar
• Keine doppelten Definitionen mehr nötig
• Cross-Feature-Zugriff auf Wissensbasis funktioniert

Abhängigkeiten: AP 2.1, AP 2.2

---

Phase 3 — Unified Data Layer + Neutralisierung als Kerndisziplin

Ziel: Features sind reine Workflow-Oberflächen. UDL mit Neutralisierung ist der Plattformkern. FeatureInstance = UI-Scope.

Voraussetzung: Phase 2 vollständig abgeschlossen.

---

AP 3.1 — [BE] Neutralisierung: Fail-Safe-Logik

Beschreibung: Wenn Neutralisierung fehlschlägt, wird das Dokument nicht weitergegeben. Kein Fallback auf Originaldaten.

Dateien:

• gateway/modules/workflows/methods/methodContext/actions/neutralizeData.py — Fail-Safe einbauen
• gateway/modules/features/neutralization/serviceNeutralization/ — Error Handling

Schritte:

1. Bestehende Error-Handling-Logik ändern: Bei Fehler nicht das Original-Part verwenden
2. Stattdessen: Part überspringen + Warning-Flag setzen
3. ChatWorkflow: Hinweis „Dokument X konnte aus Datenschutzgründen nicht einbezogen werden"
4. AI-Call läuft ohne das fehlgeschlagene Dokument weiter
5. Logging: Fehlergrund (Timeout, Modell nicht erreichbar, etc.)
6. Beim RAG-Indexing: Neutralisierung fehlgeschlagen → Dokument nicht indizieren, neutralizationStatus=failed

Akzeptanz:

• Kein Originaldokument geht an externe AI wenn Neutralisierung fehlschlägt
• User sieht Hinweis, welches Dokument fehlt und warum
• AI-Call funktioniert ohne das fehlende Dokument

Abhängigkeiten: Phase 2 abgeschlossen

---

AP 3.2 — [BE] Neutralisierung: RAG-Integration

Beschreibung: Datenquellen mit neutralize=true werden nur in neutralisierter Form im RAG indiziert.

Dateien:

• RAG-Indexing-Pipeline — Neutralisierungs-Gate
• gateway/modules/features/neutralization/ — Pipeline-Integration

Schritte:

1. Beim Einbinden einer Datenquelle mit neutralize=true:
   • Container auflösen (bestehende Extraction-Pipeline)
   • Media droppen
   • Bilder → neutraler Text via Modell mit opType=neutralization
   • Text → neutralisieren via StringParser + Modell mit opType=neutralization
   • Platzhalter-Mapping in DataNeutralizerAttributes persistieren
   • Nur neutralisierte Version im RAG indizieren
2. Bei neutralize=false: Direkt indizieren (wie bisher)
3. Re-Neutralisierung bei Flag-Änderung (async Batch-Job)

Akzeptanz:

• Neutralisierte Datenquellen: nur neutralisierte Version im RAG
• Mapping-Tabelle wird korrekt befüllt
• Re-Neutralisierung bei Flag-Änderung funktioniert

Abhängigkeiten: AP 3.1, AP 2.1

---

AP 3.3 — [BE] Neutralisierung: AI-Call-Integration + Re-Hydrierung

Beschreibung: Bei AI-Calls mit requireNeutralization=true: Prompt live neutralisieren und Response re-hydrieren.

Dateien:

• Workflow-Manager / Chat-Pipeline — Pre-/Post-Processing
• gateway/modules/workflows/workflowManager.py

Schritte:

1. Pre-Processing: Wenn requireNeutralization=true:
   • User-Prompt durch Neutralisierungs-Pipeline
   • RAG-Kontext-Dokumente: bereits neutralisiert (aus RAG-Index)
   • Prompt-Mapping in temporärer Tabelle
2. AI-Call mit neutralisiertem Prompt + neutralisierten Dokumenten
3. Post-Processing: AI-Response re-hydrieren
   • Platzhalter via Mapping-Tabelle durch Originale ersetzen
   • Konsistenz: [PERSON_1] = immer derselbe Originalwert (persistent pro Datenquelle)
4. Re-hydrierte Response an User ausliefern

Akzeptanz:

• Live-Neutralisierung von User-Prompts funktioniert
• Re-Hydrierung ersetzt Platzhalter korrekt
• Platzhalter-Konsistenz über Calls hinweg

Abhängigkeiten: AP 3.1, AP 3.2

---

AP 3.4 — [FE] ChatWorkflow-Transparenz: „Gesendete Daten"

Beschreibung: Im Chat-UI: aufklappbarer Bereich, der die neutralisierten Dokumente zeigt, die an das AI-Modell gesendet werden.

Dateien:

• Chat-UI-Komponente — Neue Sektion „Gesendete Daten (neutralisiert)"

Schritte:

1. API liefert ActionDocument-Liste mit neutralized=true Metadaten im ChatWorkflow
2. UI: Aufklappbarer Bereich unter jedem AI-Call
3. Anzeige: Dokumentname, Neutralisierungs-Status, Vorschau des neutralisierten Texts
4. Hinweis wenn Dokument übersprungen wurde (Fail-Safe)
5. Link zur Neutralisierungs-Konfiguration der Datenquelle

Akzeptanz:

• User sieht bei jedem AI-Call, was rausgegangen ist
• Übersprungene Dokumente sind sichtbar mit Grund
• Aufklappbar (nicht standardmässig offen)

Abhängigkeiten: AP 3.3

---

AP 3.5 — [FE] Neutralisierung: User-Kontrolle

Beschreibung: UI für Einsicht und Verwaltung der neutralisierten Daten und Platzhalter-Mappings.

Dateien:

• Neue Seite oder Sektion im Settings-Bereich

Schritte:

1. Übersicht: Alle Datenquellen mit Neutralisierungs-Status
2. Pro Datenquelle: Detailansicht der Platzhalter-Mappings (Original ↔ Platzhalter)
3. Löschen: Einzelne Mappings oder alle Mappings einer Datenquelle
4. Status: pending, completed, failed, not_required
5. Re-Trigger: Neutralisierung manuell neu anstossen

Akzeptanz:

• User kann alle Mappings einsehen
• Löschen funktioniert
• Status ist korrekt und aktuell

Abhängigkeiten: AP 3.2

---

AP 3.6 — [BE] RAG-Scopes: Vollständige Implementierung

Beschreibung: Alle vier Scopes (personal, featureInstance, mandate, global) vollständig implementiert mit korrekter Union-Query und RBAC.

Dateien:

• RAG-Query-Engine — vollständige Scope-Logik
• RBAC-Layer — Scope-Berechtigungen

Schritte:

1. personal: Nur Daten des anfragenden Users
2. featureInstance: Alle Daten der aktuellen Instanz (alle User mit FeatureAccess)
3. mandate: Alle Daten aller Instanzen im Mandat
4. global: Alle plattformweiten Daten (read-only, nur sysadmin setzbar)
5. Union-Query: Effiziente Kombination aller anwendbaren Scopes
6. Caching: Scope-Metadaten cachen für Performance

Akzeptanz:

• Alle Scope-Kombinationen funktionieren korrekt
• User sieht nie Daten ausserhalb seiner Berechtigung
• Performance: Union-Query < 500ms

Abhängigkeiten: AP 2.2, AP 3.2

---

AP 3.7 — [FE] Onboarding-Assistant

Beschreibung: Kontextsensitiver Onboarding-Begleiter für neue User und leere Zustände.

Dateien:

• frontend_nyla/src/components/OnboardingAssistant.tsx — NEU

Schritte:

1. Trigger-Bedingungen: Kein Mandate, keine Instanzen, keine Chats, nach Pause
2. Schritt 1: Mandant-Typ bestätigen (bei OAuth)
3. Schritt 2: Erste Feature-Instanz aktivieren (Empfehlung: Workspace)
4. Schritt 3: Erste Datenquelle einbinden (Upload oder Konnektor)
5. Schritt 4: Erster AI-Call (geführter Prompt)
6. Kontextsensitiv: Erscheint bei neuen Features, nach Pausen, bei leeren Zuständen
7. Dismissable: User kann jederzeit überspringen, aber Assistant kommt bei relevantem Trigger zurück

Akzeptanz:

• Neue User durchlaufen den 4-Schritt-Flow
• Assistant erscheint kontextsensitiv
• Kein Nerv-Faktor (smart triggers, nicht bei jedem Login)

Abhängigkeiten: AP 2.9

---

AP 3.8 — [BE/FE] FeatureInstance als UI-Scope (Semantische Verschiebung)

Beschreibung: Features werden zu reinen Workflow-Oberflächen. Die FeatureInstance definiert den UI-Kontext, nicht mehr die Datengrenze. Der Unified Data Layer ist die Datengrenze.

Dateien:

• Feature-Logik in allen Features — Daten-Queries auf UDL umstellen
• Instanz-Referenzen — von Daten-Ownership auf UI-Scope

Schritte:

1. Daten-Queries: Von WHERE featureInstanceId = X auf Scope-basierte RAG-Queries umstellen
2. featureInstanceId bleibt als Herkunftsreferenz (Quellenschutz), steuert aber nicht mehr den Zugriff
3. Zugriff wird über Scope + RBAC gesteuert
4. Feature-Instanz liefert: Workflow-Oberfläche, Feature-spezifische Substrukturen, Default-Scope-Kontext
5. Alle Features verifizieren: Datenfluss via UDL statt Instanz-Silo

Akzeptanz:

• Features zeigen Daten aus dem UDL (nicht nur eigene Instanz)
• Cross-Feature-Datennutzung funktioniert
• featureInstanceId dient nur noch als Herkunftsinfo

Abhängigkeiten: AP 3.6, AP 2.9, AP 2.10

---

Zusammenfassung

Phase	Arbeitspakete	Schwerpunkt
Phase 1	AP 1.1 — 1.15 (15 APs)	Mandanten-Grenze, Registrierung, Store, Migration, Löschung
Phase 2	AP 2.1 — 2.10 (10 APs)	UDB, Scope-Tagging, RAG-Filter, Cross-Feature-Zugriff
Phase 3	AP 3.1 — 3.8 (8 APs)	Neutralisierung, RAG-Scopes, Onboarding-Assistant, UI-Scope-Shift
Total	33 Arbeitspakete

Abhängigkeitsgraph (kritischer Pfad)

Phase 1:
  AP 1.1 (mandateType) ──┬── AP 1.2 (Subscription PENDING) ── AP 1.3 (_provision)
                          │                                          │
                          │   ┌──────────────────────────────────────┘
                          │   │
                          ├── AP 1.4 (Register Local) ── AP 1.11 (FE Register)
                          │   │
                          ├── AP 1.5 (Register OAuth) ── AP 1.12 (FE Login + Wizard)
                          │   │
                          ├── AP 1.6 (Store Refactoring) ── AP 1.7 (Auto-Mandate) ── AP 1.13 (FE Store)
                          │
                          ├── AP 1.8 (Subscription Volume) ── AP 1.14 (FE Volume)
                          │
                          ├── AP 1.9 (Migration Script) ── AP 1.15 (Bootstrap)
                          │
                          └── AP 1.10 (Mandanten-Löschung)

Phase 2: (nach Phase 1)
  AP 2.1 (Scope-Felder) ── AP 2.2 (RAG Scope-Filter) ── AP 2.3 (Tagging API)
                                                              │
  AP 2.4 (UDB Extraktion) ── AP 2.5 (Chats) ─┐              │
                              AP 2.6 (Files) ──┤── AP 2.8 (DnD) ── AP 2.9 (Integration)
                              AP 2.7 (Sources)─┘
                                                                     │
  AP 2.10 (Konsolidierung) ─────────────────────────────────────────┘

Phase 3: (nach Phase 2)
  AP 3.1 (Fail-Safe) ── AP 3.2 (RAG-Integration) ── AP 3.3 (AI-Call + Rehydrate) ── AP 3.4 (FE Transparenz)
                              │
                              └── AP 3.5 (FE User-Kontrolle)
                              
  AP 3.6 (RAG-Scopes komplett) ── AP 3.8 (UI-Scope-Shift)
  
  AP 3.7 (Onboarding-Assistant)

---

Umsetzungsplan-Version: 2026-03-23 v1 — Basierend auf Konzeptdokument v4. 33 Arbeitspakete in 3 Phasen.