19 KiB
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 |
|
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_atentity_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 austitle + subtitle + body_textmit 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_defür FTS - IVFFlat / HNSW-Index auf
embeddingfü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_atquery_textapplied_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_atsearch_index_entry_id(FK)provider(Enum:mistral | scaleway | alephalpha)status(pending | running | completed | failed | retrying)attemptslast_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:
- FTS-Pfad (Postgres
tsvector+tsquerymit deutscher Konfiguration; Trigram-Index als Ergänzung für Fuzzy-Match auf Namen)- Liefert exakte und Wortform-Treffer (Stemming, Umlaut-Normalisierung)
- Sehr schnell, deterministisch
- 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
- 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 intitle, 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/UPDATEeiner Quell-Entity → Outbox-Eintrag → Worker holt Eintrag, bautbody_textüber Adapter (Block D), ruft Embedding-Provider, persistiert inSearchIndexEntry.embedding - Sehr kurze Texte (< 10 Zeichen):
embedding_status = skipped— nur FTS - Bei Provider-Failure: Retry mit Backoff bis 3 Versuche, dann
failedmitlast_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)
- Funktion
- 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 = truesetzen - Permission-relevante Änderung (z.B.
assigned_to_user_id) →permission_subjectaktualisieren (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}/searchmit 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
/searchmit 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 proSearchIndexEntryenthä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 mitassigned_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: keineuser-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 aktualisiertSearchIndexEntry - Trigger-Alternative für Phase 1: Postgres-Trigger auf relevanten Tabellen, die direkt synchron
SearchIndexEntryupdaten (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.adminodertenant.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_texteinfließen lassen - Tenant-Admin-konfigurierbare Gewichtung zwischen FTS und Semantik
- Multi-Sprache: weitere
tsvector-Konfigurationen je nachtenant.languageund 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_idund 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
filterVisibleForUsereinfließ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