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

152 lines
12 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-P1b · P1 Service-Kerne (Audit/notify/i18n/Flags) + Konnektor-Muster
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | P1 — Fundament & Walking-Skeleton |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-18 · Gate W1 |
| **Status** | Done |
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P1a` (EU-Sterilisation + Contracts)
- **Blocks:** `R-P2a`, `AK-P3`, **alle Module** (Konnektor `tenantHasModule()` ist Pflicht-Gate jeder Folge-Phase)
- **Läuft parallel zu:** `AK-INFRA1`/`AK-INFRA2` (Ops, kein Code-Konflikt). **P1 = Raffael SOLO.**
- **Konflikt-Risiko:** keines — Service-Kerne sind Querschnitt (eigene Packages/Middleware). Schema-Berührung nur an Cross-Cutting (`AuditEntry`, `Notification`) — eigene `prisma/schema/*.prisma`, db push auf Branch (AD-21).
## Was wir bauen
Die **Querschnittsdienste**, auf denen jedes Folge-Modul aufsetzt: `logActivity()` (append-only Activity-Stream), Search-Registry, Subframe-Adapter, Mass-Action-Schutz, **Audit-Event mit SHA-256-Hash-Kette** (Prisma-Middleware, default-on), `notify()` mit Kanal-Abstraktion (In-App/Email; Push-Stub bis v2), `packages/i18n` (Resolution User → Tenant → DE, Build-Lint gegen Hard-Strings) und die **Feature-Flag-Engine mit Entitlement-Gate** (`tenantHasFlag()` + `tenantHasModule()` — das Konnektor-Prinzip). Liefert das Konnektor-Muster exemplarisch am Skeleton (wird in R-P1c angedockt).
## Benötigte Screens (Backend bedient — Design liefert `D-D0a`/`D-D0b`)
Kein fachlicher Screen — reine Service-Kerne (Backend). Die Bedien-Oberflächen dieser Dienste kommen in **P3** (`AK-P3`: Audit-Viewer + Notification-Center + Sprach-Settings). David liefert hier nur die Archetypen-Baseline (`D-D0a`/`D-D0b`), inkl. Activity-Stream-Komponente (A3) für spätere Detail-Views.
## Definition of Done
- [x] `AuditEvent` mit **SHA-256-Hash-Kette** *(vorhanden+getestet; Auto-Audit-Prisma-Middleware bewusst aufgeschoben, manueller `auditEvent`-Pfad ist der unterstützte Weg — s.u.)*
- [x] `notify()` Kanal-Abstraktion (In-App / Email; Push-Stub bis v2) *(Regression 14.–17.07. unter FORCE RLS worker-seitig — behoben, s. §Fix-Notiz 2026-07-17)*
- [x] `packages/i18n` + `verify:i18n`-CI-Gate (Resolution User→Tenant→DE, Build-Lint Hard-Strings)
- [x] `tenantHasFlag()` + `tenantHasModule()`-Muster (Cache; in R-P1c am Skeleton angedockt)
- [x] `logActivity()` (polymorph `subject_type/id`, `actor_kind`) + Search-Registry + Subframe-Adapter + Mass-Action-Schutz aufrufbar
## Technische Bausteine
- **Entities** (eigene `prisma/schema/*.prisma`): `AuditEntry` (append-only, `before/after_diff`, `summary_text` DE, Hash-Kette), `Notification`/`NotificationPreference`/`NotificationDevice` (Push-Kanal ruht v1), `Activity` (Cross-Cutting, polymorph `subject_type+subject_id`, `actor_kind` user/system/automation/ki_agent). i18n = **keine Tabelle** (JSON-Files + Felder `User.language`/`Tenant.default_language`).
- **Konnektor** `tenantHasModule()`: prüft `SubscriptionFeature.code` im Abo des Tenants (Brücke Billing↔Feature-Gate); Redis-Cache.
- **RLS** auf `AuditEntry`/`Notification` (tenant-bezogen, AD-1).
- `is_demo_data`-Flag-Konvention für seedbare Definitions-Tabellen.
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 2: Querschnitt** (AuditEntry/Notification/NotificationPreference/Device) + **Cross-Cutting** (Activity, Konnektor via SubscriptionFeature.code)
- `REQUIREMENTS.md` → `REQ-audit-datenmodell`, `REQ-notification-datenmodell`, `REQ-i18n-architektur`, `REQ-feature-flags-system`, `REQ-integration-activity-wiring`/`-audit-wiring`/`-notification-wiring`
- `ROADMAP.md` → Phase 1 · Milestones: (M001/M003/M006/M011 + M005/M007)
- `designer-briefs/P01-fundament-walking-skeleton.md` (Service-Kerne)
## Dev-Nachzug (nach Davids `D-D0a`/`D-D0b`-Delta)
- [ ] Activity-Stream-/Konnektor-Wiring an Davids Komponenten-Entscheidungen angepasst
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [x] Plane-Ticket `R-P1b` aktualisiert
## Umsetzungsstand (Claude, 2026-06-17 — noch nicht final abgenommen)
> Branch `p1-fundament-rp1abc`. Den finalen DoD-Abhaken/Done macht Raffael.
**Ausgangslage:** Die meisten Querschnitt-Service-Kerne lagen schon in der Boilerplate vor und wurden als aufrufbar verifiziert:
- **Audit + SHA-256-Hash-Kette:** `packages/db/audit-hash.ts` (`computeAuditHash`/`verifyAuditChain`/`canonicalizeAuditPayload`) + `audit-events.server.ts` (`createAuditEvent`/`publishAuditEventViaOutbox`), getestet (`audit-hash.test.ts`, `audit-events.server.test.ts`).
- **`notify()`** Kanal-Abstraktion (In-App/Email, Push-Stub) in `packages/foundation/notifications.ts`.
- **i18n + `verify:i18n`-Gate:** `packages/i18n` + `pnpm run verify:i18n` (i18n-check + hardcoded-strings + eslint auf ui-Paketen), grün.
- **`logActivity()`** (`@hivegrid/activity`), **Search-Registry** (`indexedEntities`/`listIndexedEntities`, `@hivegrid/search`), **Subframe-Adapter** (`defineAdapter`, `@hivegrid/ui-app`), **Mass-Action-Schutz** (`previewMassAction`/`assertMassActionAllowed`, `@hivegrid/foundation`) — alle exportiert/callable.
**Neu gebaut = der Konnektor (die eigentliche Lücke):**
- `apps/web/app/utils/connector/tenantConnector.server.ts` mit dem kanonischen Pflicht-Gate:
- **`tenantHasModule({tenantId, userId, moduleKey})`** → bool. Brücke Billing↔Feature-Gate: nutzt `resolveTenantProductAccess` (Abo/`SubscriptionFeature` via `getActiveTenantSubscriptions`, Blueprint, Tenant-Override, Rollen-Permission). Modul-Entscheidung Connector-seitig gecacht (`cachified`) + `invalidateTenantModuleAccessCache(tenantId)`.
- **`tenantHasFlag({flagKey, tenantId?, userId?})`** → bool. Delegiert an den v2-`evaluateFlagForContext` (bringt eigenen Eval-Cache mit).
- 6 Unit-Tests (`tenantConnector.server.test.ts`).
- Cache-Backing = App-Cache (`~/utils/cache.server`, LRU heute, per `redisCacheAdapter` Redis-swappbar — Infra-Schalter; die genutzten Resolver `getActiveTenantSubscriptions`/`evaluateFlagForContext` cachen bereits cross-replica).
**Bewusst aufgeschoben (begründet):**
- **Default-on Auto-Audit-Prisma-Middleware:** Die Hash-Kette + explizites `auditEvent`/`createAuditEvent` sind vorhanden und der **richtige** Pfad. Eine auto-Middleware am geteilten Prisma-Client ohne request-scoped Actor-Kontext (AsyncLocalStorage) erzeugt actor-lose Events (schlechter als die expliziten Aufrufe mit vollem Kontext) und ist ohne lokalen DB-Zugriff nicht validierbar. Querschnitt-Tabelle erlaubt explizit „auto via Middleware **oder** manuell auditEvent". → ALS/Auto-Audit als separater Infra-Schritt.
**Proof:** Konnektor 6/6 · Web-Typecheck grün · `verify:i18n` Exit 0 · volle Suite grün (siehe R-P1c-Abschluss).
## Querbezug AK-P3 (dependency-aware, 2026-07-07 — Akeshan)
AK-P3 (DoD 2, Diff-Detail-Drawer) hat die im LOCKED `ENTITY-MODEL.md` §Domäne 2 geforderten Spalten
**`beforeDiff`/`afterDiff` (Json?) + `summaryText` (String?)** additiv an `AuditEvent` (`core.prisma`) ergänzt
(Branch `akeshan/ak-p3-interim-ui`; Owner-Freigabe für die core.prisma-Berührung liegt vor, 2026-07-06):
- **Additiv/nullable** — bestehende Rows/Caller bleiben gültig; `buildAuditEventCreateData` nimmt die Felder
optional entgegen (gleicher Metadata-Sanitizer, Redaction at write time) und der Outbox-Pfad reicht sie durch.
- **Bewusst NICHT im `eventHash`-Digest:** das Chain-Payload-Format ist eingefroren; eine Aufnahme würde
`verifyAuditChain` für alle Bestandszeilen brechen. **Offen bei R-P1b/Raffael:** Diffs in die Hash-Kette
binden (Chain-Format-Versionierung) + flächige Befüllung der Diffs über die Schreibpfade
(Auto-Audit-Middleware, siehe „Bewusst aufgeschoben" oben).
- Konsumenten-Tests grün (audit-events 12/12, worker persist 11/11 + bootstrap 6/6, outbox-e2e).
## Abschluss-Notiz (2026-07-09, Raffael)
**DoD-Stand:** 5/5 DoD = 100 % done.
**Proof:** Die Querschnittsdienste sind laut Umsetzungsnotiz gebaut und verifiziert: Konnektor 6/6, Web-Typecheck grün, `verify:i18n` grün und volle Suite grün. Dieses Ticket ist screen-frei; spätere Activity-/Komponenten-Nachzüge aus David-Designs sind kein Done-Blocker.
**Plane:** Ticket `HIVEGRID-17` auf `Done` verschoben.
## Regressions-Befund 2026-07-16 · notify() unter FORCE RLS (aus AK-P4-Audit, Akeshan)
Beim Staging-Live-Check zu AK-P4b (16.07., `demo-pro-crm`) hat der Task-Reminder-Sweep **keine**
In-App-Benachrichtigung mehr zugestellt, obwohl das `before`-Fenster offen war und sicher ≥1
Stunden-Sweep gelaufen ist (Benachrichtigungszentrale leer).
**Ursache (Code-gelesen, auf Staging noch nicht log-verifiziert):** `notify()`
(`packages/foundation/src/notifications.ts`) macht einen rohen `notificationDelivery.upsert`
mit dem übergebenen Client und bindet **keinen** Tenant-Kontext; die Worker-Aufrufer (z.B.
`runTaskReminderSweepHandler` in `apps/worker/src/handlers.ts`) rufen es bewusst **außerhalb**
von `withTenantRLS()` auf („own RLS story"-Kommentar). Seit dem app-weiten RLS-Cutover
`20260713190000_appwide_rls_cutover` (R-P2b, scharf seit 14.07.) steht `NotificationDelivery`
auf FORCE RLS → der Upsert scheitert an der Policy, der Handler fängt und loggt nur
(`tasks.reminder.notify-failed`), Zustellung entfällt still. **Betroffen ist mutmaßlich jeder
worker-seitige `notify()`-Aufruf**, nicht nur Tasks-Reminder; web-seitige Aufrufer mit
Request-RLS-Kontext sind unauffällig.
**To-do (Owner R-P1b/Raffael, mit R-P2b abzustimmen):**
- Staging-Worker-Logs auf `notify-failed`-Einträge prüfen (Nachweis).
- Fix: `notify()` kontext-bindend machen (Tenant-GUC setzen, analog `withTenantRLS`) **oder**
alle Worker-Aufrufer in den Tenant-RLS-Kontext wrappen; Regressions-Test analog
`rls-task-isolation.integration.test.ts` (notify-Write unter FORCE RLS).
- Diagnose-Fixture liegt bereit: Staging-Task `cmrnw4rbp000101s1cxglkb3d`
(„AK-P4-Audit Testaufgabe", Fälligkeit 17.07.) — nach dem Fix löschen.
Querverweise: Befund-Ursprung `.planning/ticket-docs/AK-P4b.md` (Notiz 16.07. Abend) ·
Cutover `R-P2b`.
## Fix-Notiz 2026-07-17 · notify()-RLS-Regression behoben (Akeshan, aus R-P1a/b/c-Stand-Audit)
**Audit-Befund (17.07.):** DoD-Punkt 2 war real nur teilweise erfüllt (worker-seitig stille
Zustell-Ausfälle, s. Regressions-Befund oben) → korrigierter Stand vor dem Fix: 4/5 DoD = ~80 %.
**Fix (Branch `fix/r-p1b-notify-rls-context`):** Der Worker-Default-Client ist bereits der
RLS-Proxy aus `@hivegrid/db` (`createRlsScopedClient`), der den Tenant-GUC transaktionslokal
bindet, sobald ein `runWithRlsContext`-Kontext aktiv ist — genau das Muster, das
`apps/worker/src/jobs/portal-lifecycle-bootstrap.ts` schon korrekt nutzt. Deshalb wurde **nicht**
`packages/foundation/notifications.ts` umgebaut (bleibt pure, kein Prisma-Import), sondern:
- Neu: `apps/worker/src/notify-rls.ts` → `notifyWithTenantRlsContext(input, client)` wrappt den
`notify()`-Write in `runWithRlsContext({ tenantId: input.tenantId }, …)`.
- Alle 4 kranken Call-Sites in `apps/worker/src/handlers.ts` umgestellt (Task-Reminder-Sweep,
HR-Upload-Reminder-Dispatch + -Eskalation, Email-Domain-Probe); die irreführenden
„own RLS story"-Kommentare korrigiert. `portal-status-mail-store` (übergibt tx aus
`withTenantRLS`) und `portal-lifecycle-bootstrap` (bereits `runWithRlsContext`) waren gesund.
- Regressionstest `apps/worker/src/notify-rls.test.ts`: bildet die FORCE-RLS-Policy
(`hg_NotificationDelivery_insert` WITH CHECK) im Fake-Client nach (AGENTS.md §RLS — Mock ohne
Policy beweist nichts); erster Test dokumentiert den Bug (plain `notify()` ohne Kontext → Reject).
**Proof:** `notify-rls.test.ts` 4/4 + `rls-context.test.ts` 3/3 + `handlers.test.ts` 110/110 grün ·
Worker- + Foundation-Typecheck grün · ESLint grün.
**Offen (Staging-Nachweis, nach Merge+Deploy):** Worker-Logs auf ausbleibende
`tasks.reminder.notify-failed` prüfen; Diagnose-Fixture `cmrnw4rbp000101s1cxglkb3d`
(Tenant `demo-pro-crm`) löschen, sobald die In-App-Notification zugestellt wurde.
**Drift-Korrektur (Stand main, 17.07.):** Der in Plane am 15.07. gemeldete Audit-Diff-Nachzug
(`computeAuditFieldDiff`, Restarbeiten-Wave 2a) ist **nicht auf `main`**; der Branch
`feat/restarbeiten-initiative` wurde verworfen. Die beiden Design-Entscheidungen
(Default-on-Middleware-Wiring, v3-Chain-Format) liegen weiter bei Raffael; DoD-Punkt 1 bleibt in
seiner abgeschwächten Fassung (expliziter `auditEvent`-Pfad) erfüllt.
**Stand nach Fix-Merge:** wieder 5/5 DoD = 100 % done (Staging-Nachweis als offener Nachzug oben).