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

216 lines
16 KiB
Markdown
Raw 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]]):** 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
- [x] **Meilisearch-Keyword-Suche permission-aware** über **SearchAdapter** (Modul-Registrierung: Kontakt/Firma/Lead/**Projekt**/File/Task/User); kein pgvector/Embedding nach 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] **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
- [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
> **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-`.prisma`s 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
- [x] **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
- [x] 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
- [x] Scope-Schnitt in den verbindlichen Planungs-, Design- und Runtime-Dokumenten nachgezogen
- [x] Spotlight-Interim-Screen im Hot-Swap-Drill verifiziert (Audit-Nachtrag 2026-07-19)