Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P11a.md
T

16 KiB
Raw Blame History

R-P11a · P11 Globale Suche (Meilisearch, Cmd+K)

⚠️ KI→MCP-Pivot (AD-26): HiveGrid hostet kein Embedding/LLM/RAG. Das reale Search-Schema enthält weder pgvector-/Embedding-Felder noch einen EmbeddingProviderJob. v1/v2 bleiben reine Meilisearch-Keyword-Suche mit SQL-Fallback; externe KI-Clients docken später über VR-MCP/VD-MCP an und bringen ihre Inferenz selbst mit.

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 Done

🎨 design-nachzug: offen — D-DASH bleibt das finale Design-Delta. Nach AD-28 ist es kein Done-Blocker: R-P11a wird mit einer Interim-UI aus ~/ui fertiggestellt.

Scope-Schnitt 2026-07-12 (verbindlich): Die globale Suche ist in v1 ausschließlich eine Spotlight-Suche. Desktop öffnet sie per Cmd+K/Ctrl+K oder Header-Suchsymbol als Modal; Mobile öffnet dasselbe Sucherlebnis über das Header-Suchsymbol als viewportfüllendes Overlay. Eine nutzerseitige /search-Seite, Direktlinks auf Suchzustände sowie erweiterte Vollseiten-Filter/Paginierung/Sortierung entfallen. /search/api bleibt ausschließlich als geschützter, tenant-scoped Resource-Endpunkt. R-P11b nutzt die bestehenden Such-/Index-Contracts weiter und ist von diesem UI-Schnitt nicht betroffen.

🟢 Kein Pivot-Sonderfall (P11 ist nicht Teil der projekt-zentrischen Kern-Kette). Der Such-Index greift auf den Projekt-Kern zu: frühere Typen deal | project | order sind im Pivot-Modell EIN Projekt-Entity-Typ (Pipeline-Typ = View). AD-26 entfernt pgvector, Embeddings und eigene semantische Suche vollständig.

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; der Scope-Schnitt 2026-07-12 ändert dessen Contracts nicht)
  • 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 als globale Spotlight-Suche mit Debounce, gruppierten Treffern, Match-Highlight und RecentSearches. Desktop nutzt ein Modal per Cmd+K/Ctrl+K oder Header-Suchsymbol; Mobile ein viewportfüllendes Overlay über das Header-Suchsymbol. 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
Spotlight-Suche [global, keine nutzerseitige Route] Desktop-Modal bzw. mobiles viewportfüllendes Overlay; 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; Loading-, Empty- und Fehlerzustand; bei leerer Eingabe RecentSearches + Tipps; Treffer öffnen direkt ihre Ziel-Route

Definition of Done

  • Meilisearch-Keyword-Suche permission-aware über SearchAdapter (Modul-Registrierung: Kontakt/Firma/Lead/Projekt/File/Task/User); kein pgvector/Embedding nach AD-26
  • Entity-Mutationen aktualisieren den Index über Outbox-Index-Pattern; SearchIndexEntry + RecentSearch befüllt (5–10 s Index-Latenz mit Klartext-Hinweis)
  • Spotlight-Interim-UI aus ~/ui: Desktop per Cmd+K/Ctrl+K und Header-Suchsymbol als Modal, Mobile per Header-Suchsymbol viewportfüllend; debounced und nach Entity-Typ gruppiert, Match-Highlight, Loading-/Empty-/Fehlerzustände, vollständige Tastatur-Navigation inkl. Cmd/Ctrl+Enter, RecentSearches; keine nutzerseitige /search-Seite
  • 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

Historischer Nachweis: Die beiden Einträge vom 2026-07-01 bleiben als damaliger Implementierungsstand erhalten. Aussagen zur nutzerseitigen /search-Route, zum Wechsel in eine Vollbild-Such-View und zu „keine selbst machbaren Dev-Punkte offen" sind durch den verbindlichen Scope-Schnitt vom 2026-07-12 überholt.

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.

