Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M24-globale-suche.md
T

19 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
24 Globale Suche 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-1
LP-9
LP-10
LP-13
requirements-pur

Modul 24 — Globale Suche

Detail-Spec gemäß LP-9. Cmd+K-Stil-Suche überall verfügbar (Header der App). Cross-Entity, hybrid (Postgres-FTS + pgvector-Embeddings über EU-Provider), permission-aware. Adapter-Pattern: jedes Modul registriert seine durchsuchbaren Entitäten.

Themenblöcke

A. Datenmodell (SearchableEntity-Index, RecentSearch, Embedding-Cache)
B. Menü-Struktur und Routes
C. Hybrid-Suche (FTS + Embeddings)
D. Adapter-Pattern (Modul-Registrierung)
E. UI-Anforderungen (Modal/Cmd+K + Vollbild-Suche)
F. Permissions / Sichtbarkeit
G. Recent Searches
H. Performance & Indexierung
I. Klartext-Hinweise

Block A — Datenmodell

SearchIndexEntry (zentrale Index-Tabelle)

Tenant-scoped, RLS-aktiv. Wird von jedem Modul-Adapter befüllt; ermöglicht eine einzige Such-Query über alle Entitäten.

  • id, tenant_id, created_at, updated_at
  • entity_type (Enum: contact | company | lead | deal | project | file | form_submission | user | task | wiki_page — wiki Phase 2)
  • entity_id (Polymorpher FK auf das jeweilige Modul-Entity)
  • title (Hauptsächlicher Treffer-Titel; z.B. Kontakt-Name, Deal-Titel)
  • subtitle (optional; z.B. Firma beim Kontakt, Deal-Stage)
  • body_text (gesamter durchsuchbarer Volltext-Inhalt; konkateniert aus relevanten Feldern)
  • tsvector_de (Generated Column aus title + subtitle + body_text mit deutscher Konfiguration)
  • embedding (vector(1024) — pgvector; siehe Block C für Provider)
  • embedding_generated_at (Timestamp; NULL bei pending)
  • embedding_status (Enum: pending | generating | ready | failed | skipped)
  • permission_subject (JSONB — modulares Permissions-Subject für Filter-Anwendung; z.B. {"assigned_to_user_id": "uuid", "module": "crm"})
  • last_activity_at (für Sortier-Boost im Default-Ranking)
  • is_archived (Boolean — archivierte Einträge sind suchbar mit Toggle, default ausgeblendet)

Indizes:

  • GIN-Index auf tsvector_de für FTS
  • IVFFlat / HNSW-Index auf embedding für Cosine-Similarity
  • (tenant_id, entity_type, entity_id) unique
  • (tenant_id, is_archived, last_activity_at DESC) für Sortier-Default

Sonderfall: SearchIndexEntry ist Sekundär-Index — Source-of-Truth bleibt das jeweilige Modul-Entity. Updates über Trigger oder Outbox-Pattern (siehe Block H).

RecentSearch

Pro User, nicht tenant-scoped (User-Setting; trotzdem tenant_id für Trennung).

  • id, tenant_id, user_id, created_at
  • query_text
  • applied_filters (JSONB — gewählte Entity-Typen, Zeitraum, etc.)
  • result_count (für Display)
  • clicked_entity_type, clicked_entity_id (optional — falls User auf Treffer geklickt hat; für Personalisierung Phase 2)

Index: (tenant_id, user_id, created_at DESC).

Retention: letzte 50 pro User, ältere automatisch gelöscht.

EmbeddingProviderJob

Worker-Queue-State für asynchrone Embedding-Generation.

  • id, tenant_id, created_at, updated_at
  • search_index_entry_id (FK)
  • provider (Enum: mistral | scaleway | alephalpha)
  • status (pending | running | completed | failed | retrying)
  • attempts
  • last_error_text (Klartext)
  • completed_at

Block B — Menü-Struktur und Routes

Sidebar-Hauptpunkt: keiner (Suche ist global verfügbar im Header).

Routen:

/{tenant}/search                       → Vollbild-Such-View (für komplexe Filter, Saved Searches Phase 2)
/{tenant}/search?q=...&types=...       → Direkt-Link mit Query und Filtern (URL-state)

Embedded-Komponente:

  • Such-Modal-Komponente (Cmd+K / Ctrl+K) ist global verfügbar in jedem authentifizierten Layout
  • Triggered durch Tastenkürzel (Cmd+K / Ctrl+K) oder Klick auf Such-Anker im Header
  • Auf Mobile: Such-Anker im Header, öffnet Vollbild-Modal

Block C — Hybrid-Suche (FTS + Embeddings)

