24 KiB
Boilerplate-Abgleich: M24 — Globale Suche
Faktischer Abgleich der HiveGrid-Detail-Spec (M24) gegen die Boilerplate. Boilerplate-Wurzel (NUR LESEN):
/Users/raffaelsheikh/Documents/GitHub/boilerplateSpec-Quelle:/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M24-globale-suche.mdAlle Pfade absolut. Nichts erfunden — jeder Eintrag verweist auf konkrete Datei(en); fehlt etwas, ist es klar als Lücke markiert.
Kopf
| Feld | Wert |
|---|---|
| Modul-ID | M24 |
| Name | Globale Suche (Cmd+K, hybrid FTS + Embeddings, permission-aware, Adapter-Pattern) |
| Milestones | M056 (Such-Index), M057 (Permission-aware-Search), M058 (Such-UI + Saved-Searches) |
| Block | Block 2 (_bmad-output/pflichtenheft/blocks/block2.md, Modul 24) |
| Reuse-Level | MEDIUM |
Kernaussage: Die Boilerplate hat ein erstaunlich vollständiges Such-/Embedding-Such-Fundament: ein tenant-scoped @toolctrl/search-Paket (Index-Schemas, Outbox-Publisher, Query-Layer, Sanitize, Fallback-Pfad), den dazu passenden Search-Indexer-Worker (Upsert/Delete/Bulk-Reindex über Outbox→BullMQ), die komplette Embeddings-/RAG-Pipeline (@toolctrl/ai/embeddings) mit EU-Providern (Scaleway 1024-dim — exakter Match zur Spec) und den pgvector-Store mit tenant-scoped Wrapper. Außerdem existiert eine funktionierende Cmd+K-Command-Palette + SearchButton (in der Boilerplate-Web-App). Das Adapter-/Schema-Pattern (SearchIndexSchema, allowedDocumentFields-Whitelist) ist konzeptuell genau das von der Spec geforderte SearchAdapter-Modell.
Die zwei großen Architektur-Divergenzen, die das Reuse-Level auf MEDIUM drücken:
-
Such-Engine: Die Boilerplate sucht via Meilisearch (
packages/search→meilisearch-SDK). Die HiveGrid-Spec (Block C/H) und der M056-Plan verlangen Postgres-FTS (tsvector/tsquery, deutsche Konfiguration, „kein Extra-Service") + pgvector-Hybrid mit Reciprocal-Rank-Fusion. → Der FTS-Pfad und die Fusion sind in der Boilerplate nicht vorhanden. Es gibt einen SQL-ILIKE-Fallback (crmContactSearch.server.ts), aber keintsvector-FTS und keine Hybrid-Fusion. -
Daten-Modell: Die Spec verlangt eine zentrale
SearchIndexEntry-Tabelle (polymorpher Cross-Entity-Index mittsvector_de,embedding vector(1024),permission_subjectJSONB), plusRecentSearchundEmbeddingProviderJob. Keines dieser Prisma-Modelle existiert in der Boilerplate (verifiziert via Grep überprisma/schema/*.prisma). Die Boilerplate hält den Such-Index extern in Meilisearch + die Vektoren invec_*-Tabellen (von pgvector via Raw-SQL angelegt) — kein zentrales Postgres-Index-Modell.
Wo HiveGrid sich entscheiden muss: Entweder (A) die BP-Meilisearch-Architektur übernehmen (entgegen Spec/Plan, dafür mehr 1:1-Reuse) oder (B) bei Spec/Plan bleiben (Postgres-FTS) und nur die Embedding-/Vektor-Hälfte + Outbox-/Worker-/Adapter-Muster aus der BP übernehmen, den FTS-Pfad + SearchIndexEntry-Modell + Fusion neu bauen. Dieser Report bewertet gegen die HiveGrid-Spec (Variante B), weil Memory/Plan-Hinweise (M056: „Postgres FTS bevorzugen — kein Extra-Service") das so vorgeben.
Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
packages/search/src/schemas/types.ts |
SearchIndexSchema-Interface: name, primaryKey, searchableAttributes, filterableAttributes, sortableAttributes, rankingRules, allowedDocumentFields (Whitelist gegen PII-Leak) |
als-vorlage — konzeptuell exakt das SearchAdapter-Modell der Spec Block D (welche Felder fließen in den Index). Whitelist-Pattern (allowedDocumentFields) = direkte Vorlage für buildSearchableContent(). Muss um buildPermissionSubject(), getRouteForEntity(), getDisplayMetadata(), filterVisibleForUser() erweitert werden |
packages/search/src/schemas/{crm-contacts,users,rows,entities,kb-articles}.ts + schemas/index.ts |
Konkrete Index-Schema-Definitionen pro Entity-Typ; ALL_SEARCH_INDEXES, BULK_REINDEX_SUPPORTED_INDEXES, getSearchIndexSchema(name) (zentrale Schema-Registry) |
als-vorlage — Muster für HiveGrid indexedEntities-Map (INTEGRATION-CONTRACTS §8 packages/db/src/search/indexed-entities.ts). crm-contacts/users decken Adapter-Typen contact/user. Felder/Permission-Keys auf HiveGrid-Schema umsetzen |
packages/search/src/outbox-publisher.ts |
publishSearchUpsertEvent/publishSearchDeleteEvent/publishSearchBulkReindexEvent, searchEventType(entity, verb) → search.index.<entity>.<verb>; SearchOutboxPublisher-Interface (dependency-frei, in DB-Transaktion committbar) |
1:1 / anpassen — exakt das Outbox-Pattern der Spec Block H (schreibende Op → Outbox-Eintrag → Worker). Re-Index-Trigger (Insert/Update/Delete/Archiv) der Spec Block D docken hier an. sanitizeDocument-Aufruf bleibt; Event-Type-Konvention 1:1 übernehmbar |
packages/search/src/sanitize.ts (sanitizeDocument) |
Projiziert ein Dokument auf allowedDocumentFields (droppt nicht-gelistete Felder vor Index) |
1:1 — verhindert PII-Leak in den Index (Spec AV#5, M057 Field-Level-Redact-Fundament). Direkt für body_text-Aufbau wiederverwendbar |
packages/search/src/query.ts |
Tenant-scoped Query-Layer: searchInIndex, searchWithFallback, bulkIndex, deleteFromIndex, health, TenantScopeError; assertTenantId() erzwingt non-empty Tenant; buildFilter() AND-merged tenantId + extraFilters; Filter-Value-Escaping gegen Injection |
als-vorlage — Tenant-Isolation-Pattern (Spec LP-1, RLS-Äquivalent) + Fallback-Architektur (Spec Block I: „Embedding-Provider-Down → nur FTS"). Bei Variante B Meilisearch-spezifisch → Pattern (Tenant-Pflicht, Filter-Escaping, Fallback-Hook) übernehmen, SQL-FTS-Implementation neu schreiben |
apps/worker/src/jobs/search-indexer.ts |
Search-Indexer-Worker: konsumiert outbox.search-index-Queue, projiziert upsert/delete/bulk-reindex auf den Index; Cursor-Pager für Bulk-Reindex (1000er-Batches), BULK_PAGER_STALLED/BULK_REINDEX_INCOMPLETE-Guards, Tenant-Mismatch-Check Envelope↔Payload |
als-vorlage — exakt die Indexierungs-Architektur der Spec Block H (Outbox→Worker→Index, 5-10s Latenz). Bulk-Reindex = Initial-Backfill der Spec Block C + Admin-Re-Index (M_search.admin Phase 2). Bei Variante B: Index-Ziel von Meilisearch auf SearchIndexEntry-Upsert (FTS) + Embedding-Job-Enqueue umbauen |
apps/worker/src/jobs/search-indexer-bootstrap.ts + search-indexer-bulk-pagers.ts |
Worker-Bootstrap (Queue-Worker verdrahten) + Bulk-Pager-Registry pro Index | als-vorlage — Worker-Wiring-Muster |
apps/worker/src/outbox/{event-router,dispatcher,bootstrap}.ts |
Outbox-Event-Router (mappt search.index.* auf BullMQ-Queue outbox.search-index) + Dispatcher (liest Outbox-Tabelle, fan-out) |
als-vorlage / anpassen — generisches Outbox→Queue-Fan-out. HiveGrid braucht eigenes Outbox-Modell (Spec Block H search_outbox); das Router-/Dispatcher-Muster ist direkt übernehmbar |
packages/ai/src/embeddings/factory.ts + embeddings/types.ts |
createEmbeddingProvider(), registerEmbeddingProviderAdapter(), resolveEmbeddingProviderName(env) (Default-Reihenfolge), resolveEmbeddingDimensions(env); EmbeddingProvider-Interface (embed/embedSingle/dimensions/maxBatchSize), typisierte EmbeddingProviderError |
1:1 — Spec Block C Embedding-Generation-Fundament. Multi-Provider-Fallback-Architektur (Spec AV#13) |
packages/ai/src/embeddings/providers/scaleway.ts |
Scaleway-Embeddings-Adapter, Default-Modell bge-multilingual-gemma2 (1024 dim), Batch 64, max 4096 Tokens |
1:1 — Spec Block C: „Embedding-Dimension einheitlich 1024" + EU-Provider (LP-13). Exakter Match. (Spec nennt primär Mistral-embed; Scaleway-Adapter liefert ebenfalls 1024-dim → der von der Spec offen gelassene Dimensions-Punkt ist faktisch auf 1024 entschieden) |
packages/ai/src/embeddings/providers/aleph-alpha.ts |
Aleph-Alpha-Embeddings-Adapter (EU, Germany) | 1:1 — Tertiär-Provider der Spec Block C (alephalpha) |
packages/ai/src/embeddings/embed-and-upsert.ts |
embedAndUpsert() — chunked Embed + Upsert in VectorUpsertSink; erzwingt tenantId im Payload; deterministische buildChunkId(); optionale Kostenverfolgung via executeLLMCall (capability embedding) |
1:1 / anpassen — Spec Block C Schreibseite (bei Insert/Update → Embedding generieren). Re-Embed-bei-Text-Änderung (Spec Block D Trigger) + embedding_status-Pflege (pending/generating/ready/failed/skipped) andocken |
packages/ai/src/embeddings/retrieve.ts |
retrieveRelevantContext() — Query embedden, Fan-out über Collections, Rank-Merge (Score-sort + min-Score 0.7, top-K 8); tenant-scoped via RagRetrievalStore.searchForTenant |
1:1 / anpassen — Spec Block C semantischer Pfad. Rank-Merge ist die halbe Fusion — der FTS-Pfad + RRF-Gewichtung (70/30) muss ergänzt werden |
packages/ai/src/embeddings/chunking.ts |
splitForEmbedding(), countTokens(), DEFAULT_CHUNK_TOKENS/OVERLAP_TOKENS |
1:1 — Text-Chunking für body_text (lange Inhalte) |
packages/ai/src/embeddings/outbox-publisher.ts |
publishRagUpsertEvent/publishRagDeleteEvent, ragEventType() → rag.index.<entity>.<verb> (Queue outbox.rag-index), Idempotenz via dispatchKey |
als-vorlage — exakt das von der Spec Block C/D verlangte async Re-Embedding-Event-Muster (parallel zum FTS-Outbox). Kann für den Embedding-Teil des Such-Index 1:1 als Vorlage dienen |
apps/worker/src/jobs/rag-indexer.ts + rag-indexer-bootstrap.ts |
RAG-Indexer-Worker: konsumiert outbox.rag-index, chunk+embed+upsert / delete-by-source; tenant-scoped, provider-agnostisch |
als-vorlage — exakt die asynchrone Embedding-Generation der Spec Block C (Worker holt Eintrag, baut Text, ruft Provider, persistiert). Ziel-Sink von vec_*-Tabelle auf SearchIndexEntry.embedding umlenken; Retry-Backoff (Spec: 3 Versuche → failed mit last_error_text) ergänzen (EmbeddingProviderJob) |
packages/vector-store/src/factory.ts + adapters/pgvector.ts |
createVectorStore() (pgvector Default / Qdrant Upgrade), PgvectorAdapter über PrismaLike ($queryRawUnsafe), legt vec_<ns>_<collection>-Tabellen + HNSW-Index an, Payload-Filter via payload ->> 'key' |
1:1 / als-vorlage — Spec Block C/H: pgvector + Cosine-Similarity-Index. Spec lässt IVFFlat-vs-HNSW offen, nennt initial IVFFlat; BP-Adapter nutzt HNSW. Wenn HiveGrid das embedding-Feld direkt auf SearchIndexEntry legt (statt separate vec_*-Tabelle), ist der Adapter eher Vorlage für die SQL-Cosine-Query als 1:1-Drop-in |
packages/vector-store/src/wrappers/tenant-scoped.ts |
withTenantScope() → TenantScopedVectorStore; searchForTenant() injiziert tenantId-must-Filter zwingend; bare searchVectors() wirft |
1:1 — Spec LP-1 Tenant-Isolation für den Vektor-Pfad. „kein Cross-Tenant" built-in |
prisma/migrations/20260517085146_04_enable_pgvector/migration.sql |
Aktiviert pgvector-Extension in Postgres |
1:1 — Voraussetzung für SearchIndexEntry.embedding vector(1024) |
apps/web/app/components/ui/commandPalettes/CommandPalette.tsx + CommandPaletteDialog.tsx + command.tsx |
Cmd+K/Ctrl+K-Command-Palette: Keyboard-Listener (metaKey|ctrlKey + k), Lazy-Loaded Dialog, Context-Provider, ScopedCommandAction-Actions |
als-vorlage — Spec Block E: Cmd+K-Modal mit Auto-Fokus, Keyboard-Navigation, Esc-Schließen. Achtung: liegt in der Boilerplate-Web-App (shadcn-basiert), NICHT in HiveGrids packages/ui-hivegrid. M058-Plan-Hinweis „kbar in Boilerplate-Deps" ist faktisch falsch — kbar ist nirgends in der BP (verifiziert via Grep über alle package.json). Das vorhandene CommandPalette ist die nutzbare Vorlage, NICHT kbar |
apps/web/app/services/command-registry/commandRegistry.ts |
ScopedCommandAction-Registry (scoped Commands für die Palette) |
als-vorlage — Muster für Action-Registrierung im Such-Modal (Treffer-Klick → Route via getRouteForEntity) |
apps/web/app/components/layouts/buttons/SearchButton.tsx |
Such-Anker im Header (UI_ACTION_IDS.search, i18n shared.search, onClick-Trigger) |
als-vorlage — Spec Block B: „Such-Anker im Header", Mobile-Trigger. UI-Stil ist BP-spezifisch → in HiveGrid neu via Subframe/ui-hivegrid |
apps/web/app/modules/crm/services/crmContactSearch.server.ts |
Permission-/Tenant-scoped Such-Service mit Fallback Meilisearch→SQL-ILIKE (SEARCH_BACKEND=sql erzwingbar, transparenter Connectivity-Fallback) |
als-vorlage — Muster für Service-Layer (View-Model-Aufbau, Fallback-Architektur Spec Block I). Der SQL-ILIKE-Fallback ist KEIN tsvector-FTS, dient aber als Skelett für den HiveGrid-FTS-Service |
apps/web/app/modules/rows/services/rowSearch.server.ts + rowSearchOutbox.server.ts |
Generischer Row-Such-Service + Outbox-Anbindung (Domain-Write → Such-Event) | als-vorlage — Muster wie ein Domain-Modul seinen Adapter+Outbox verdrahtet (Spec Block D Modul-Registrierung) |
packages/queue/src/{names,payloads,producers}.ts |
BullMQ-Queue-Namen, typisierte Job-Payloads (inkl. ai.embedding), Producer mit Idempotenz (buildIdempotentJobId) |
1:1 / anpassen — async Embedding-Jobs (Spec Block C EmbeddingProviderJob). Eigener Queue-Eintrag outbox.search-index ist bereits konventioniert |
packages/ai/src/cost/executeLLMCall.ts |
Wrappt Provider-Calls, Token/Kosten-Tracking, Quota-Pre-Check, Outbox-Event ai.cost.event.persist |
1:1 — Query-Embedding-Calls (Spec Block C) sollen durch denselben Cost-Wrapper (capability embedding), damit Such-Embedding-Kosten ins Pay-as-you-go (M088) fließen |
packages/ai/src/cost/spend-cache.ts / createSpendCache + @toolctrl/shared-store createCacheStore |
Cache-Primitive (TTL) | als-vorlage — Spec Block C Query-Embedding-Caching (24h TTL, Cache-Key SHA256(query+provider_version)). createCacheStore (Redis-KV, Cross-Instance-Invalidation) ist das passende Primitive |
Vorhandene Daten-Modelle
Wichtig: Für die globale Suche selbst existiert in der Boilerplate kein einziges Prisma-Modell (kein SearchIndexEntry, kein RecentSearch, kein SavedSearch, kein EmbeddingProviderJob — verifiziert via grep -rilE "RecentSearch|SavedSearch|SearchIndex|SearchHistory" prisma/schema/). Die BP hält Such-Daten außerhalb von Prisma (Meilisearch-Indexe + pgvector-vec_*-Tabellen via Raw-SQL).
Mittelbar relevante / als-Index-Quelle dienende Modelle (Stand BP, ToolCTRL-Schema — NICHT HiveGrid-Entitäten):
| Modell | Pfad | Bezug zur Spec |
|---|---|---|
Row / RowValue (Entity-Builder) |
prisma/schema/entityBuilder.prisma |
BP indexiert CRM-Contacts als Rows mit entityName="contact"; SQL-Fallback scannt RowValue.textValue. HiveGrid hat dagegen dedizierte Tabellen (Kontakt, Verkaufsfall, …) → BP-Row-Modell ist NICHT 1:1, nur Pattern-Vorlage |
AICostEvent |
prisma/schema/ai.prisma |
Append-only Cost-Log für Embedding-Calls (capability embedding) — Such-Embedding-Kosten landen hier. 1:1 nutzbar als Querschnitt |
Outbox-Modell |
prisma/schema/outbox.prisma |
Generische Outbox-Tabelle, von Dispatcher gelesen. Als-Vorlage für search_outbox (Spec Block H) |
QueueFailedJob |
prisma/schema/queue.prisma |
DLQ-Spiegel für fehlgeschlagene Jobs — deckt Spec Block C „Provider-Failure → retrying/failed" indirekt (BullMQ-Retry + DLQ) |
pgvector vec_*-Tabellen |
via PgvectorAdapter Raw-SQL (kein Prisma-Modell) |
Vektor-Speicher. HiveGrid-Spec will embedding direkt auf SearchIndexEntry → hier weicht HiveGrid vom BP-Layout ab |
Fazit Daten-Layer: Die drei Kern-Modelle der Spec (SearchIndexEntry, RecentSearch, EmbeddingProviderJob) sind komplett neu zu bauen. Die pgvector-Extension (Migration vorhanden) und das Cost-Event-Modell sind die einzigen direkt nutzbaren DB-Bausteine.
Lücken / komplett neu zu bauen
SearchIndexEntryPrisma-Modell + Migration (Spec Block A) — zentrale polymorphe Cross-Entity-Index-Tabelle mittsvector_de(Generated Column, deutsche FTS-Config),embedding vector(1024),permission_subjectJSONB,embedding_status-Enum,entity_type-Enum, GIN-Index (FTS), HNSW/IVFFlat-Index (Cosine), Unique(tenant_id, entity_type, entity_id), RLS. Existiert nicht in BP.- Postgres-FTS-Pfad (Spec Block C/M056) —
tsvector/tsquerymit deutscher Konfiguration, Stemming, Umlaut-Normalisierung, Trigram-Index für Fuzzy-Name-Match. BP nutzt Meilisearch + SQL-ILIKE — keintsvector-FTS vorhanden. - Hybrid-Fusion (RRF) (Spec Block C) — Reciprocal-Rank-Fusion / gewichtetes Score-Merging FTS↔Semantik (Default 70/30), plus Boosts (
last_activity_at, exakter Title-Match, User-eigene Entitäten). BP hat nur einen einseitigen semantischen Rank-Merge (retrieve.ts), keine FTS↔Vektor-Fusion. Neu. RecentSearchPrisma-Modell + Service (Spec Block G) — pro User letzte 50 Queries,applied_filtersJSONB,clicked_entity_*, Retention (50 / 90 Tage), Privacy (privat pro User, DSGVO-Export, Hard-Delete bei Account-Löschung). Existiert nicht.- Saved-Searches (M058-Plan: bis 5 pro User; Spec: Phase 2) — User speichert Query+Filter unter Namen. Modell + UI neu. (Spec markiert als Phase 2, M058-Plan zieht es nach Phase 1 — Klärungs-/Scope-Punkt.)
EmbeddingProviderJobPrisma-Modell (Spec Block A) — Worker-Queue-State (provider, status, attempts,last_error_text, completed_at). BP nutzt stattdessen BullMQ-Job-State + DLQ; ein persistiertes Job-Modell mit Klartext-Error fehlt → neu (oder bewusst durch BullMQ+QueueFailedJobersetzen).- SearchAdapter-Voll-Interface (Spec Block D) — BP-
SearchIndexSchemadeckt nurbuildSearchableContent-Äquivalent (Feld-Whitelist). Es fehlen:buildPermissionSubject(entity) → JSONB,getRouteForEntity(entity) → string,getDisplayMetadata(entity) → {icon, badge},filterVisibleForUser(entries, perms) → entries[],triggers-Liste. Erweiterung/Neu. - Permission-aware Server-Side-Filter (Spec Block F / M057) —
filterVisibleForUserpro Adapter, server-side vor Ausgabe (kein Client-Hiding), Trefferanzahl-Konsistenz (nur erlaubte Treffer), Field-Level-Redact für Snippets (M057-Erfolgskriterium: Volume-Wert im Snippet redacten). BP hat nur tenant-scoped Filter +sanitizeDocument(Index-Zeit-Whitelist), kein per-User-Permission-Filter zur Query-Zeit und kein Snippet-Field-Redact. Neu (Kern von M057). indexedEntities-Registry für HiveGrid (INTEGRATION-CONTRACTS §8,packages/db/src/search/indexed-entities.ts) — Mapentity → {table, searchable[], permission}. BP-ALL_SEARCH_INDEXESist die Vorlage, aber auf ToolCTRL-Entitäten gemünzt. Neu mit HiveGrid-Entitäten (contact, company, lead, deal, project, order, form_submission, user, file, task).- Domain-Adapter pro HiveGrid-Modul (Spec Block D, M001/M042-M046 abhängig) — je Adapter für Kontakt/Firma/Lead (M01), Verkaufsfall (M03), Projekt/Auftrag (M04), Form-Submission (M05), User/Mitarbeiter (M14), File (M23), Task (M26). Komplett neu (jeweils im Ziel-Modul zu bauen).
- Such-UI in
packages/ui-hivegrid(Spec Block E, M058 + M015) — Cmd+K-Modal + Vollbild-Such-View (/{tenant}/search) als HiveGrid-VM-Component (View-Model vom Loader, keine Server-Imports im UI-Paket, i18n-Keys, Subframe-Adapter). Das BP-CommandPalette ist nur Vorlage (anderer UI-Stack/-Paket). Neu inkl. Filter-Chips, Tastatur-Navigation, Snippet-Highlight, Recent-Searches-Anzeige, Sortier-Optionen, Cursor-Pagination, Mobile-Vollbild. - Routen + Wiring —
/{tenant}/searchRoute, globaler Cmd+K-Layout-Mount, Header-Such-Anker, Mobile-Tab/Header (INTEGRATION-CONTRACTS §3/§13/§14), Feature-Flag (M006), Audit (M001/M021: Suchanfrage + Trefferanzahl loggen — Spec Block F). Neu. search_outbox+ Trigger/Outbox-Wiring (Spec Block H) — HiveGrid-eigenes Outbox-Modell + Re-Index-Trigger auf den Quell-Tabellen. BP-Outbox-Router/Dispatcher ist Vorlage; das HiveGrid-Modell + Verdrahtung an die dedizierten Tabellen ist neu.- Query-Embedding-Cache (Spec Block C) — SHA256-Key, 24h-TTL. Primitive (
createCacheStore) vorhanden, die Such-spezifische Cache-Schicht ist neu. - Klartext-Hinweise (Spec Block I / M002) — alle 7 Fehler-/Hinweis-Texte (keine Treffer, Permission-Reduktion, Embedding-Down-Banner, <2 Zeichen, Indexierungs-Verzögerung, Re-Index-Lauf, Server-Fehler) als i18n-Keys im M002-Catalog. Neu.
Empfohlenes Vorgehen
Phase 0 — Architektur-Entscheid (blockierend, vor M056-Bau):
- Klären: Postgres-FTS (Spec/Plan) vs. Meilisearch (BP). Memory + M056-Plan sagen FTS („kein Extra-Service"). Empfehlung: bei FTS bleiben, BP-Meilisearch-Pakete als Pattern-Vorlage (Outbox, Schema-Registry, Tenant-Scope, Fallback) statt als Engine nutzen.
- Klären:
embeddingdirekt aufSearchIndexEntry(Spec) vs. separate pgvector-vec_*-Tabelle (BP). Spec-Variante reduziert Joins, weicht aber vonPgvectorAdapterab → Adapter wird Vorlage für die Cosine-Query. - Klären: Saved-Searches Phase 1 (M058-Plan) vs. Phase 2 (Spec).
- Klären:
EmbeddingProviderJob-Tabelle (Spec) vs. BullMQ-Job-State +QueueFailedJob(BP-Konvention).
M056 — Such-Index (zuerst BP-Bausteine übernehmen):
pgvector-Migration aus BP übernehmen (1:1).SearchIndexEntry-Modell + Migration neu bauen (tsvector_deGenerated Column, GIN-Index, Cosine-Index, RLS).EmbeddingProvider-Pakete (@toolctrl/ai/embeddingsfactory/scaleway/aleph-alpha/embed-and-upsert/chunking/retrieve) 1:1 übernehmen (EU-1024-dim ist exakter Match).- Outbox-Publisher + Search-Indexer-Worker + RAG-Indexer-Worker als Vorlage übernehmen, Ziel-Sink auf
SearchIndexEntry(FTS-Felder synchron, Embedding async) umbauen;EmbeddingProviderJob-State + Retry-Backoff ergänzen. indexedEntities-Registry (HiveGrid) + erste Adapter (Kontakt/Firma/Lead aus M042-M046, da Vorbedingung) bauen.- FTS-Pfad (
tsquerydeutsch + Trigram) + Hybrid-Fusion (RRF + Boosts) neu — kein BP-Äquivalent.
M057 — Permission-aware (auf M056 + M004):
7. permission_subject-Befüllung pro Adapter (buildPermissionSubject).
8. filterVisibleForUser server-side im Query-Pfad (vor Ausgabe), withTenantScope-Pattern aus BP als Tenant-Basis, Permission-Filter darauf neu.
9. Field-Level-Snippet-Redact (M057-Erfolgskriterium Volume-Feld) — neu; BP sanitizeDocument deckt nur Index-Zeit, nicht Query-Zeit-Redact.
10. Trefferanzahl-Konsistenz + Klartext-Hinweis „weitere Treffer nicht sichtbar" (Schwellwert klären — offener Spec-Punkt).
11. Audit-Wiring (Suchanfrage + Trefferanzahl, M001/M021).
M058 — UI + Saved-Searches (auf M056/M057 + M015):
12. Cmd+K-Modal in packages/ui-hivegrid neu (BP-CommandPalette als Interaktions-Vorlage: Keyboard-Listener, Lazy-Dialog, Esc/Focus). Nicht kbar (existiert nicht in BP).
13. Vollbild-Such-View /{tenant}/search (Filter-Sidebar, Sortier, Cursor-Pagination, URL-State) — neu.
14. RecentSearch-Modell + Service (Retention, Privacy, DSGVO) — neu.
15. Saved-Searches (falls Phase 1) — neu.
16. Query-Embedding-Cache (createCacheStore, 24h-TTL) — Primitive aus BP, Schicht neu.
17. Klartext-Catalog (Spec Block I) + i18n-Keys; Feature-Flag (M006); Header-Anker + Mobile (BP-SearchButton als Stil-Vorlage, neu via Subframe).
Reihenfolge-Prinzip: Erst die EU-Embedding-Pipeline + pgvector + Outbox/Worker-Muster aus der BP übernehmen (höchster 1:1-Anteil), dann den FTS-Pfad, das SearchIndexEntry-Modell, die Fusion und den Permission-Query-Filter neu bauen (kein BP-Äquivalent), zuletzt die HiveGrid-UI (BP-CommandPalette nur als Vorlage).