2026-07-12 · Scope-Neuschnitt und Wiederaufnahme R-P11a (5/6 DoD = ~83 % done; selbst machbar offen: 1 Punkt).

  • Die nutzerseitige /search-Vollseite entfällt. /search/api bleibt geschützter Resource-Endpunkt für die Spotlight-Suche.
  • Offen ist die vollständige AD-28-Interim-UI: echte Typ-Gruppierung, Loading-/Empty-/Fehlerzustände, vollständige Tastatursteuerung inklusive neuem Tab sowie der mobile Header-Trigger mit viewportfüllendem Overlay.
  • D-DASH bleibt als design-nachzug offen, blockiert den Abschluss mit Interim-UI aber nicht.
  • R-P11b bleibt funktional und dependency-seitig unverändert.

2026-07-12 · Abschluss R-P11a (6/6 DoD = 100 % done; selbst machbar offen: 0 Punkte).

Proof:

  • Feature-Commit f9f98c57e (feat(search): replace full-page search with Spotlight UI) liegt konfliktfrei auf dem aktuellen origin/main.
  • Die nutzerseitige /search-Route ist entfernt. Die globale Suche läuft ausschließlich im bestehenden Spotlight-/Command-Palette-Slot; /search/api bleibt der geschützte, tenant-scoped Resource-Endpunkt.
  • Desktop öffnet das Modal per Cmd+K, Ctrl+K oder Header-Trigger. Mobile nutzt einen eigenen Header-Trigger und ein viewportfüllendes Overlay. Debounce, Typfilter, gruppierte Treffer, Match-Highlight, relative Aktivität, 20→50-Nachladen, RecentSearches und sämtliche Klartextzustände sind integriert.
  • Normales Enter öffnet im selben Tab, Cmd/Ctrl+Enter in einem neuen Tab, Esc schließt und gibt den Fokus an den sichtbaren Header-Trigger zurück. Stale Requests werden über Request-IDs verworfen.
  • GET bleibt read-only. Der POST schreibt erst nach einer bestätigten Trefferauswahl, validiert CSRF, Tenant, Modul, search.use, Auswahl und aktuellen Entity-Zugriff und dedupliziert den privaten Verlauf unter einem Transaktions-Lock auf maximal 50 Einträge mit 90 Tagen Aufbewahrung.
  • AD-28 ist durch einen reinen VM-Builder, packages/ui-mock-Interim-Artefakt, Hot-Swap-Drill und reale Desktop-/Mobile-Pixel-Baselines abgedeckt. Das finale D-DASH-Delta bleibt separat als design-nachzug offen und ist kein Done-Blocker.

Verifikation:

  • pnpm typecheck, pnpm lint, pnpm test (694 Testdateien bestanden, 8 übersprungen; 4.339 Tests bestanden, 46 übersprungen)
  • pnpm verify:i18n, pnpm verify:route-inventory, pnpm verify:sidebar-routes, pnpm verify:cross-cutting-models, pnpm verify:ci-baseline, pnpm verify:source-health, pnpm verify:test-coverage
  • pnpm --filter @hivegrid/search test (84 Tests), pnpm --filter @hivegrid/view-models test (347 Tests), Worker-Suchindex (16 Tests)
  • Spotlight Unit/API/Backend-/Shell-Fokus: 56 Tests; Component-Pixel-Baseline: 2/2; echter lokaler E2E-Smoke mit geschütztem Endpoint: Desktop + Mobile 2/2; pnpm test:hot-swap; pnpm verify:ui-visual (30 bestanden, 3 Beobachtungen, 0 Fehler)
  • prisma validate und prisma migrate status gegen die aktuelle lokale Datenbank grün.
  • Nach dem konfliktfreien Rebase auf origin/main wurden Typecheck, Lint, die 56 fokussierten Tests und beide Component-Pixel-Baselines erneut grün ausgeführt.

RLS-Stand:

  • RLS Teil A für den Search-Leseweg und RecentSearch ist abgeschlossen: Tenant-GUC-fähiger Zugriff, Policy-/Grant-/Inverse-Artefakt und Contract-/Mock-Tests sind vorhanden.
  • Die physische FORCE RLS-Aktivierung bleibt Teil B des organisationsweiten Cutovers und ist kein zusätzlicher R-P11a-DoD-Punkt. Vor ihrer Aktivierung muss der TenantUser-Lifecycle auf withTenantRLS() umgestellt und ein Restricted-Role-Integrationstest für SearchIndexEntry und RecentSearch gefahren werden. Diese Notiz behauptet ausdrücklich nicht, dass FORCE RLS bereits produktiv aktiv ist.

