Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P11a.md
T
2026-07-08 16:15:37 +02:00

8.9 KiB
Raw Blame History

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

  • Meilisearch-Keyword-Suche permission-aware über SearchAdapter (Modul-Registrierung: Kontakt/Firma/Lead/Projekt/File/Task/User); pgvector/Hybrid → v2 → ruht (AD-26)
  • Entity-Mutationen aktualisieren den Index über Outbox-Index-Pattern; SearchIndexEntry + RecentSearch befüllt (5–10 s Index-Latenz mit Klartext-Hinweis)
  • Cmd+K-Modal (global Hotkey, debounced, gruppierte Treffer, Match-Highlight, Tastatur-Navigation, RecentSearches) + Wechsel in Vollbild-Such-View mit Filtern
  • Server-side Permission-Filter (nie durchsickern; Trefferanzahl = erlaubte Treffer; Klartext „weitere Treffer, die du nicht siehst")
  • Konnektor tenantHasModule('search') (Suche gated)
  • 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-.prismas 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
  • Plane-Ticket R-P11a aktualisiert