12 KiB
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 (KonnektortenantHasModule()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) — eigeneprisma/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
AuditEventmit SHA-256-Hash-Kette (vorhanden+getestet; Auto-Audit-Prisma-Middleware bewusst aufgeschoben, manuellerauditEvent-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()(polymorphsubject_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_textDE, Hash-Kette),Notification/NotificationPreference/NotificationDevice(Push-Kanal ruht v1),Activity(Cross-Cutting, polymorphsubject_type+subject_id,actor_kinduser/system/automation/ki_agent). i18n = keine Tabelle (JSON-Files + FelderUser.language/Tenant.default_language). - Konnektor
tenantHasModule(): prüftSubscriptionFeature.codeim 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-wiringROADMAP.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-P1baktualisiert
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) inpackages/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.tsmit dem kanonischen Pflicht-Gate:tenantHasModule({tenantId, userId, moduleKey})→ bool. Brücke Billing↔Feature-Gate: nutztresolveTenantProductAccess(Abo/SubscriptionFeatureviagetActiveTenantSubscriptions, 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, perredisCacheAdapterRedis-swappbar — Infra-Schalter; die genutzten ResolvergetActiveTenantSubscriptions/evaluateFlagForContextcachen bereits cross-replica).
Bewusst aufgeschoben (begründet):
- Default-on Auto-Audit-Prisma-Middleware: Die Hash-Kette + explizites
auditEvent/createAuditEventsind 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;
buildAuditEventCreateDatanimmt 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ürdeverifyAuditChainfü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, analogwithTenantRLS) oder alle Worker-Aufrufer in den Tenant-RLS-Kontext wrappen; Regressions-Test analogrls-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 dennotify()-Write inrunWithRlsContext({ tenantId: input.tenantId }, …). - Alle 4 kranken Call-Sites in
apps/worker/src/handlers.tsumgestellt (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 auswithTenantRLS) undportal-lifecycle-bootstrap(bereitsrunWithRlsContext) waren gesund. - Regressionstest
apps/worker/src/notify-rls.test.ts: bildet die FORCE-RLS-Policy (hg_NotificationDelivery_insertWITH CHECK) im Fake-Client nach (AGENTS.md §RLS — Mock ohne Policy beweist nichts); erster Test dokumentiert den Bug (plainnotify()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).