Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M00-querschnitt-foundation.md
T

18 KiB
Raw Blame History

Boilerplate-Abgleich M00 — Querschnitt-Hülle (Bauprinzipien + Hot-Swap)

Abgleich der 17 Querschnitt-Milestones M001–M017 gegen die Boilerplate-Foundation (/Users/raffaelsheikh/Documents/GitHub/boilerplate). Eigene Greps/Reads verifiziert, nicht nur Inventur übernommen. Alle Pfade absolut. Boilerplate nur gelesen, nichts geändert.

Feld Wert
Modul-ID M00 (Sammel-Hülle für M001–M017)
Name Querschnitt-Hülle (Bauprinzipien + Hot-Swap)
Milestones M001 Audit-Log, M002 Klartext-Diagnostik, M003 i18n-Pflicht, M004 Tenant-Scope+Owner, M005 URL-Tampering+Mass-Action, M006 Feature-Flags, M007 Idempotenz, M008–M010 Apps-Engine-Adapter/State-Machine, M011 Notifications, M012 Workspace-Topologie, M013 View-Model-Konvention, M014 Action-Callback-Contract, M015 Subframe-Adapter, M016 Visual-Regression-Gate, M017 Hot-Swap-Drill
Block Querschnitt-Hülle Teil 1 (Bauprinzipien, M001–M011) + Teil 2 (UI-Hot-Swap-Architektur, M012–M017)
Pflichtenheft-Quelle _bmad-output/pflichtenheft/03-architektur.md (A.1, A.4, A.5, A.6, A.7, A.8) + AGENTS.md + INTEGRATION-CONTRACTS.md
Reuse-Level HIGH — fast die gesamte Hülle existiert in der Boilerplate als lauffähige Patterns + CI-Gates. HiveGrid füllt Inhalte (Error-Texte, Flags, i18n-Keys, Adapter, Sidebar-Einträge). Echte Lücken: Activity-Stream-Service (logActivity), Search-indexed-entities-Registry, Subframe-Adapter-Pattern (Paket leer), plus durchgängiger Naming-Drift in der HiveGrid-Doku.

Übernehmbar aus Boilerplate

