Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P1b.md
T
2026-07-08 16:15:37 +02:00

7.7 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 geplant

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)
  • 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 · PHASE-SOURCES.md → Phase 1 (M001/M003/M006/M011 + M005/M007)
  • designer-briefs/P01-fundament-walking-skeleton.md (Service-Kerne)
  • _bmad-output/specs/M21-audit-log.md, M22-notifications.md, M30-i18n.md, M32-feature-flags.md

Dev-Nachzug (nach Davids D-D0a/D-D0b-Delta)

  • Activity-Stream-/Konnektor-Wiring an Davids Komponenten-Entscheidungen angepasst
  • REQUIREMENTS/PHASE-SOURCES 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).