Files
2026-07-08 16:15:37 +02:00

107 lines
8.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# R-P11a · P11 Globale Suche (Meilisearch, Cmd+K)
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Die pgvector-`embedding`-Spalte und der `EmbeddingProviderJob` **ruhen** (RAG entfällt — HiveGrid hostet kein Embedding/LLM mehr, sondern wird MCP-Server, [[VR-MCP]]). v1 bleibt **unverändert reine Meilisearch-Keyword-Suche**; die früher als „v2-Andock-Halter" geführten Embedding-Teile werden in v2 **nicht** befüllt.
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | P11 — Globale Suche & Dashboard |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · 2026-07-03 → 2026-07-04 · Gate W4 |
| **Status** | On Hold |
> 🟢 **Kein Pivot-Sonderfall** (P11 ist nicht Teil der projekt-zentrischen Kern-Kette). Aber: Der Such-Index greift auf den **`Projekt`-Kern** zu — in der M24-Spec stehen `deal | project | order` als Typen; im Pivot-Modell ist das **EIN `Projekt`-Entity-Typ** (Pipeline-Typ = View, kein separater Index-Typ je Pipeline). v1 = **Meilisearch-Keyword-Suche**; ~~pgvector/Hybrid → v2 (AD-5 sequenziert) — embedding-Spalte/EmbeddingProviderJob sind nur Andock-Halter.~~ → **pgvector/Hybrid ruht ([[AD-26]]: RAG entfällt); embedding-Spalte/EmbeddingProviderJob bleiben ungenutzt.**
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P9b` (Kern-Kette abgeschlossen — Projekt/Sub-Areas indexierbar), `AK-INFRA2` (Meilisearch zentral bereitgestellt)
- **Blocks:** `R-P11b` (Dashboard danach)
- **Sequenz (Raffaels Kern-Kette):** nach abgeschlossener Kern-Kette (P6–P9). P11/P12/P13 folgen sequenziell.
- **Läuft parallel zu:** Akeshans Module W4 (`AK-P20`/`AK-P21` Billing/DSGVO u.a.). Schema-Trennung nach **AD-21**.
> **Zulieferung aus R-P9b (Stand 2026-07-01, serverseitig umgesetzt):** Die Projekt-/Auftrags-Kern-Kette ist
> serverseitig indexierbar: Plantafel (`ScheduleEntry`/`ScheduleConflict`), Abnahme
> (`AbnahmeProtokoll`/`AbnahmeSignatur`) und Offline-Sync (`OfflineSyncMutation`) stehen
> im typisierten Prisma-Schema, mit RLS/Tenant-Registry und Service-Routen bereit. Commit:
> `6b6ca1fd9`. R-P9b bleibt wegen `D-PLAN`/`D-ABN`/`D-P9` screen-blockiert auf On Hold;
> für den R-P11a-Backend-Ausbau sind die relevanten Contracts nutzbar.
## Was wir bauen
Eine **permission-aware Keyword-Suche** über alle Entitäten via **Meilisearch** (SearchAdapter pro Modul, Outbox-Index-Updates), bedienbar per **Cmd+K-Modal** (global, debounced, gruppierte Treffer, Match-Highlight, RecentSearches) und als **Vollbild-Such-View** mit Filtern. Server-side Permission-Filter sorgt dafür, dass nie Treffer durchsickern.
## Benötigte Screens (Backend bedient — Design liefert `D-DASH`-Paket)
| Screen [Route] | Kern-Inhalt |
|---|---|
| Cmd+K-Such-Modal [global] | Auto-Fokus + Live-Suche (300 ms debounce); Treffer **gruppiert nach Entity-Typ** (Icon/Titel/Subtitle/Match-Highlight/relative letzte Aktivität); Entity-Typ-Filter-Chips (Multi-Select); Tastatur-Navigation (↑↓/Enter/Cmd+Enter/Esc) + Shortcut-Anzeige; Leer-Zustand: **RecentSearches** + Tipps; „Alle {n} Treffer zeigen" → Vollbild |
| Vollbild-Such-View [`/search`] | Such-Feld (URL-Param), volle Trefferliste (cursor-paginiert 50/Page) mit Metadaten; **Filter-Sidebar** (Entity-Typ/Erstellt-Range/Verantwortlicher/Tags/modul-spezifisch + Archiviert-Toggle); Trefferanzahl-Klartext; Sortierung (Relevanz/Letzte Aktivität/Erstellt) |
## Definition of Done
- [x] **Meilisearch-Keyword-Suche permission-aware** über **SearchAdapter** (Modul-Registrierung: Kontakt/Firma/Lead/**Projekt**/File/Task/User); ~~pgvector/Hybrid → v2~~ → ruht ([[AD-26]])
- [x] Entity-Mutationen aktualisieren den Index über **Outbox-Index-Pattern**; `SearchIndexEntry` + `RecentSearch` befüllt (5–10 s Index-Latenz mit Klartext-Hinweis)
- [x] **Cmd+K-Modal** (global Hotkey, debounced, gruppierte Treffer, Match-Highlight, Tastatur-Navigation, RecentSearches) + Wechsel in **Vollbild-Such-View** mit Filtern
- [x] **Server-side Permission-Filter** (nie durchsickern; Trefferanzahl = erlaubte Treffer; Klartext „weitere Treffer, die du nicht siehst")
- [x] Konnektor `tenantHasModule('search')` (Suche gated)
- [x] Permissions: `search.use`/`search.admin` (Suche leichtgewichtig — Sichtbarkeit über Modul-Permissions)
## Umsetzungs-Notiz
**2026-07-01 · Teilumsetzung R-P11a (3/6 DoD = 50 % done; selbst machbar offen: 3 Punkte).**
Proof:
- Neues Search-Datenmodell `SearchIndexEntry`/`RecentSearch` in `prisma/schema/search.prisma`, RLS-Artefakt `prisma/rls/search-isolation.sql`, Tenant-Snapshot-Registry nachgezogen.
- `search` als Entitlement/Modul-Key inklusive `tenantHasModule('search')`, Sidebar-Gate, `search.use`/`search.admin` in DefaultPermissions, Seed, Role-Display und Übersetzungen.
- `@hivegrid/search` um `projects`-Index, Projekt-Registry und Worker-Bulk-Pager erweitert; `indexedEntities` enthält Kontakt/Firma/Lead/Projekt/File/Task/User.
- App-Route `/search` + Resource-Route `/search/api` + Cmd+K-Live-Suche (300 ms debounce) integriert; serverseitiger Permission-Filter mit `read_all`/`read_own`-Owner-Filtern, Unit-Test gegen Treffer-Leak ergänzt.
Verifikation:
- `pnpm typecheck`
- `pnpm lint`
- `pnpm verify:route-inventory`
- `pnpm verify:cross-cutting-models`
- `pnpm --filter @hivegrid/search test`
- `pnpm --filter @hivegrid/entitlements test`
- `pnpm --filter @hivegrid/web test -- app/services/search/globalSearch.server.test.ts app/components/ui/commandPalettes/CommandPalette.test.tsx app/components/core/roles/roleDisplay.test.ts app/utils/services/rolesAndPermissionsService.role-matrix.test.ts`
- `pnpm --filter @hivegrid/worker typecheck`
- `pnpm --filter @hivegrid/cli test -- src/commands/tenant/models.test.ts`
**2026-07-01 · Dev-Fertigstellung R-P11a (6/6 selbst machbare DoD = 100 % done; Ticket bleibt screen-blockiert auf On Hold).**
Proof:
- Zentraler Search-Projektionshelper `apps/web/app/services/search/searchIndexProjection.server.ts` spiegelt `SearchIndexEntry` und publiziert `search.index.*`-Outbox-Events fuer Kontakt/Firma/Lead/Projekt/File/Task/User.
- Live-Mutations verdrahtet: CRM-Kontakte inkl. Primaer-E-Mail/-Telefon, Leads inkl. Status/Bulk/Konvertierung, Projekte inkl. Stage/Undo/Konvertierung, Files inkl. Upload/Meta/Archiv/Delete, Tasks inkl. Status/Assignment/Archiv/Delete, TenantUser-Deaktivierung/Reaktivierung.
- `crm-contacts`-Index unterscheidet `entityType` (`contact`/`company`/`lead`); Meilisearch-Abfragen nutzen tenant- und owner-scoped Filter fuer Own-Permissions. SQL-Fallback bleibt als robuste Rueckfallebene.
- Cmd+K erweitert um Entity-Filter-Chips, RecentSearches im Leerlauf, Match-Highlight und gefilterten Wechsel in `/search`; Vollbildsuche zeigt ebenfalls Highlighting.
Verifikation:
- `pnpm --filter @hivegrid/web typecheck`
- `pnpm --filter @hivegrid/worker typecheck`
- `pnpm lint`
- `pnpm verify:route-inventory`
- `pnpm verify:cross-cutting-models`
- `pnpm --filter @hivegrid/search test`
- `pnpm --filter @hivegrid/web test -- app/utils/services/tenantUserLifecycle.server.test.ts app/services/search/globalSearch.server.test.ts app/components/ui/commandPalettes/CommandPalette.test.tsx`
- `pnpm --filter @hivegrid/worker test -- src/jobs/search-indexer.test.ts`
Offen:
- Keine selbst machbaren Dev-Punkte offen.
- Screen-/UI-Abnahme gegen `D-DASH` (Cmd+K + Vollbild-Such-View) offen; Ticket bleibt deshalb in Plane auf `Blocked / On Hold`, nicht `Done`.
## Technische Bausteine
- **Entities** (eigene `prisma/schema/search.prisma`): `SearchIndexEntry` (entity_type/id, title, body_text, tsvector_de, **~~embedding [pgvector → v2-Andock-Halter]~~ → ruht, ungenutzt ([[AD-26]])**, permission_subject, is_archived), `RecentSearch` (query_text/applied_filters/result_count), ~~`EmbeddingProviderJob` (async, Inhalt v2)~~ → ruht ([[AD-26]]). Modul-`.prisma`s nur über polymorphe Referenz (AD-21).
- **RLS** auf SearchIndexEntry/RecentSearch (AD-1); Permission-Filter zusätzlich server-seitig via `permission_subject` vor Meilisearch-Query.
- **Outbox-Pattern:** Entity-Mutation → Outbox-Event → Index-Job (SearchAdapter pro Modul) → Meilisearch upsert/delete.
- **SearchAdapter-Interface** (INTEGRATION-CONTRACTS §8) je Modul registriert.
- **Konnektor** `tenantHasModule('search')` gated.
- `is_demo_data`-Flag respektiert (Demo-Treffer bei Echt-Start-Bereinigung entfernt).
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 6: Suche & Dashboard** (SearchIndexEntry/RecentSearch/EmbeddingProviderJob) — Hinweis: ein `Projekt`-Entity-Typ statt deal/project/order
- `REQUIREMENTS.md` → `REQ-suche-datenmodell`, `REQ-suche-hybrid` (Meilisearch/SearchAdapter), `REQ-suche-ui` (Phase 11)
- `ROADMAP.md` → Phase 11 · `PHASE-SOURCES.md` → P11
- `designer-briefs/P11-suche-dashboard.md` (Cmd+K BESPOKE; kein Pivot-Sonderfall, aber Projekt-Kern-Hinweis)
- `_bmad-output/specs/M24-globale-suche.md` (⚠ Entity-Typen deal/project/order → im Pivot EIN Projekt-Typ; pgvector → v2)
## Dev-Nachzug (nach Davids `D-DASH`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [x] Plane-Ticket `R-P11a` aktualisiert