Such-Strategie

Bei Query q:

  1. FTS-Pfad (Postgres tsvector + tsquery mit deutscher Konfiguration; Trigram-Index als Ergänzung für Fuzzy-Match auf Namen)
    • Liefert exakte und Wortform-Treffer (Stemming, Umlaut-Normalisierung)
    • Sehr schnell, deterministisch
  2. Semantischer Pfad (pgvector Cosine-Similarity)
    • Query wird zu Embedding über EU-Provider (siehe unten)
    • Top-N nächste Einträge nach Cosine-Distance
    • Liefert semantisch ähnliche Treffer auch ohne Wort-Übereinstimmung
  3. Fusion (Reciprocal Rank Fusion oder einfaches Score-Merging mit gewichteter Summe)
    • Gewichtung Default: 70% FTS / 30% Semantisch (Tenant-Admin-konfigurierbar Phase 2)
    • Zusätzliche Boosts: aktuelle last_activity_at, exakter Match in title, User-eigene Entitäten

Embedding-Provider (LP-13: EU-Stack)

  • Primär: Mistral Embeddings (mistral-embed)
  • Sekundär: Scaleway-Hosted Embeddings
  • Tertiär: AlephAlpha
  • Embedding-Dimension einheitlich 1024 (Mistral-embed); falls Provider-Wechsel nötig → Re-Embedding-Job für gesamten Index
  • Provider-Fallback automatisch bei Down (siehe AV #13 / EC-6)

Embedding-Generation-Strategie

  • Bei INSERT / UPDATE einer Quell-Entity → Outbox-Eintrag → Worker holt Eintrag, baut body_text über Adapter (Block D), ruft Embedding-Provider, persistiert in SearchIndexEntry.embedding
  • Sehr kurze Texte (< 10 Zeichen): embedding_status = skipped — nur FTS
  • Bei Provider-Failure: Retry mit Backoff bis 3 Versuche, dann failed mit last_error_text
  • Initial-Backfill bei Tenant-Migration: Bulk-Job über alle bestehenden Entitäten

Query-Embedding-Caching

  • Häufige Such-Queries werden als Embedding gecacht (24h TTL) → reduziert Provider-Kosten
  • Cache-Key: SHA256(query_text + provider_version)

Block D — Adapter-Pattern (Modul-Registrierung)

Anforderungen (LP-11)

Jedes Modul, das Entitäten durchsuchbar machen will, registriert einen SearchAdapter:

  • Liefert pro Entity-Typ:
    • Funktion buildSearchableContent(entity) → { title, subtitle, body_text } (welche Felder fließen in den Index)
    • Funktion buildPermissionSubject(entity) → JSONB (welche Daten brauchen wir später für Permissions-Filter)
    • Funktion getRouteForEntity(entity) → string (Ziel-Route bei Treffer-Klick)
    • Funktion getDisplayMetadata(entity) → { icon_kind, badge_text, ... } (für UI-Anzeige; Designer entscheidet finales Aussehen)
    • Liste der triggers (welche DB-Events lösen Re-Indexierung aus)
  • Definiert seinen entity_type-Wert (Enum-Eintrag)
  • Definiert Permissions-Filter-Funktion: filterVisibleForUser(searchEntries, userPermissions) → searchEntries[]

Modul-Initial-Registrierungen (Phase 1)

Modul Entity-Typen
Modul 1 (CRM) contact, company, lead
Modul 3 (Sales-Pipeline) deal
Modul 4 (Projekt-Pipeline) project, order
Modul 5 (Form-Builder) form_submission
Modul 14 (HR-Hub) user (Mitarbeiter) — eingeschränkte Sichtbarkeit
Modul 23 (Files) file
Modul 26 (Tasks) task

Phase 2 Erweiterungen

  • Modul 16 (Wiki) → wiki_page
  • Modul 9 (Email-Inbox) → email_message (mit DSGVO-spezifischer Sichtbarkeit)
  • Modul 13 (Team-Chat) → chat_message (sehr restriktive Permissions)

Re-Indexierungs-Trigger

  • INSERT der Quell-Entity → SearchIndexEntry anlegen (Outbox)
  • UPDATE relevanter Felder (laut Adapter) → SearchIndexEntry aktualisieren + Embedding-Re-Generation
  • DELETE / Archivierung → SearchIndexEntry löschen oder is_archived = true setzen
  • Permission-relevante Änderung (z.B. assigned_to_user_id) → permission_subject aktualisieren (kein Re-Embedding nötig)

Block E — UI-Anforderungen

Such-Modal (Cmd+K)

Zu zeigende Daten:

  • Eingabefeld für Query-Text mit Live-Suche
  • Trefferliste, gruppiert nach entity_type
  • Pro Treffer: Titel, Subtitle, Entity-Typ-Indikator (Designer wählt visuelles Zeichen), Kontext-Snippet (Highlight der Match-Stelle aus body_text), letzte Aktivität (relativ)
  • Bei leerem Query: Recent-Searches (siehe Block G) + Tipps („Tippe um zu suchen", „Cmd+K für Suche überall")
  • Bei keinem Treffer: Klartext + Vorschläge (siehe Block I)
  • Loading-Indikator während Suche

Benötigte UI-Elemente:

  • Such-Eingabefeld mit Auto-Fokus beim Öffnen
  • Trefferliste mit Tastatur-Navigation (Pfeiltasten + Enter zum Öffnen, Cmd+Enter für „in neuem Tab")
  • Filter-Chips für Entity-Typ-Auswahl (z.B. „Nur Kontakte", „Nur Files") — Multi-Select
  • Mehr-Treffer-Funktion („alle {n} Treffer zeigen" → leitet auf /{tenant}/search mit Query)
  • Schließen-Funktion (Esc oder Klick außerhalb)
  • Keyboard-Shortcut-Anzeige (z.B. „↑↓ navigieren • Enter öffnen • Esc schließen")

Operationen:

  • Enter / Klick auf Treffer → öffnet die Ziel-Route (über Adapter getRouteForEntity)
  • Filter-Chip-Klick → schränkt Treffer auf gewählte Typen ein
  • „Alle Treffer anzeigen" → leitet auf /search mit Query und Filtern als URL-Param

Vollbild-Such-View (/{tenant}/search)

Zu zeigende Daten:

  • Such-Eingabefeld (vorausgefüllt aus URL-Param)
  • Vollständige Trefferliste mit Pagination (Cursor-basiert, 50 pro Page)
  • Pro Treffer: alle Daten wie im Modal + erweiterte Metadaten (Erstellt-Datum, Verantwortlicher, Tags)
  • Filter-Sidebar/Sektion mit:
    • Entity-Typ (Multi-Select)
    • Erstellt-Zeitraum (Date-Range)
    • Verantwortlicher (Multi-Select)
    • Tags (Multi-Select)
    • Modul-spezifische Filter (Adapter-erweitert: z.B. Deal-Stage bei deal-Filter)
    • Toggle „Archivierte einbeziehen"
  • Trefferanzahl-Anzeige (Klartext: „1.247 Treffer in 0,3 Sek")
  • Sortier-Optionen: Relevanz (Default) / Letzte Aktivität / Erstellt-Datum

Benötigte UI-Elemente:

  • Such-Feld
  • Filter-Komponenten (siehe Liste oben)
  • Trefferliste mit Pagination
  • Sortier-Auswahl
  • Klick auf Treffer → Ziel-Route

Mobile-Anforderungen

  • Such-Modal als Vollbild-Layer
  • Tastatur öffnet automatisch
  • Touch-Optimierte Trefferliste

Performance-Anforderungen

  • Debounce: 300ms zwischen Tippen und Query (kein Server-Hit pro Tastendruck)
  • Initial-Response binnen 500ms (FTS-Pfad)
  • Semantischer Pfad darf länger laufen (Embedding-Provider-Latenz) — Trefferliste wird nachgeladen wenn Embeddings da
  • „Loading more results"-Indikator während Embedding-Pfad noch läuft

Block F — Permissions / Sichtbarkeit

Anforderungen (AV #5: Permissions-aware-Default)

  • Suche darf niemals Treffer anzeigen, die der User regulär nicht sehen darf
  • Filter wird server-side angewendet, bevor Treffer an den Client gehen (kein Client-side-Hidings — User kann sonst Existenz aus Trefferanzahl ableiten)
  • permission_subject-JSONB pro SearchIndexEntry enthält die Daten, die der modulspezifische Filter braucht (z.B. assigned_to_user_id, project_team_member_ids)
  • Pro Adapter: filterVisibleForUser(entries, userPermissions) reduziert Treffer auf erlaubte

Beispiele

  • User mit crm.read_own: nur Contacts/Deals/Leads mit assigned_to_user_id = self
  • User mit projects.read_own: nur Projekte, in deren Team er Mitglied ist
  • User ohne files.read_*: keine Files in den Treffern
  • User ohne hr.read_all: keine user-Treffer (bzw. nur eigener User-Eintrag)

Trefferanzahl-Konsistenz

  • Trefferanzahl bezieht sich immer auf erlaubte Treffer (nicht auf Index-Gesamtmenge)
  • Klartext bei massiv reduzierter Anzeige: „Es gibt weitere Treffer, die du aufgrund deiner Berechtigungen nicht siehst." (nur wenn signifikant — sonst Verwirrung; konkrete Anzahl bewusst nicht genannt)

Audit-Log

  • Suchanfragen mit Inhalt und Trefferanzahl werden im User-Activity-Trail (Modul 21) geloggt
  • Bei sensiblen Themen (HR-Suche, Lohnabrechnungen) optional erweiterte Audit-Granularität — Phase 2

Block G — Recent Searches

Anforderungen

  • Pro User die letzten 50 Suchanfragen gespeichert (siehe Datenmodell RecentSearch)
  • Anzeige im Modal bei leerem Query
  • Klick auf Recent-Search-Eintrag → setzt Query und Filter neu, führt Suche aus

Operationen

  • Einzelne Recent-Search löschen
  • Alle Recent-Searches löschen (User-Setting in /settings/)
  • Auto-Cleanup: ältere als 50 oder älter als 90 Tage werden automatisch entfernt

Privacy

  • Recent-Searches sind privat pro User — kein Tenant-Admin-Zugriff
  • Bei DSGVO-Export (Modul 35) eines Users werden die eigenen Recent-Searches mit ausgegeben
  • Bei Account-Löschung werden Recent-Searches hart gelöscht

Block H — Performance & Indexierung

Indexierungs-Architektur

  • Outbox-Pattern: schreibende Operationen in Modul-Tabellen schreiben Events in search_outbox (Tenant-scoped); Worker konsumiert Events und aktualisiert SearchIndexEntry
  • Trigger-Alternative für Phase 1: Postgres-Trigger auf relevanten Tabellen, die direkt synchron SearchIndexEntry updaten (FTS-Felder); Embedding-Generation läuft asynchron
  • Entscheidung: Outbox bevorzugt, weil weniger Trigger-Last und besser für hohe Schreibraten

Index-Größen-Schätzung

  • Geerkens-Größe: ~5.000 Kontakte + ~3.000 Deals + ~2.000 Projekte + ~10.000 Files + ~50 User = ~20.000 Einträge → unproblematisch
  • 1.024-dim Embeddings × 20.000 = ~80 MB pro Tenant
  • HNSW-Index zusätzlich ~30%

Query-Performance-Ziele

  • FTS-Pfad: < 100ms p95
  • Embedding-Pfad: < 300ms p95 (bei warmem Cache); 1-3s bei Cold-Cache (erstes Embedding der Query)
  • Modal-Initial-Response: < 500ms (FTS-only first paint, Embeddings nachladen)

Indexierungs-Latenz

  • Update einer Entity → erscheint in Suche binnen 5-10 Sekunden (Outbox-Worker-Tick)
  • Klartext-Hinweis falls User direkt nach Anlegen sucht und nichts findet: „Neue Einträge erscheinen kurz nach Anlegen in der Suche."

Skalierung

  • pgvector mit IVFFlat-Index reicht für Phase-1-Größen
  • Bei Wachstum (10M+ Einträge global): Migration zu HNSW oder Sharding pro Tenant erwägen — Phase 2/3
  • Tenant-Pooling auf DB-Ebene; keine Cross-Tenant-Queries möglich

Block I — Klartext-Hinweise / Fehler-Cases (LP-10)

  • Keine Treffer: „Keine Treffer für ‚{query}'. Versuch andere Begriffe oder erweitere den Zeitraum-Filter."
  • Permission-bedingte Reduktion: „Es gibt weitere Treffer, die du aufgrund deiner Berechtigungen nicht siehst." (nur bei signifikantem Unterschied einblenden)
  • Embedding-Provider-Down: „Erweiterte semantische Suche ist gerade nicht verfügbar — Treffer kommen nur aus der Volltext-Suche." (Banner im Modal; Treffer trotzdem sinnvoll, nur weniger semantisch)
  • Zu kurze Eingabe (<2 Zeichen): „Tippe mindestens 2 Zeichen für die Suche."
  • Indexierungs-Verzögerung: „Neue Einträge erscheinen ein paar Sekunden nach dem Anlegen in der Suche." (nur bei Verdacht, dass User darauf wartet — z.B. wenn Query exakt einem gerade angelegten Namen entspricht und keine Treffer da sind)
  • Re-Indexierungs-Lauf (Admin-Trigger): „Such-Index wird neu aufgebaut. Suche kann temporär unvollständig sein. Status: {progress}%" (in /admin/-Bereich, Phase 2)
  • Server-Fehler: „Suche ist gerade nicht erreichbar. Bitte in einer Minute nochmal versuchen."

Permissions-Anwendung

Permission-IDs

Permission Erlaubt
search.use Globale Suche nutzen (Default für alle Tenant-User)
search.admin Re-Indexierungs-Lauf triggern, Index-Statistiken sehen

Hinweis: Die Suche selbst hat sehr leichtgewichtige Permissions, weil die eigentliche Sichtbarkeit über die Modul-Permissions der jeweiligen Entitäten bestimmt wird (siehe Block F).

Bundle-Mapping

Bundle Atomare Permissions
search.none (keine — Suche im Header ausgeblendet)
search.use search.use
search.admin search.use + search.admin

Anwendung in Routes

  • /{tenant}/search → search.use
  • Such-Modal global → search.use
  • /{tenant}/admin/search/ (Phase 2 Index-Verwaltung) → search.admin oder tenant.admin

Phase 2 / spätere Features

  • Saved Searches: User speichert Query + Filter unter Namen, ruft sie aus Dropdown auf
  • Erweiterte Operatoren: contact:max@firma.de status:active type:deal (Lucene-light-Syntax)
  • Search-Analytics: Tenant-Admin sieht häufige Queries, Null-Treffer-Queries (Hinweis auf fehlende Inhalte), Klick-Through-Rate
  • Personalisiertes Ranking: Treffer-Boost basierend auf User-Klick-Historie (Recent-Searches mit clicked_entity_*-Daten)
  • Cross-Tenant-Suche (für Plattform-Admin in admin.hivegrid.de) — sehr restriktiv
  • Wiki-/Knowledge-Base-Inhalte indexieren (sobald Modul 16 in Phase 2)
  • Email-Inhalte / Chat-Nachrichten indexieren (mit DSGVO-spezifischer Permissions-Schicht)
  • OCR-Texte aus Files (sobald Modul 23 OCR hat) ins body_text einfließen lassen
  • Tenant-Admin-konfigurierbare Gewichtung zwischen FTS und Semantik
  • Multi-Sprache: weitere tsvector-Konfigurationen je nach tenant.language und Phase-2-i18n-Roadmap (LP-12)

Architektur-Vorschriften (Querschnitt)

  • LP-9, AV #1: Klartext-Diagnostik (siehe Block I)
  • LP-11, AV #2: Adapter-Pattern für Modul-Registrierung (siehe Block D)
  • LP-13, AV #12: EU-Stack — Embeddings ausschließlich über Mistral / Scaleway / AlephAlpha
  • AV #5: Permissions-aware-Default — server-side-Filter, niemals Treffer durchsickern lassen
  • AV #6: Audit-Trail-Default — Suchanfragen werden geloggt
  • AV #13: Multi-Provider-Fallback für Embeddings
  • LP-1: Tenant-Isolation — Index pro Tenant via tenant_id und RLS
  • LP-9: Requirements-pur Spec ohne UI-Layout

Abhängige Module

  • Modul 1, 3, 4, 5, 14, 23, 26: liefern Adapter und werden durchsucht
  • Modul 17 (Automation Engine): stellt Worker-Queue für asynchrone Embedding-Generation bereit
  • Modul 18 (KI-Layer): stellt LLM-Gateway für Embedding-Provider-Calls bereit (LP-13, EU-Provider, Multi-Provider-Fallback)
  • Modul 21 (Audit-Log): Such-Anfragen werden geloggt
  • Modul 27 (Auth/Permissions): liefert User-Permissions, die in filterVisibleForUser einfließen
  • Modul 35 (DSGVO): Recent-Searches im DSGVO-Export

Detail-Spec-Status: DRAFT

Erste vollständige Detail-Spec für Modul 24. Vor Bau: Verifizierung mit Noah und Abgleich mit Modul 18 (LLM-Gateway-Spec) und Modul 17 (Worker-Queue-Spec).

Offene Detail-Punkte (nicht-blockierend):

  • Embedding-Dimension Standardisierung (1024 vs. 1536 vs. 768) — Provider-übergreifende Strategie
  • HNSW vs. IVFFlat — initial IVFFlat, Migration zu HNSW bei Skalierungs-Bedarf
  • Permission-Filter-Performance bei großen Tenants (10.000+ Treffer pro Query) — ggf. Materialized View pro User
  • Konkrete Outbox-Implementation (separate Tabelle vs. logisches Replication Slot)
  • Klartext-Schwellwert für „Es gibt weitere Treffer, die du nicht siehst"-Hinweis (Datenleak-Risiko vs. Klartext-Pflicht)
  • Recent-Searches: User-Opt-Out-Möglichkeit (Privacy-Setting) — Default an oder aus