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

12 KiB
Raw Blame History

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

  • AuditEvent mit SHA-256-Hash-Kette (vorhanden+getestet; Auto-Audit-Prisma-Middleware bewusst aufgeschoben, manueller auditEvent-Pfad ist der unterstützte Weg — s.u.)
  • 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)
  • packages/i18n + verify:i18n-CI-Gate (Resolution User→Tenant→DE, Build-Lint Hard-Strings)
  • tenantHasFlag() + tenantHasModule()-Muster (Cache; in R-P1c am Skeleton angedockt)
  • 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
  • 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).