Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,90 @@
# Phase 04 — Search + RAG
**Dauer:** 3.5 Wochen
**Tasks:** 3
**Ziel:** Volltextsuche und semantische Suche als first-class Capabilities der Boilerplate etablieren. Meilisearch als Full-Text-Search-Engine (FTS) für Hot-Paths, Vector-Store mit Adapter-Pattern (pgvector als Default, Qdrant optional) für semantische Suche, plus generische Embedding-Pipeline die Outbox-Events konsumiert und beide Stores aktuell hält. Damit wird die Foundation für Chatbot V2 (Phase 07) geschaffen — RAG ohne diese Pipeline ist nicht realisierbar.
## Warum diese Phase nach Phase 03
- **Outbox-Pattern** (Task #42 aus Phase 03) ist Pflicht-Voraussetzung. Alle drei Tasks dieser Phase laufen async — sie konsumieren Outbox-Events (`search.index`, `search.delete`, `rag.index`) und reflektieren Änderungen aus dem Domain-Model in die externen Stores. Ohne Outbox riskieren wir Dual-Write-Probleme und Index-Drift zwischen Postgres und Meilisearch/Vector-Store.
- **Worker-Queues** (Task #43 aus Phase 03) liefern den `worker-general`-Service, in dem die Indexer-Jobs laufen.
- **prismaWrite-Client / Read-Write-Split** (Task #41 aus Phase 03) wird vom pgvector-Adapter genutzt, um Writes konsistent auf den Primary zu schicken.
Ohne diese Foundation würden wir Indexing synchron im Request-Path machen müssen — das produziert messbare Latenz, blockiert Tenants gegenseitig und bricht bei Service-Ausfall den Schreibpfad.
## Warum diese Phase vor Phase 07
Chatbot V2 (`07-chatbot/chatbot-v2.md`) braucht eine funktionierende RAG-Pipeline:
- Retrieval von tenant-scoped Wissensbasis-Snippets via semantischer Suche
- Embedding-Provider-Abstraktion damit man pro Tenant zwischen OpenAI/Scaleway/Aleph-Alpha wählen kann
- Vector-Store mit konsistentem Tenant-Scoping
Phase 04 liefert exakt diese drei Bausteine und blockt deshalb Chatbot V2 hart.
## Task-Reihenfolge
| Reihenfolge | Task-ID | Datei | Parallelisierbar mit |
|---|---|---|---|
| 1 | #48 | `meilisearch.md` | #49 (unabhängige Pakete + unabhängige Container) |
| 2 | #49 | `vector-store.md` | #48 |
| 3 | #50 | `embedding-pipeline.md` | — (braucht #48 für Search-Worker-Pattern und #49 für Vector-Upsert) |
## Dependency-Graph (intern)
```
Phase 03 (Outbox #42, Worker-Queues #43, prismaWrite #41)
│
┌──────────────────────┴──────────────────────┐
▼ ▼
#48 meilisearch ──────────────┐ #49 vector-store
(FTS, Indexer-Worker, │ (Adapter-Interface, pgvector,
Tenant-Filter, Bulk-Reindex) │ Qdrant, Backup-Strategy)
│ │
└──────────┬────────────┘
▼
#50 embedding-pipeline
(Provider-Abstraktion,
Chunking, RAG-Worker,
Retrieval-Helper, CLI-Backfill)
│
▼
Phase 07 Chatbot V2
```
`#48` und `#49` sind echte Parallelkandidaten — sie touchen unterschiedliche Packages (`packages/search/` vs `packages/vector-store/`), unterschiedliche Container (Meilisearch vs Qdrant/pgvector-Extension) und unterschiedliche Worker-Job-Typen. Zwei Subagents können sie parallel implementieren.
`#50` braucht beide. Insbesondere die im Vector-Store etablierten Helpers (`embedAndUpsert`, `semanticSearch`) sind die Bausteine, auf denen der RAG-Worker und der `retrieveRelevantContext`-Helper aufbauen.
## Phase Done-Definition
Diese Phase ist `completed` wenn:
- [ ] Alle 3 Tasks `completed` in `PROGRESS.md`
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` global grün
- [ ] `packages/search/` und `packages/vector-store/` exportieren stabile öffentliche APIs (in jeweils einer `index.ts` + Type-Exporten)
- [ ] `worker-general` registriert mindestens die Job-Handler `search.index`, `search.delete`, `search.bulk-reindex`, `rag.index`
- [ ] Outbox-Producer-Hooks für KB-Articles, CRM-Contacts, Rows, CRM-Notes feuern Events bei Create/Update/Delete
- [ ] `.env.example` enthält neue Keys: `MEILI_URL`, `MEILI_MASTER_KEY`, `QDRANT_URL` (optional), `AI_EMBEDDING_PROVIDER`, `AI_EMBEDDING_MODEL`, `AI_EMBEDDING_DIMENSIONS`
- [ ] Doku-Files vorhanden: `docs/features/search.md`, `docs/features/vector-store.md`, `docs/features/rag.md`
- [ ] Staging-Deployment auf `agent/phase-04-final` deployed: Meilisearch- und Qdrant-Container laufen, Bulk-Reindex einmal erfolgreich ausgeführt
- [ ] Integration-Test-Flow: KB-Artikel anlegen → Outbox-Event → Worker → Meilisearch-Hit innerhalb 2s und Vector-Store-Hit (Semantic-Query findet Artikel) innerhalb 5s
- [ ] Tenant-Isolation-Test: Tenant A kann via Search/Semantic nie Dokumente von Tenant B sehen (positiv- und negativ-Test)
- [ ] `gsd-code-reviewer`-Subagent hat alle Phase-04-Commits reviewed; Findings adressiert
- [ ] Phase-Summary in dieser README.md ergänzt (siehe unten)
## Phase Summary
_(Wird nach Abschluss der Phase vom ausführenden Agent ergänzt.)_
### Lessons Learned
_(Wird nach Abschluss ergänzt — insbesondere: Latenz-Erfahrungen mit Meilisearch vs Postgres-FTS, pgvector-HNSW-Tuning-Findings, Embedding-Provider-Cost-Vergleich, Chunking-Strategie-Findings.)_
## Verweise
- Detail-MD-Template: `../DETAIL-MD-TEMPLATE.md`
- Agent-Workflow: `../AGENT-INSTRUCTIONS.md`
- Execution-Order: `../00-execution-order.md`
- Live-Status: `../PROGRESS.md`
- Vorgänger-Phase: `../03-scaling-infrastructure/README.md`
- Nachfolger-Phase (geblockt): `../07-chatbot/chatbot-v2.md`