# Boilerplate-Abgleich: M24 — Globale Suche > Faktischer Abgleich der HiveGrid-Detail-Spec (M24) gegen die Boilerplate. > Boilerplate-Wurzel (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate` > Spec-Quelle: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M24-globale-suche.md` > Alle 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:** 1. **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 kein `tsvector`-FTS und keine Hybrid-Fusion. 2. **Daten-Modell:** Die Spec verlangt eine **zentrale `SearchIndexEntry`-Tabelle** (polymorpher Cross-Entity-Index mit `tsvector_de`, `embedding vector(1024)`, `permission_subject` JSONB), plus `RecentSearch` und `EmbeddingProviderJob`. **Keines** dieser Prisma-Modelle existiert in der Boilerplate (verifiziert via Grep über `prisma/schema/*.prisma`). Die Boilerplate hält den Such-Index extern in Meilisearch + die Vektoren in `vec_*`-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..`; `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..` (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__`-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 `Row`s 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 1. **`SearchIndexEntry` Prisma-Modell + Migration** (Spec Block A) — zentrale polymorphe Cross-Entity-Index-Tabelle mit `tsvector_de` (Generated Column, deutsche FTS-Config), `embedding vector(1024)`, `permission_subject` JSONB, `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.** 2. **Postgres-FTS-Pfad** (Spec Block C/M056) — `tsvector`/`tsquery` mit deutscher Konfiguration, Stemming, Umlaut-Normalisierung, **Trigram-Index** für Fuzzy-Name-Match. BP nutzt Meilisearch + SQL-ILIKE — **kein `tsvector`-FTS vorhanden**. 3. **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.** 4. **`RecentSearch` Prisma-Modell + Service** (Spec Block G) — pro User letzte 50 Queries, `applied_filters` JSONB, `clicked_entity_*`, Retention (50 / 90 Tage), Privacy (privat pro User, DSGVO-Export, Hard-Delete bei Account-Löschung). **Existiert nicht.** 5. **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.) 6. **`EmbeddingProviderJob` Prisma-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+`QueueFailedJob` ersetzen). 7. **SearchAdapter-Voll-Interface** (Spec Block D) — BP-`SearchIndexSchema` deckt nur `buildSearchableContent`-Äquivalent (Feld-Whitelist). Es fehlen: `buildPermissionSubject(entity) → JSONB`, `getRouteForEntity(entity) → string`, `getDisplayMetadata(entity) → {icon, badge}`, `filterVisibleForUser(entries, perms) → entries[]`, `triggers`-Liste. **Erweiterung/Neu.** 8. **Permission-aware Server-Side-Filter** (Spec Block F / M057) — `filterVisibleForUser` pro 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). 9. **`indexedEntities`-Registry für HiveGrid** (INTEGRATION-CONTRACTS §8, `packages/db/src/search/indexed-entities.ts`) — Map `entity → {table, searchable[], permission}`. BP-`ALL_SEARCH_INDEXES` ist 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). 10. **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). 11. **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. 12. **Routen + Wiring** — `/{tenant}/search` Route, 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.** 13. **`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. 14. **Query-Embedding-Cache** (Spec Block C) — SHA256-Key, 24h-TTL. Primitive (`createCacheStore`) vorhanden, die Such-spezifische Cache-Schicht ist neu. 15. **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: `embedding` **direkt auf `SearchIndexEntry`** (Spec) vs. separate pgvector-`vec_*`-Tabelle (BP). Spec-Variante reduziert Joins, weicht aber von `PgvectorAdapter` ab → 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):** 1. `pgvector`-Migration aus BP übernehmen (1:1). 2. `SearchIndexEntry`-Modell + Migration **neu** bauen (`tsvector_de` Generated Column, GIN-Index, Cosine-Index, RLS). 3. `EmbeddingProvider`-Pakete (`@toolctrl/ai/embeddings` factory/scaleway/aleph-alpha/embed-and-upsert/chunking/retrieve) **1:1** übernehmen (EU-1024-dim ist exakter Match). 4. 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. 5. `indexedEntities`-Registry (HiveGrid) + erste Adapter (Kontakt/Firma/Lead aus M042-M046, da Vorbedingung) bauen. 6. FTS-Pfad (`tsquery` deutsch + 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).