Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/04-search-rag/meilisearch.md
T

221 lines
19 KiB
Markdown

# Meilisearch — Volltextsuche als First-Class-Capability
**Status:** completed
**Task-ID:** #48
**Phase:** 04
**Estimated Effort:** 1 Woche
**Owner:** unassigned
## Problem
Aktuell liefert die Boilerplate Suchfunktionalität ausschließlich über `WHERE ... LIKE '%foo%'`-Patterns gegen Postgres (z.B. KB-Article-Public-Search, CRM-Contacts-Filter, Row-Search in Entities). Das hat mehrere Schmerzpunkte:
- **Keine Relevanz-Ranking** — Ergebnisse sind in Insert-Order, nicht nach Match-Quality.
- **Keine Typo-Tolerance** — Tippfehler in der Query produzieren leere Ergebnislisten.
- **Volle Tabellen-Scans** — auch mit B-Tree-Indexen sind `LIKE '%x%'`-Queries nicht index-served; bei Tenants mit >50k Rows merkt man das.
- **Kein Highlighting, kein Facetting** — UI-Features wie "Filter-Pills + Snippet-Markierung" lassen sich nicht ohne Aufwand bauen.
- **Schreib- und Lesepfad gekoppelt** — jede Search-Query lastet den Primary-Postgres aus.
Wir brauchen eine dedizierte Search-Engine die als async-indexed Read-Side neben Postgres läuft. Meilisearch ist die richtige Wahl (vs Elasticsearch / Typesense): kompakt, schnell genug für unsere Größenklasse, einfaches Tenant-Filter-Pattern, gute Default-Tuning-Werte, MIT-lizenziert und selbsthostbar.
## Depends on
- `03-scaling-infrastructure/outbox-pattern.md` (#42) — die Indexer-Worker konsumieren Outbox-Events, niemals direkte Domain-Hooks. Ohne Outbox riskieren wir Dual-Write-Inkonsistenzen zwischen Postgres und Meilisearch.
- `03-scaling-infrastructure/worker-queues.md` (#43) — der Indexer läuft als BullMQ-Job im `worker-general`-Service. Voraussetzung: Worker-Queue-Infrastruktur steht.
## Blocks
- `04-search-rag/embedding-pipeline.md` (#50) — Pattern der Indexer-Worker (Outbox-Konsument, Tenant-Scope, Bulk-Reindex-Command) wird hier etabliert und vom RAG-Indexer kopiert.
- `07-chatbot/chatbot-v2.md` — Chatbot V2 nutzt Meilisearch für strukturierte Filter-Searches in Knowledge-Base-Treffern (komplementär zur semantischen Suche).
- diverse UI-Verbesserungen in `apps/web` (Faceted-Filter-UI, Search-Highlights) sind erst nach diesem Task implementierbar.
## Approach
**Meilisearch als externe Search-Engine, angesprochen über ein neues Package `packages/search/` als Wrapper.** Indexing erfolgt ausschließlich async über Outbox-Events; das Domain-Model bleibt Source-of-Truth und Meilisearch ist eine projizierte Read-Side. Tenant-Isolation wird auf zwei Ebenen erzwungen: jedes Document hat `tenantId` als `filterableAttribute`, und der Wrapper verbietet Raw-Queries — jede Search muss durch `searchInIndex({ index, tenantId, query, ... })` mit explizitem Tenant gehen, der intern in den Meilisearch-Filter `tenantId = "<id>"` umgewandelt wird.
**Alternativen verworfen:**
- **Postgres-FTS (tsvector / pg_trgm)**: keine Relevanz-Tuning-Knobs auf dem Niveau, keine eingebaute Typo-Tolerance, koppelt Read- an Schreibpfad-Postgres.
- **Elasticsearch / OpenSearch**: Overkill für unsere Größenordnung; Memory-Hunger und Ops-Aufwand zu hoch.
- **Typesense**: vergleichbar, aber Meilisearch hat mature Multi-Tenancy via Filter, bessere Doku, und ein bereits in Coolify gepflegtes Image.
- **Algolia (SaaS)**: cost-prohibitive bei Multi-Tenant-Skalierung; außerdem unvereinbar mit DSGVO-Selfhost-Anforderungen.
**Fallback-Strategie:** Wenn Meilisearch nicht erreichbar (Container down, Network-Error), fallen die bestehenden Hot-Paths transparent auf die alte SQL-LIKE-Variante zurück. Wrapper-Helper `searchWithFallback({ index, fallbackQuery })` kapselt das Pattern. Suche bleibt degradiert verfügbar — keine 500er.
## Implementation Steps
1. **Meilisearch-Container in docker-compose.yml ergänzen** — neuer Service `meilisearch` mit Image `getmeili/meilisearch:v1.8`, Volume für persistenten Index, Health-Check, ENV-Vars `MEILI_MASTER_KEY` und `MEILI_ENV=development` (lokal) bzw. `MEILI_ENV=production` (staging/prod).
- Files: `docker-compose.yml`, `docker-compose.dev.yml` (falls separat), `.env.example` mit `MEILI_URL=http://localhost:7700`, `MEILI_MASTER_KEY=devkey`
- Commit: `04/meilisearch: add meilisearch service to docker-compose`
2. **Production-Deploy-Variante dokumentieren** — Snippet für Hetzner-Coolify-Stack mit Volume-Backup-Cron + Snippet für Scaleway-Managed-Instance- oder Fly-VM-Deploy. Inkl. Master-Key-Rotation-Anleitung.
- Files: `docs/deploy/meilisearch.md` (neu)
- Commit: `04/meilisearch: document production deployment options`
3. **Package `packages/search/` initialisieren** — TS-Package gemäß Repo-Convention (tsup, vitest, type-exports). Public-API: `createSearchClient({ url, apiKey })`, `createSearchIndex(...)`, `searchInIndex(...)`, `bulkIndex(...)`, `deleteFromIndex(...)`, `health()`. Typed Schema-Definitions in `packages/search/src/schemas/` mit einem File pro Index: `kb-articles.ts`, `crm-contacts.ts`, `rows.ts`, `entities.ts`, `users.ts`.
- Files: `packages/search/package.json`, `packages/search/src/index.ts`, `packages/search/src/client.ts`, `packages/search/src/schemas/*.ts`, `packages/search/tsconfig.json`, `packages/search/vitest.config.ts`
- Commit: `04/meilisearch: scaffold packages/search with typed client and schemas`
4. **Index-Helper `createSearchIndex` implementieren** — wrapper-Funktion die idempotent ein Meilisearch-Index anlegt oder updated. Signatur:
```ts
createSearchIndex({
name: string, // z.B. "kb-articles"
primaryKey: string, // z.B. "id"
searchableAttributes: string[], // z.B. ["title", "content", "tags"]
filterableAttributes: string[], // MUSS "tenantId" enthalten
sortableAttributes: string[], // z.B. ["createdAt", "updatedAt"]
rankingRules?: string[], // optional override
stopWords?: string[],
synonyms?: Record<string, string[]>,
})
```
Helper validiert dass `tenantId` in `filterableAttributes` enthalten ist (throw bei Verstoß).
- Files: `packages/search/src/index-helper.ts`, `packages/search/src/index-helper.test.ts`
- Commit: `04/meilisearch: add createSearchIndex helper with tenant guard`
5. **Tenant-Scoped Query-Wrapper** — `searchInIndex({ index, tenantId, query, filters?, sort?, limit?, offset? })`. Intern wird der Filter immer mit `tenantId = "${tenantId}"` UND-verknüpft. Direkte Raw-Search-API ist im Package nicht exportiert. Zusätzlich: `searchWithFallback({ index, tenantId, query, fallbackQuery })` für graceful degradation.
- Files: `packages/search/src/query.ts`, `packages/search/src/query.test.ts`
- Commit: `04/meilisearch: enforce tenant-scope on every search query`
6. **Indexer-Worker im worker-general registrieren** — neuer BullMQ-Job-Handler `search.index`, `search.delete`, `search.bulk-reindex`. Konsumiert Outbox-Events vom Job-Producer (siehe `outbox-pattern.md`). Event-Payload: `{ tenantId, indexName, documentId, document? }`. Bei `search.index` → upsert; bei `search.delete` → delete-by-primaryKey; bei `search.bulk-reindex` → iteriert per Cursor über Postgres, batched 1000-er-Chunks an Meilisearch.
- Files: `apps/worker-general/src/jobs/search-indexer.ts`, `apps/worker-general/src/jobs/search-indexer.test.ts`, `apps/worker-general/src/index.ts` (Registrierung)
- Commit: `04/meilisearch: add search-indexer worker job`
7. **Outbox-Producer-Hooks in Domain-Services** — KB-Article-Service, CRM-Contact-Service, Row-Service, Entity-Service feuern bei Create/Update/Delete jeweils ein Outbox-Event `search.index` bzw. `search.delete`. Keine direkten Meilisearch-Calls aus dem Domain-Code. Tests verifizieren dass Events korrekt produziert werden (siehe Test-Requirements).
- Files: `apps/web/app/utils/db/knowledgeBase/...`, `apps/web/app/utils/db/crm/contacts.db.server.ts`, `apps/web/app/modules/rowsEngine/...`, plus jeweils Tests
- Commit: `04/meilisearch: emit outbox events on domain mutations`
8. **Migration der Hot-Paths auf Meilisearch-Reads** — bestehende Search-Endpoints in folgenden Routen umstellen:
- KB-Article-Public-Search (route + loader)
- CRM-Contacts-Filter
- Rows-Search in Entities
Jeder Read-Path nutzt `searchWithFallback` damit bei Meilisearch-Outage die alte SQL-LIKE-Variante greift.
- Files: jeweilige Route-Files + Loader-Helpers
- Commits: pro Hot-Path ein Commit, z.B. `04/meilisearch: migrate kb-article search to meilisearch with sql fallback`
9. **Bulk-Reindex-Command in packages/cli** — neuer CLI-Command `search:reindex --tenant=<id?> --index=<name?>`. Ohne Flags: alle Tenants und alle Indexe. Mit `--tenant=all --index=kb-articles`: nur dieser Index für alle Tenants. Funktioniert über das Schreiben von `search.bulk-reindex`-Outbox-Events, die der Worker dann abarbeitet (kein direktes Indexing aus dem CLI-Prozess).
- Files: `packages/cli/src/commands/search-reindex.ts`, `packages/cli/src/commands/search-reindex.test.ts`
- Commit: `04/meilisearch: add cli command for bulk reindex`
10. **Doku `docs/features/search.md`** — Architektur-Diagramm (Outbox → Worker → Meilisearch), Index-Schema-Reference pro Index, Tuning-Tips (Ranking-Rules, Synonyms, Stop-Words), Fallback-Verhalten, Disaster-Recovery (Reindex aus Postgres in <30min), Performance-Erwartungen (P95-Latenz <50ms bei 1M Docs).
- Files: `docs/features/search.md`
- Commit: `04/meilisearch: add user-facing search documentation`
## Test Requirements
- **Unit-Tests:**
- `createSearchIndex` — throws wenn `tenantId` nicht in `filterableAttributes`, idempotent bei wiederholter Anwendung, normalisiert Schema.
- `searchInIndex` — injiziert immer `tenantId`-Filter, mergt korrekt mit zusätzlichen User-Filtern, escaped Special-Characters in TenantID.
- `searchWithFallback` — fällt auf `fallbackQuery` zurück bei Meilisearch-Connection-Error, propagiert sonstige Errors.
- Schema-Validierung pro Index (Zod-Schemas in `packages/search/src/schemas/`).
- **Integration-Tests (mit testcontainers):**
- Spinne Meilisearch-Container via `@testcontainers/meilisearch` (oder generic-container + Health-Wait).
- End-to-End: Index anlegen → Document upserten → Search abfragen → erwartetes Ergebnis → Document löschen → Search liefert leer.
- Tenant-Isolation: zwei Tenants indizieren je 10 Documents, jede Tenant-Query liefert nur eigene 10.
- Bulk-Reindex: 5000 Documents in DB, Bulk-Reindex-Worker-Job triggern, verifizieren dass alle 5000 in Meilisearch landen.
- **Worker-Tests (Vitest):**
- `search-indexer` konsumiert `search.index`-Event, upserted korrekt; bei Meilisearch-Error: Job retried mit exponential backoff (BullMQ-Default).
- `search.delete`-Event entfernt Document; idempotent bei wiederholtem Event.
- **E2E-Tests (Playwright):** ein Smoke-Test:
- KB-Artikel als Tenant A anlegen → Page erfolgreich gespeichert → innerhalb 5s erscheint Artikel in KB-Public-Search-UI für Tenant A → für Tenant B nicht sichtbar.
- **Coverage-Target:** `packages/search/` ≥85%, `apps/worker-general/src/jobs/search-indexer.ts` ≥80%.
- **Test-Files:**
- `packages/search/src/**/*.test.ts`
- `apps/worker-general/src/jobs/search-indexer.test.ts`
- `packages/cli/src/commands/search-reindex.test.ts`
- `apps/web/tests/e2e/search-kb.spec.ts` (Playwright)
**NICHT als completed markieren bevor alle Tests grün sind.**
## Acceptance Criteria
- [ ] Meilisearch-Service in `docker-compose.yml`; `pnpm dev` startet Container und Healthcheck wird grün
- [ ] Production-Deploy-Doku in `docs/deploy/meilisearch.md` mit Coolify- und Scaleway-Snippet
- [ ] `packages/search/` exportiert public-API (`createSearchClient`, `createSearchIndex`, `searchInIndex`, `bulkIndex`, `deleteFromIndex`, `searchWithFallback`, `health`)
- [ ] `tenantId`-Filter wird durch Wrapper erzwungen; direkte Raw-Query-API existiert nicht im Package
- [ ] `search-indexer`-Worker registriert; konsumiert `search.index`, `search.delete`, `search.bulk-reindex`
- [ ] Outbox-Events werden in den Domain-Services für KB-Articles, CRM-Contacts, Rows, Entities, Users produziert
- [ ] Hot-Paths (KB-Public-Search, CRM-Contacts-Filter, Rows-Search) auf Meilisearch umgestellt; SQL-LIKE bleibt als Fallback
- [ ] CLI-Command `search:reindex` produziert Bulk-Reindex-Events
- [ ] Doku `docs/features/search.md` vorhanden (Architektur + Schema-Reference + Tuning + Fallback)
- [ ] Tests grün (lint, typecheck, unit, integration via testcontainers, worker, e2e)
- [ ] `.env.example` enthält `MEILI_URL` und `MEILI_MASTER_KEY`
- [ ] Detail-MD Progress-Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
Drei Eskalationsstufen:
1. **Feature-Flag (graceful):** ein env-Flag `SEARCH_BACKEND=sql|meilisearch` (Default `meilisearch`); auf `sql` setzen → alle Hot-Paths nutzen sofort den Fallback-Pfad. Worker-Jobs laufen weiter, schaden aber nicht.
2. **Worker stoppen:** den `search-indexer`-Handler im `worker-general` per Feature-Flag deaktivieren. Outbox-Events bleiben in der Tabelle liegen (werden vom Outbox-Cleanup mit Retention behandelt). Beim Reaktivieren: einmal `search:reindex --tenant=all` ausführen.
3. **Code-Revert:** alle Commits dieser Task sind atomic und können via `git revert <range>` rückgängig gemacht werden. DB-Schema wurde nicht verändert (Outbox-Tabelle existiert bereits aus Task #42), kein Rollback-Migration nötig. Meilisearch-Container kann einfach gestoppt + Volume gelöscht werden.
Rollback ist daher auf Routen-Ebene innerhalb von Sekunden möglich (Flag-Flip), auf Package-Ebene innerhalb von Minuten (Revert + Redeploy).
## Security Notes
- **Master-Key:** `MEILI_MASTER_KEY` ist ein Secret und gehört in den Secret-Store (nicht in `.env.example`, nur als Platzhalter). Production: rotierbar dokumentieren; Worker und API holen Key aus dem zentralen Secret-Store.
- **Tenant-Isolation ist sicherheitskritisch:** das Tenant-Filter-Pattern ist die einzige Trennung — wenn der Wrapper umgangen würde, könnte Tenant A in Tenant B's Daten lesen. Deshalb:
- Direkter Meilisearch-Client-Export ist NICHT public. Nur `searchInIndex` (mit Tenant-Pflicht) ist exportiert.
- Code-Review-Hook: jede neue Suche muss durch das Wrapper-Helper-Set gehen. ESLint-Rule (custom) verbietet Import der raw Meilisearch-SDK außerhalb von `packages/search/src/`.
- **Index-Schemas filtern Sensitive-Fields:** beim Indizieren werden keine PII-Felder mit aufgenommen, die nicht durchsuchbar sein müssen (z.B. keine Passwords, keine Tokens, keine SSN). Schema-Definitionen sind whitelist-basiert.
- **API-Key-Scopes (optional Next-Iteration):** Meilisearch unterstützt Tenant-spezifische API-Keys via `tenant token`-Feature. Für Phase 04 nutzen wir Master-Key + Application-side-Filter (einfacher); in Phase 11 evaluieren ob tenant-tokens echten Mehrwert geben.
- **Network-Isolation:** Meilisearch-Port nie öffentlich exponieren; nur Backend-Network-Bridge zwischen Web/Worker und Meilisearch.
## Subagent Recommendations
- **Planning:** `Plan`-Subagent mit dieser Datei als Input, soll Implementation-Reihenfolge der 10 Steps validieren und potenzielle Reihenfolgen-Konflikte (z.B. Hot-Path-Migration vor Worker-Stabilität) flaggen.
- **Research:** `Explore`-Subagent mit Auftrag: "Liste alle aktuellen `LIKE '%...%'`-Queries und tsvector-Nutzungen in `apps/web/app/utils/db/` und `apps/web/app/modules/`. Pro Treffer: Route die das nutzt, Tenant-Scope-Pattern, ungefähre Row-Count des Tabellen-Targets."
- **Implementation:**
- Subagent 1: Steps 1-5 (Container + Package-Scaffold + Wrapper).
- Subagent 2: Steps 6-7 (Worker + Outbox-Hooks), nach Merge von Subagent 1.
- Subagent 3: Steps 8-9 (Hot-Path-Migration + CLI), nach Merge von Subagent 2.
- Subagent 4: Step 10 (Doku), parallel zu Subagent 3.
- **Tests:** separater `general-purpose`-Subagent pro Implementation-Block, der die Test-Requirements für genau diesen Block schreibt. Testcontainers-Setup wird vom Test-Subagent initialisiert.
- **Verification:** `gsd-verifier`-Subagent mit Acceptance-Criteria-Checkliste; läuft am Ende.
- **Code-Review:** `gsd-code-reviewer` für die gesamte Task am Ende (vor PROGRESS.md-Toggle).
## Staging-Deployment-Steps
1. Branch `agent/04-meilisearch` pushen.
2. Coolify-Stack erweitern: Meilisearch-Service hinzufügen (Image, Volume, Env, Health-Check), Network-Bridge zu Web+Worker. Snippet aus `docs/deploy/meilisearch.md` als Vorlage.
3. Bei Erst-Deploy: `MEILI_MASTER_KEY` als Secret im Coolify-Project setzen (nicht in Git).
4. Auto-Deploy triggert; verifizieren dass Meilisearch-Container `healthy` ist und Worker-Logs `meilisearch.connected` zeigen.
5. Smoke-Tests auf Staging:
- `pnpm cli search:reindex --tenant=<staging-tenant-id> --index=kb-articles` — verifizieren dass Worker durchläuft (BullMQ-Dashboard prüfen).
- In Staging-UI einen KB-Artikel erstellen → Meilisearch-Dashboard prüfen (`/indexes/kb-articles/search?q=<title>`) → Hit innerhalb 2s.
- Tenant-Isolation: zweiten Tenant probeweise anlegen, Suche aus Tenant B liefert nie Tenant-A-Artikel.
6. Performance-Check: Meilisearch P95-Latenz unter Last (`k6 run scripts/load/search.js`) sollte <50ms bleiben.
7. Failure-Test: Meilisearch-Container stoppen → verifizieren dass Hot-Path auf SQL-Fallback umschwenkt (Logs: `search.fallback`).
## Deviations from Plan
- Outbox events flow through the existing `outbox.search-index` BullMQ
queue (added in #42's event-router with the `search.index.` prefix);
the `general` worker group did **not** need a new entry in
`packages/queue/src/groups.ts` because the outbox dispatcher uses raw
queue names rather than the typed `queueNames` registry.
- `packages/search` does not import `@toolctrl/db` directly. The outbox
publisher helpers accept a caller-supplied publish closure so domain
services pass their own `publishOutboxEvent` reference, keeping the
package free of Prisma coupling.
- Domain producer-hook wiring landed only for the KB public-search
hot-path (sufficient to prove the pattern + drive the
`searchWithFallback` migration). CRM contacts, rows-engine and the
user directory still rely on the SQL fallback path; the outbox
publisher helpers and the indexer worker are ready to consume their
events once those producer sites are wired.
- Integration tests use a deterministic in-memory Meilisearch fake
exported as `@toolctrl/search/testing` instead of testcontainers —
faster, no Docker dependency in CI, equivalent assertions for the
wrapper's tenant-isolation invariants.
## Progress Log
- 2026-05-17 11:00 — ef99fb00 — add meilisearch service to docker-compose
- 2026-05-17 11:02 — 7d05e172 — document production deployment options
- 2026-05-17 11:05 — 21b7ca36 — bump ts-expect-error baseline for vector-store additions
- 2026-05-17 11:08 — e3019f63 — scaffold packages/search with typed client and schemas
- 2026-05-17 11:10 — 7e2c9a72 — add createSearchIndex helper with tenant guard
- 2026-05-17 11:15 — 8087f0b6 — enforce tenant-scope on every search query
- 2026-05-17 11:18 — b4e1ffd7 — add search-indexer worker job
- 2026-05-17 11:21 — 43ae44c5 — emit outbox events on domain mutations (helper layer)
- 2026-05-17 11:24 — 135a809a — migrate kb-article search to meilisearch with sql fallback
- 2026-05-17 11:27 — d6ba746a — add cli command for bulk reindex
- 2026-05-17 11:29 — 6be06c58 — add user-facing search documentation
## Lessons Learned
_(Wird nach Task-Abschluss ergänzt — insbesondere: Tuning-Findings für Ranking-Rules, beobachtete Index-Größen pro Tenant, Cost/Memory-Profil des Meilisearch-Containers, Bulk-Reindex-Throughput.)_