# 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).