Milestone Boilerplate-Pfad Was Wie nutzbar
M001 Audit …/packages/foundation/src/audit.ts auditEvent(input, client), withAuditMiddleware(handler, buildEvent, client), Typen AuditEventInput/AuditEventClient (Pattern, Prisma-frei per Client-Injection) 1:1 als Service-Wrapper
M001 Audit (DB) …/packages/db/src/audit-events.server.ts createAuditEvent als single write-path, tamper-evidente Hash-Chain pro Tenant (audit-hash.ts), Outbox-Publish; Felder actorIp, regulatoryScope, dataSensitivity, outcome, sourceModule 1:1 — HiveGrid liefert nur die Module-spezifischen action/targetType-Werte
M001 Audit (Schema) …/prisma/schema/core.prisma:55 (AuditEvent) Vollständiges Audit-Modell inkl. previousHash/eventHash Hash-Chain 1:1
M001 Audit (CI) …/scripts/verify-audit-cascade-guard.mjs, verify-permissions-audit-baseline.mjs Schützt Audit-Cascade-Verhalten + Permission-Audit-Baseline 1:1 als Gate
M002 Klartext …/packages/foundation/src/errors.ts CatalogError, CatalogErrorDefinition, catalogRegistry (Object.freeze({}) — leer), foundationErrors (forbidden 403, notFound 404, idempotencyConflict/idempotencyInProgress 409), toPinoLogObject als-vorlage — Engine 1:1, HiveGrid füllt catalogRegistry mit Klartext-Definitionen (code/status/i18nKey/details)
M003 i18n …/packages/i18n/src/index.ts defaultLocale "de", supportedLocales ["de","en"], i18nNamespaces (crm, auth, settings, errors, mail, …), Intl-Formatter, ICU, createUseTranslate 1:1 Engine; HiveGrid ergänzt Namespaces/Keys
M003 i18n (assert) …/packages/foundation/src/notifications.ts (assertI18nKey), …/packages/view-models/src/index.ts (assertI18nLabel) Erzwingt Key-Form ^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$ statt Klartext 1:1
M003 i18n (CI) …/scripts/i18n-check.ts + …/scripts/verify-hardcoded-strings.mjs + ESLint über `packages/ui-app ui-subframe ui-mock (pnpm verify:i18n`)
M004 Tenant/Owner …/packages/foundation/src/permissions.ts requirePermission, withTenantScope, withPermission, withOwnerCheck, PermissionContext — Fehlschlag wirft CatalogError(notFound) = 404, nicht 403 (Existenz-Versteckung, A.5.3) 1:1
M004 Tenant (CI) …/scripts/tenant-isolation-report.ts (pnpm verify:tenant-isolation-report), verify-permission-matrix.mjs, verify-role-permission-baseline.mjs Tenant-Scoping- + Permission-Matrix-Report 1:1 Gate
M005 URL-Tampering (gleiches Paket) …/packages/foundation/src/permissions.ts + …/packages/foundation/src/outbound-http.ts 404-statt-403-Verhalten (kein Owner-Leak) + SSRF-Schutz validateOutboundHttpUrl/fetchOutboundHttpWithRedirects (block private IPv4/6, DNS-Check, Redirect-/Size-/Timeout-Limit) 1:1 für Hardening; Mass-Action-Limit (s. Lücken) ist HiveGrid-Logik
M006 Feature-Flags (leicht) …/packages/foundation/src/flags.ts defineFlag, featureFlag (user>tenant>global, override), selectFlagRecord, normalizeFlagScope 1:1 für einfache Gates
M006 Feature-Flags (Engine v2) …/packages/feature-flags/src/* (evaluate.ts, targeting/*, cache.ts, publisher.ts, client/context.tsx) Targeting (boolean/allowlist/percentage/plan-tier/role/time/composite), Zeitfenster, Parent-Dependency, sticky Bucketing, Eval-Cache + Cross-Process-Invalidierung, React-Hooks 1:1 mächtige Variante (M031–M033 nutzen sie)
M006 Feature-Flags (Schema) …/prisma/schema/featureFlags.prisma:1/32/44 (FeatureFlag/FeatureFlagFilter/FeatureFlagAudit) Flag-Tabellen inkl. append-only Audit-Trail, rules/variants/enabledFrom/parentFlagId 1:1
M007 Idempotenz …/packages/foundation/src/idempotency.ts withIdempotency(input, client, operation), IdempotencyClient, IdempotencyResponse — In-Process-Lock, stabiler Fingerprint-Hash, 409 bei Hash-Mismatch/In-Progress 1:1
M007 Idempotenz (DB) …/packages/db/src/idempotency-keys.server.ts, Schema …/prisma/schema/core.prisma:84 (@@unique([scope, key])) Idempotency-Key-Persistenz passend zur Client-Where-Form 1:1
M008–M010 Apps-Engine (Adapter-Register) …/packages/foundation/src/adapters.ts defineAdapter, getAdapter, AdapterStatus (not_configured/configured/healthy/degraded/unavailable) — globales Provider-Slot-Register mit Fallback not_configured 1:1 (verifiziert: Enum exakt wie behauptet)
M008–M010 Apps-Engine (Schema/State-Machine) …/prisma/schema/appsEngine.prisma (App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem) App-Installation pro Tenant, Sync-Run-State-Machine (pending/running/completed/partial/failed/cancelled/reverted), executionMode (manual/scheduled/webhook), Sync-Logs + Items 1:1 State-Machine; HiveGrid baut KWP/Gmail/AirCall-Adapter darauf
M008–M010 Apps-Engine (Plugin-Loader) …/packages/plugins/src/* (manifest-loader.ts, manifest-schema.ts) + …/packages/plugin-runtime/src/* (capabilities, capability-gateway, capability-grants, signature, crash-tracker, production-gate, runtime, audit-chain) + …/packages/plugin-sdk Vollständiges Plugin-Capability-/Sandbox-/Signatur-/Crash-Tracking-System als-vorlage für externe Adapter (über Inventur hinaus vorhanden)
M011 Notifications …/packages/foundation/src/notifications.ts notify, notifyMany, bundleNotifications, isNotificationEnabled, assertI18nKey, Typen NotificationInput/NotificationClient/NotificationPreference, Channels IN_APP/EMAIL, Status PENDING/SENT/FAILED/SKIPPED/READ 1:1 — Preference-Check, Upsert per sourceKey, Metadata-Redaction, Bundling
M011 Notifications (DB/Schema) …/packages/db/src/notifications.server.ts; Schema …/prisma/schema/notifications.prisma:14/41 (NotificationDelivery @@unique([tenantId,userId,channel,sourceKey]), UserNotificationPreference) Persistenz + Preferences 1:1
M011 Notifications (CI) …/scripts/verify-notification-boundary-baseline.mjs Erzwingt Notify-über-Service (kein direkter Email/Push) 1:1 Gate
M012 Workspace-Topologie …/packages/view-models, …/packages/ui-app, …/packages/ui-subframe, …/packages/ui-mock Alle vier Pakete existieren und bauen (pnpm verify:phase-c-boundaries, Phase-0 SIGNED-OFF) 1:1
M012 Topologie (CI) …/scripts/verify-phase-c-boundaries.mjs (pnpm verify:phase-c-boundaries) Erzwingt Layer-Trennung (Anti-Pattern: Prisma in ui-, ui-subframe-Direktimport, useLoaderData in ui-) 1:1 Gate
M013 View-Model-Konvention …/packages/view-models/src/index.ts VMState<T> (idle/loading/ready/empty/error, error trägt messageKey+code), VMStatus, ready, empty 1:1 (verifiziert: Union exakt wie behauptet)
M014 Action-Callback-Contract …/packages/view-models/src/index.ts ActionCallbacks<T> (onCreate/onUpdate/onDelete/onRefresh) 1:1
M013/M014 Registry-Gating …/packages/view-models/src/index.ts RegistryGate (permission?/flag?), I18nLabel, SidebarRegistryItem/BreadcrumbRegistryItem/MobileRegistryItem/PortalRegistryItem/ShellRegistries, assertI18nLabel 1:1 Typen für die Shell-Registries
M015 Subframe-Adapter …/packages/ui-subframe/ (README + leeres src/index.ts) Reservierte Vendor-Import-Boundary; exportiert bewusst leere Registry als-vorlage — Boundary steht, der Adapter-Code (M015-Kern) ist NOCH NICHT gebaut (s. Lücken)
M016 Visual-Regression …/scripts/verify-ui-mock-visual.ts (pnpm verify:ui-visual), Baseline …/packages/ui-mock/visual-baseline/; CI ci.yml:117 Visual-Regression-Gate läuft im CI 1:1 Gate; HiveGrid ergänzt Snapshots pro Hauptansicht
M017 Hot-Swap-Drill …/scripts/verify-ui-hot-swap.ts (pnpm verify:ui-hot-swap, pnpm test:hot-swap); CI-Job „Test UI mock hot-swap" ci.yml:119-120; …/packages/ui-mock/ als Drop-in Tausch ui-app↔ui-mock in CI; bricht bei versteckter Kopplung 1:1 Gate; HiveGrid hält Smoke-E2E hot-swap-fähig
Querschnitt (Logging) …/packages/logger/src/index.ts createLogger mit Redaction (authorization/cookie/password/token/secret/apiKey/…), createChildLogger, resolveLogLevel 1:1
Querschnitt (Observability/Metrics) …/packages/observability (PIISpanProcessor), …/packages/metrics (createMetricsRegistry, recordAICostCents, Token-Auth) PII-Scrubbing + Prometheus-Metriken 1:1
Querschnitt (URL/Config) …/packages/url/src/canonical.ts (appPath/appUrl host-aware, adminPath, apiPath), …/packages/config/src/* (Env-Katalog, Session-Cookie-Policy, Domain-Routing, Secret-Validatoren) Kanonische Tenant-/Admin-/API-Links + Env-Validierung 1:1
Querschnitt (Entitlements) …/packages/entitlements/src/* (featureKeys, evaluateEntitlement, standardEntitlementPlans, productBlueprints) Feature-Gate-/Plan-Auswertung (ergänzt Feature-Flags um Billing-Gating) anpassen — HiveGrid-Plan-/Seat-Modell befüllen (M153–M156)

Vorhandene Daten-Modelle (Prisma)

Alle verifiziert in /Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/:

Modell Pfad Querschnitt
AuditEvent …/prisma/schema/core.prisma:55 M001 — Hash-Chain (previousHash/eventHash), actorType, outcome, dataSensitivity, regulatoryScope[], metadata, requestId
IdempotencyKey …/prisma/schema/core.prisma:84 M007 — @@unique([scope, key], name: "idempotency_key_scope_key"), expiresAt-Index
FeatureFlag / FeatureFlagFilter / FeatureFlagAudit …/prisma/schema/featureFlags.prisma:1 / :32 / :44 M006 — v2-Felder (rules/variants/enabledFrom/enabledUntil/parentFlagId) + append-only Audit
NotificationDelivery / UserNotificationPreference …/prisma/schema/notifications.prisma:14 / :41 M011 — @@unique([tenantId,userId,channel,sourceKey]) für Upsert
App / DataConnection / AppSyncRun / AppSyncRunLog / AppSyncItem …/prisma/schema/appsEngine.prisma M008–M010 — App-Install pro Tenant, Sync-State-Machine, Sync-Logs/Items
SubscriptionFeature / PortalSubscriptionFeature …/prisma/schema/subscriptions.prisma:65 / …/prisma/schema/portals.prisma:149 Entitlements (Plan-/Portal-Feature-Zuordnung)
(weitere relevante Schemas) permissions.prisma, accounts.prisma, plugins.prisma, outbox.prisma, queue.prisma Permissions, Tenant/User, Plugin-Manifest, Outbox (Audit/Search-Publish), BullMQ

Insgesamt 30 .prisma-Dateien (nicht 184 Einzelmodelle in einer Datei — die Inventur-Angabe „184 Modelle" bezieht sich auf das Gesamt-Schema über alle Dateien).


Lücken / komplett neu zu bauen

  1. Activity-Stream-Service logActivity() — FEHLT komplett.

    • Grep über packages/ und apps/web/app nach logActivity/ActivityStream/activity-stream ergab keinen Treffer.
    • DoD #14 (AGENTS.md) und INTEGRATION-CONTRACTS.md §„Activity-Stream" fordern logActivity auf Kontakt/Firma/Lead/Verkaufsfall/Auftrag. Das ist HiveGrid-spezifisch und muss neu gebaut werden (eigener Querschnitt-Service, distinkt vom Audit-Log). Fachlich angesiedelt in M045 (Aktivitäts-Stream), aber als Querschnitt-Vertrag hier zu definieren.
  2. Search-indexed-entities-Registry — FEHLT am behaupteten Ort.

    • AGENTS.md DoD #16 verweist auf packages/db/src/search/indexed-entities.ts. Dieser Pfad/Ordner existiert nicht (packages/db/src/search/ fehlt).
    • Die Such-Engine liegt stattdessen in …/packages/search/src/* (index-helper.ts, client.ts, outbox-publisher.ts, query, sanitize). Die zentrale Entity-Registrierungs-Konvention (indexed-entities) muss neu angelegt + im DoD-Pfad korrigiert werden.
  3. Subframe-Adapter-Pattern (M015-Kern) — NUR Boundary, kein Code.

    • …/packages/ui-subframe/ ist bewusst leer (README: „exports an empty registry … import rules and review gates … in a later slice").
    • Es existiert kein adapters/-Verzeichnis in …/packages/ui-app/ (nur src/, src/test-utils, test-setup). Das in M015 geforderte Type-Bridge-Adapter-Pattern (Subframe-Props ↔ HiveGrid-VM) ist noch zu bauen.
  4. Mass-Action-Schutz (M005) — Engine fehlt.

    • SSRF-Hardening + 404-statt-403 sind vorhanden; ein dediziertes Bulk-/Mass-Action-Limit + Bestätigungs-/Vorschau-Flow (Pflichtenheft A.10.1 „würde 1.400 Personen betreffen") ist als generischer Querschnitt nicht vorhanden und neu zu konzipieren.
  5. Naming-Drift in der HiveGrid-Doku (kein Code-Gap, aber Blocker für jeden Folge-Agent).

    • AGENTS.md, alle PLAN.md und PROGRESS-TRACKER-Vorlagen referenzieren packages/ui-hivegrid/..., packages/ui-hivegrid/src/app-shell/sidebar.config.ts, @hivegrid/foundation.
    • Boilerplate-Realität: Paket heißt packages/ui-app (npm @toolctrl/ui-app), Foundation ist @toolctrl/foundation, und die Sidebar liegt nicht in einem Paket-sidebar.config.ts, sondern in …/apps/web/app/application/sidebar/ (AppSidebar.tsx, AdminSidebar.tsx, SidebarItem.ts, SidebarGroupDto.ts) — gegated via CI pnpm verify:sidebar-routes.
    • Der PROGRESS-TRACKER Phase-0 listet diese Umbenennung explizit als ⚪ NICHT-GESTARTET („Doku-Naming-Anpassung an Boilerplate-Realität"). Muss vor M018ff. erfolgen, sonst greifen DoD-Pfade ins Leere.
  6. catalogRegistry ist leer (erwartet, kein Bug). Object.freeze({}) in errors.ts — HiveGrid muss alle Klartext-Fehler-Definitionen (M002, Bauprinzip A.1) befüllen. Kein Default-Katalog vorhanden.

  7. Locale-Inhalte nur DE/EN-Gerüst. …/apps/web/public/locales existiert; HiveGrid-Namespaces/Keys (crm, …) sind zu befüllen (Phase 1: nur Deutsch, A.4.2).


Empfohlenes Vorgehen

Phase 0 (Voraussetzung, vor jedem Folge-Modul):

  1. Naming-Drift beheben (Tracker Phase-0-Punkt): in AGENTS.md, allen PLAN.md, PROGRESS-TRACKER-Vorlagen ui-hivegrid→ui-app, @hivegrid/foundation→@toolctrl/foundation ersetzen; Sidebar-Pfad auf apps/web/app/application/sidebar/ und Such-Registry-Pfad auf packages/search/... korrigieren. Ohne diesen Schritt sind alle DoD-Checklisten falsch verlinkt.
  2. Pre-Flight (pnpm typecheck && pnpm test, EU-Sterilisations-Grep) gemäß AGENTS.md durchlaufen.

Phase 1 — 1:1 übernehmen (kein Code, nur Wiring/Inhalt): M001 (audit), M004/M005-Hardening (permissions/outbound-http), M007 (idempotency), M011 (notify), M012 (Topologie), M013/M014 (VMState/ActionCallbacks) sind als Engine fertig. Hier nur HiveGrid-Werte einfüllen und CI-Gates (verify:phase-c-boundaries, verify:tenant-isolation-report, verify:notification-boundary-baseline, test:hot-swap, verify:ui-visual) als Pflicht-Pipeline verdrahten.

Phase 2 — Inhalte befüllen (Engine vorhanden, Daten fehlen): M002 catalogRegistry mit Klartext-Fehlern; M003 i18n-Namespaces/Keys (DE) + ESLint-Scope auf HiveGrid-UI-Pakete erweitern; M006 Flags definieren (defineFlag/Engine v2 für M031–M033).

Phase 3 — Apps-Engine aufsetzen: M008–M010 auf vorhandenem appsEngine.prisma + foundation/adapters.ts + packages/plugins/plugin-runtime aufbauen; State-Machine ist da, KWP/Gmail/AirCall-Adapter sind HiveGrid-Arbeit.

Phase 4 — echte Neubauten:

  • logActivity()-Querschnitt-Service (Lücke 1) — vor den ersten Stammdaten-Modulen (M042ff.), da DoD #14 pflicht.
  • indexed-entities-Such-Registry (Lücke 2) auf Basis packages/search/ anlegen, DoD-Pfad korrigieren.
  • Subframe-Adapter-Pattern M015 (Lücke 3) — packages/ui-app/src/adapters/ + Beispiel-Adapter (DataTable→KontaktList), abgesichert durch M016/M017-Gates.
  • Mass-Action-Schutz M005 (Lücke 4) — generischer Bulk-Confirm/Preview-Flow.

Reihenfolge-Logik: Engine-Übernahme (Phase 1) ist risikolos und sofort. Die vier echten Neubauten (Phase 4) blockieren die fachlichen Module — logActivity und indexed-entities zuerst, da bereits M042 sie braucht; Subframe-Adapter + Mass-Action können parallel laufen.