Technische Bausteine

  • Entities (eigene prisma/schema/search.prisma): SearchIndexEntry mit tenantId, entityType/entityId, title/subtitle/bodyText, routePath/sourceIndex, permissionSubject (String), lastIndexedAt, Archive-/Demo-Flags und metadata; RecentSearch mit tenantId/userId, queryText, appliedFilters, resultCount. Keine tsvector-, pgvector-, Embedding- oder Provider-Job-Felder (AD-26). Modul-.prismas referenzieren polymorph über Scalars (AD-21).
  • RLS Teil A für SearchIndexEntry/RecentSearch (AD-1): Tenant-GUC-fähiger Zugriff plus Policy-/Grant-/Inverse-Artefakt. FORCE-RLS-Aktivierung ist Teil B und derzeit nicht aktiv. Permission-Filter laufen zusätzlich serverseitig via Permission-Key und aktuelle Source-of-Truth-Revalidierung.
  • 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) — 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
  • designer-briefs/P11-suche-dashboard.md (Cmd+K BESPOKE; kein Pivot-Sonderfall, aber Projekt-Kern-Hinweis)

Abgrenzung zum breiteren M24-Produktscope

R-P11a ist mit seinen sieben registrierten Typen und sechs DoD-Punkten abgeschlossen. Folgende historische M24-Wünsche sind nicht still als umgesetzt markiert und brauchen vor Arbeit ein eigenes Ticket beziehungsweise einen Change Request:

  • typisierter form_submission-SearchAdapter,
  • Datenschutzentscheidung und ggf. Audit für Live-Queries,
  • UI zum manuellen Löschen einzelner beziehungsweise aller RecentSearches.

Diese offenen Produkterweiterungen sind keine zusätzlichen, nachträglich erfundenen R-P11a-DoD-Punkte.

Definition of Done — Audit-Nachtrag 2026-07-19

  • Hot-Swap-Drill (AGENTS.md DoD 20) für den Spotlight-Interim-Screen — beim Audit am 2026-07-19 fehlte der Spotlight-Eintrag in scripts/verify-ui-hot-swap.ts (das ui-mock-Artefakt createSpotlightInterimFixturePage existierte, wurde aber vom Drill nicht verifiziert). Nachgezogen auf fix/r-p11-audit-restwork: Drill prüft jetzt Registry-Swap, Modul-/HTML-Artefakte, Portal-Slot shell.commandPalette und search.use-Gate. Proof: Commit 9f98f3f8c, pnpm test:hot-swap grün.

Umsetzungs-Notiz (Audit 2026-07-19)

2026-07-19 · Stand-Audit R-P11a (korrigiert 6/7 → nach Nachzug 7/7 DoD = 100 % done). Drei-Quellen-Abgleich (Doc/Plane/Code): alle 6 Original-DoD-Punkte im Code belegt (Registry packages/search/src/indexed-entities.ts, Outbox searchIndexProjection.server.ts + Worker search-indexer.ts, Spotlight-UI ohne /search-Route, Permission-Filter mit RLS-Revalidierung, Modul-Gate, Permissions inkl. Seed). RLS-Check nach Cutover 14.07. unauffällig (Worker via runWorkerPayloadWithRlsContext, RecentSearch-Writes in withTenantRLS). Einziger Befund: fehlender Hot-Swap-Drill-Eintrag (siehe Audit-Nachtrag oben), am selben Tag geschlossen.

Dev-Nachzug

  • AD-28-Interim-UI für die Spotlight-Suche fertigstellen und gegen Interim-Baseline verifizieren
  • Finales D-DASH-Delta später als design-nachzug integrieren und Visual-Baseline neu setzen
  • Scope-Schnitt in den verbindlichen Planungs-, Design- und Runtime-Dokumenten nachgezogen
  • Spotlight-Interim-Screen im Hot-Swap-Drill verifiziert (Audit-Nachtrag 2026-07-19)