18 KiB
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
-
Activity-Stream-Service
logActivity()— FEHLT komplett.- Grep über
packages/undapps/web/appnachlogActivity/ActivityStream/activity-streamergab keinen Treffer. - DoD #14 (AGENTS.md) und INTEGRATION-CONTRACTS.md §„Activity-Stream" fordern
logActivityauf 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.
- Grep über
-
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.
- AGENTS.md DoD #16 verweist auf
-
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/(nursrc/,src/test-utils,test-setup). Das in M015 geforderte Type-Bridge-Adapter-Pattern (Subframe-Props ↔ HiveGrid-VM) ist noch zu bauen.
-
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.
-
Naming-Drift in der HiveGrid-Doku (kein Code-Gap, aber Blocker für jeden Folge-Agent).
- AGENTS.md, alle
PLAN.mdund PROGRESS-TRACKER-Vorlagen referenzierenpackages/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 CIpnpm 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.
- AGENTS.md, alle
-
catalogRegistryist leer (erwartet, kein Bug).Object.freeze({})inerrors.ts— HiveGrid muss alle Klartext-Fehler-Definitionen (M002, Bauprinzip A.1) befüllen. Kein Default-Katalog vorhanden. -
Locale-Inhalte nur DE/EN-Gerüst.
…/apps/web/public/localesexistiert; HiveGrid-Namespaces/Keys (crm, …) sind zu befüllen (Phase 1: nur Deutsch, A.4.2).
Empfohlenes Vorgehen
Phase 0 (Voraussetzung, vor jedem Folge-Modul):
- Naming-Drift beheben (Tracker Phase-0-Punkt): in AGENTS.md, allen
PLAN.md, PROGRESS-TRACKER-Vorlagenui-hivegrid→ui-app,@hivegrid/foundation→@toolctrl/foundationersetzen; Sidebar-Pfad aufapps/web/app/application/sidebar/und Such-Registry-Pfad aufpackages/search/...korrigieren. Ohne diesen Schritt sind alle DoD-Checklisten falsch verlinkt. - 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 Basispackages/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.