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

124 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`) | Build-Lint gegen hartkodierte Strings; läuft im CI (`ci.yml:101`) | **1:1** Gate; ESLint-Scope auf HiveGrid-UI-Pakete erweitern |
| 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.