Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,123 @@
# 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.
@@ -0,0 +1,238 @@
# Boilerplate-Abgleich: M01 — CRM-Kern
> Faktischer Abgleich der HiveGrid-Anforderungen (Modul 1) gegen die Boilerplate
> (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`). Read-only verifiziert mit
> eigenen Greps/Reads, nicht nur Inventur. Alle Pfade absolut.
## Kopf
| Feld | Wert |
| --- | --- |
| Modul-ID | M01 |
| Name | CRM-Kern (Kontakte + Firmen + Leads) |
| Milestones | M042 (Kontakt-Stammdaten), M043 (Firma-Stammdaten + Hierarchie), M044 (Tags + Custom-Felder + Datenherkunft), M045 (Aktivitäts-Stream), M046 (Listen + Segmente + DSGVO-Felder) |
| Pflichtenheft-Block | Block 2, Abschnitte 1.1–1.13 (`_bmad-output/pflichtenheft/blocks/block2.md`) |
| Detail-Spec | `_bmad-output/specs/M01-crm-kern.md` |
| **Reuse-Level** | **medium** |
## Reuse-Verdict in einem Satz
Das Daten-Modell des Moduls (Contact/Company/Lead als **dedizierte, first-class
Prisma-Modelle** mit Mehrfach-Email/-Telefon, M:N-Relation, Activity-Sourcing-Tabelle,
Custom-Field-Definitionen, Tags) existiert in der Boilerplate **nicht** — es gibt nur
(a) eine generische No-Code-Engine (`entityBuilder`), auf der die Boilerplate ihr eigenes,
architektonisch **unvereinbares** CRM (`company`/`contact`/`opportunity` als `Entity`+`Row`)
betreibt, und (b) einen operator-scoped Marketing-`Lead` (kein Tenant-CRM-Lead). Der gesamte
**Querschnitt** (Audit, Permissions/Tenant-Scope, Notifications, i18n, Feature-Flags,
View-Models, Search, Export/DSGVO, App-Shell, Form-Capture) ist hingegen **reif vorhanden
und direkt nutzbar**. Daher: solides Fundament + viele Vorlagen, aber die CRM-Kern-Tabellen
und die domänen-spezifische Logik sind **neu zu bauen**.
---
## Wichtige Architektur-Vorbemerkung (entscheidet das gesamte Mapping)
Die Boilerplate enthält **zwei** CRM-Konzepte, die beide NICHT zur HiveGrid-Spec passen:
1. **Boilerplate-„CRM" über den Entity-Builder** (`apps/web/app/modules/crm/`):
`company`, `contact`, `opportunity`, `submission` sind **keine eigenen Prisma-Modelle**,
sondern werden zur Laufzeit als `entityBuilder.Entity`-Definitionen geseedet
(`apps/web/app/modules/crm/services/ProductCoreCrmEntities.server.ts`,
`productCoreCrmEntityNames = ["company","contact","opportunity"]`). Ein Kontakt ist ein
`Row` mit `RowValue`-Einträgen (`firstName`, `lastName`, `email`, `jobTitle`,
`marketingSubscriber`). Verifiziert in `CrmService.ts` (`RowValueHelper.getText({..., name: "email"})`).
→ **Inkompatibel** mit der HiveGrid-Spec, die explizit dedizierte, typisierte Tabellen
mit Constraints, Indizes (`tenant_id, archived_at, last_activity_at`), `pg_trgm`-Fuzzy-Index,
`ContactCompanyRelation` (M:N mit Rolle/Primary), separate `ContactEmail`/`ContactPhone`-Tabellen
und eine zentrale `Activity`-Event-Sourcing-Tabelle fordert.
2. **Marketing-`Lead`** (`prisma/schema/marketingLeads.prisma:14`): bewusst **NICHT
tenant-scoped** (operator-/sales-of-record, `@@unique([email])`, First-Touch-UTM,
`convertedToTenantId`). Das ist der „Wer-wird-HiveGrid-Kunde"-Funnel, **nicht** der
tenant-interne CRM-Lead aus M01/M02 (der ist tenant-scoped, hat Status
`new|qualified|converted|lost|spam` und konvertiert zu einem `Contact`, nicht zu einem `Tenant`).
**Konsequenz:** Die HiveGrid-CRM-Modelle gehören neu nach `prisma/schema/app.prisma`
(der vorgesehene leere Platzhalter, `prisma/schema/app.prisma`). Die Entity-Builder-Variante
wird NICHT übernommen (allenfalls als konzeptionelle Vorlage für Custom-Felder-UI). Das
Boilerplate-CRM-Modul (`apps/web/app/modules/crm`, `routes/app.$tenant/crm`, `routes/admin/crm`)
sollte für HiveGrid entfernt/ersetzt werden, da es die andere Architektur transportiert.
> Hinweis: Das HiveGrid-Cloud-Repo selbst enthält aktuell **noch keinen** Code
> (`apps/`/`packages/` fehlen, nur `prisma/` + `docs/` + Specs vorhanden). Die Boilerplate
> ist die zu übernehmende Basis (gem. AGENTS.md „Die Boilerplate IST deine Codebase").
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/foundation/src/permissions.ts` | `withTenantScope()`, `withPermission()`, `withOwnerCheck()`, `requirePermission()` — Tenant-Isolation + Permission-/Owner-Gate; 404-statt-403 (`CatalogError(notFound)`) | **1:1** — deckt Block I komplett (crm.read_own/read_all/write/delete/admin, Owner-Check, 404-Versteckung) |
| `packages/foundation/src/audit.ts` | `auditEvent()`, `withAuditMiddleware()` + `AuditEvent`-Hash-Kette (`packages/db/src/audit-hash.ts`, `prisma/schema/core.prisma:55`) | **1:1** — Audit-Default (AV #6) für jede Schreib-Aktion |
| `packages/foundation/src/notifications.ts` + `prisma/schema/notifications.prisma` | `notify()`, `bundleNotifications()`, Preference-Check, In-App/Email/Push | **1:1** — Notification-Wiring (Verantwortlichen-Wechsel, Lead-Zuweisung) |
| `packages/foundation/src/errors.ts` | `CatalogError`, `foundationErrors` (forbidden/notFound/conflict), `toPinoLogObject` | **als-vorlage** — HiveGrid-Error-Catalog (M002) auf diesem Muster; Klartext-Texte (Block C/D/F/G/H „Klartext-Hinweise") als i18n-Keys ergänzen |
| `packages/foundation/src/idempotency.ts` | `withIdempotency()` (Lead-Promotion-Transaktion, Bulk-Actions) | **1:1** |
| `packages/view-models/src/index.ts` | `VMState<T>`, `VMStatus`, `ActionCallbacks<T>`, `RegistryGate`, `I18nLabel`, `SidebarRegistryItem`, `assertI18nLabel` | **1:1** — VM-/Action-Vertrag für alle Listen-/Detail-VMs (AGENTS.md C.18, INTEGRATION-CONTRACTS §11) |
| `packages/feature-flags/src/*` + `prisma/schema/featureFlags.prisma` | Flag-Engine v2 (Targeting, Cache, React-Hooks) bzw. leichtgewichtig `foundation/src/flags.ts` | **1:1** — Feature-Flag-fähig (M006, DoD) |
| `packages/i18n/src/*` + `apps/web/public/locales/{de,en}/crm.json` | Locales, Intl-Formatter, ICU; **CRM-Namespace `crm` existiert bereits** (`i18nNamespaces` in `packages/i18n/src/index.ts`) | **anpassen** — Keys neu für HiveGrid-CRM füllen; Namespace + Formatter-Infra 1:1 |
| `packages/db/src/client.server.ts`, `transactions.server.ts`, `outbox.ts` | `getDbClient()/getReadDbClient()/getExtendedDbClient()`, `runDbTransaction()`, `publishOutboxEvent()` | **1:1** — DB-Grenze + Lead-Promotion-Transaktion + Side-Effects via Outbox |
| `packages/db/src/dsgvo/user-fk-map.ts`, `dsgvo/pseudonymize.ts` | Zentrale User-FK-Karte (CI-Test erzwingt Vollständigkeit) + Pseudonymisierung | **anpassen** — neue Contact/Lead-User-FKs (`assigned_to_user_id`, `created_by_user_id`) eintragen, sonst bricht CI |
| `packages/exports/*` + `apps/worker/src/jobs/dsgvo-export.ts` | Streaming-Export CSV/JSON/XLSX/PDF, S3-Sink, **DSGVO-Personal-Data-Export** (JSON-Bundle, Signed-URL, Audit-Event) | **anpassen** — Block D „DSGVO-Daten-Export (alle Daten als JSON)" + Block C „Export als CSV (gefilterte Auswahl)"; an HiveGrid-Contact-Schema anpassen |
| `packages/imports/*` + `prisma/schema/imports.prisma` | Dependency-freies Parser-/Dry-Run-/Dedupe-Framework (CSV/JSON/XLSX), PII-Redaction; `src/dedupe.ts` (`DuplicateKeyField`, `DuplicateDetectionRow`) | **anpassen** — `lead_source = import`, Dedupe-Logik als Basis für Block G (Duplikat-Erkennung); Dry-Run-Preview für Import-Wizard |
| `packages/search/src/*` (`@toolctrl/search`) + `apps/web/app/modules/crm/services/crmContactSearch.server.ts` | Meilisearch-Client + **SQL-Fallback** (`searchWithFallback`, `SEARCH_BACKEND=sql`); Beispiel-Such-Implementierung über Kontakt-Felder | **als-vorlage** — Block G (Listen-Suche + Auto-Complete + globale Suche M24/M056); HiveGrid-Implementierung muss auf neue Tabellen statt `RowValue` zeigen; Trigram/`pg_trgm` ist im Schema selbst zu ergänzen (nicht vorhanden) |
| `packages/form-widget/src/routing.ts` | `resolveSubmissionTarget`/`applyFieldMapping` mit Ziel `"crm-contact"` (verifiziert) + `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) | **anpassen** — `lead_source = form` Eingang (Block A, M02); Routing-Ziel auf HiveGrid-Lead/Contact umbiegen |
| `apps/web/app/components/layouts/sidebars/shadcn/*` + `apps/web/app/application/sidebar/{AppSidebar.tsx,SidebarItem.ts,SidebarGroupDto.ts}` + `ShadcnSidebarLayout.tsx`, `AppLayout.tsx` | Vollständige authentifizierte App-Shell, datengetriebene Sidebar mit Permission-/Feature-Gating, Tenant-Theme, Breadcrumbs, Command-Palette | **als-vorlage** — HiveGrid fordert eigene `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (existiert noch nicht); Shell-Mechanik + Permission-Filter übernehmen, in HiveGrid-6-Gruppen-Schema (`stammdaten`, `arbeiten`) überführen |
| `apps/web/app/components/ui/**` (~707 .tsx, shadcn/Radix) | Tabellen (`TableNew`, `TablePagination`, `RowsLoadMoreCard`, `ColumnSelector`, `GridPagination`), Forms/Inputs/Selectors/Editors, `multi-select.tsx`, Modals (`ConfirmDialog`), Empty-/Loading-States, `command.tsx`, `badge.tsx` | **als-vorlage** — deckt nahezu alle UI-Element-Anforderungen aus Block C/D/E (Listen-Tabelle, Spalten-Selektor, Cursor-„Mehr laden", Filter, Bulk-Checkboxes, Inline-Edit, Tag-Editor via multi-select, Markdown-Editor). MEMORY-Regel: HiveGrid-Routen müssen via Subframe + `packages/ui-hivegrid`-Adapter laufen → diese Komponenten als Adapter-Backing |
| `apps/web/app/components/ui/tables/ColumnSelector.tsx`, `GridPagination.tsx`, `RowsLoadMoreCard.tsx` | Spalten-Konfiguration + Cursor-Pagination („Mehr laden", 50/Page) | **als-vorlage** — Block C Performance-Anforderung (10k+, server-side) |
| `prisma/schema/marketingLeads.prisma` (`Lead`, `LeadEvent`, `LeadStatus`) | Lead-Timeline-Append-Log + Status-Enum + Conversion-FK-Pattern | **als-vorlage** — NUR konzeptionell für M02 Tenant-Lead (Status-Maschine, Event-Timeline, Promotion-FKs). NICHT 1:1 (operator- vs. tenant-scoped, andere Status-Werte) |
| `prisma/schema/queue.prisma` (`ExportJob` mit `expiresAt`/`hardDeletedAt`) | Retention/Grace-Pattern (Soft→Hard mit Frist) | **als-vorlage** — DSGVO-Auto-Lösch von Spam-Leads (30 Tage), `archived_at`-Grace |
| `apps/web/app/application/ui/uiRegistry.ts` + `docs/ui-inventory/*` + `scripts/verify-*boundaries*.mjs` | Stabile `data-ui-id`-Registry + maschinenlesbare Inventur + Layer-Grenz-Gates | **als-vorlage** — UI-Governance/Hot-Swap (M016/M017, DoD-Tests) |
| `packages/ui-mock/src/*` | Hot-Swap-Mock-Generator (deterministisches HTML + Hashes) | **1:1** — Hot-Swap-Drill (DoD: Smoke-Test gegen `ui-mock`) |
| `packages/entitlements/src/features.ts` (`crm-basic` Feature-Key) | Feature-Gate-Registry; `crm-basic` existiert bereits | **anpassen** — CRM-Feature-Gating; Permission-Keys (`crm.*`) gehören laut INTEGRATION-CONTRACTS §10 nach `packages/entitlements/src/permissions.ts` (noch zu erstellen) |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
**Direkt CRM-deckend: KEINE.** Verifiziert via
`grep "^model (Contact|Company|ContactCompany|ContactEmail|ContactPhone|Activity|CustomField|Tag)"`
über `prisma/schema/*.prisma` → 0 Treffer (einziger Tag-Treffer ist `EntityTag` der No-Code-Engine).
Relevante **angrenzende / als Fundament nutzbare** Modelle:
| Modell | Pfad | Relevanz für M01 |
| --- | --- | --- |
| `AuditEvent` | `prisma/schema/core.prisma:55` | Audit-Trail-Default (AV #6) — tamper-evident Hash-Kette, `dataSensitivity`/`regulatoryScope` für PII/GDPR |
| `IdempotencyKey` | `prisma/schema/core.prisma:84` | Idempotente Lead-Promotion / Bulk-Actions |
| `Log` | `prisma/schema/core.prisma:36` | Per-`Row`-Aktivitäts-Timeline der No-Code-Engine (`rowId`, `action`, `details`, `commentId`) — **konzeptionelle Vorlage** für die HiveGrid-`Activity`-Tabelle (Block E), NICHT übernehmbar (kein `subject_type`/`actor_kind`/`summary_text`, an `Row` gebunden) |
| `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` | `prisma/schema/permissions.prisma` | RBAC-Fundament — Block I Permission-Bundles (`crm.none`→`crm.admin`) als `Role`+`RolePermission` abbildbar |
| `User`, `Tenant`, `TenantUser` | `prisma/schema/accounts.prisma` | `assigned_to_user_id`/`created_by_user_id`-FKs, Tenant-Scope-Anker, DSGVO-Flags |
| `NotificationDelivery`, `UserNotificationPreference` | `prisma/schema/notifications.prisma` | Notification-Wiring |
| `FeatureFlag` (+ Filter/Audit) | `prisma/schema/featureFlags.prisma` | Feature-Flag-fähig (DoD) |
| `Lead`, `LeadEvent`, `LeadStatus` | `prisma/schema/marketingLeads.prisma:14` | **NUR Vorlage** für tenant-scoped CRM-Lead (M02); semantisch operator-scoped, NICHT 1:1 |
| `Form`, `FormSubmission` | `prisma/schema/formWidget.prisma` | Lead-Capture-Eingang (`lead_source=form`) |
| `ImportJob` | `prisma/schema/imports.prisma` | Bulk-Import (`lead_source=import`) |
| `ExportJob` | `prisma/schema/queue.prisma` | DSGVO-Export-Job + Retention-Pattern |
| `entityBuilder.*` (`Entity`, `Property`, `EntityView`, `Row`, `RowValue`, `RowComment`, `RowTag`, `EntityTag`, `RowTask`, `RowPermission`, `EntityRelationship`) | `prisma/schema/entityBuilder.prisma` | **Konkurrierendes** Daten-Modell für Custom-Felder/Tags/Activity — als **Vorlage** für Block F/H, aber Architektur (polymorphe `RowValue`) wird für M01 NICHT übernommen (Spec fordert typisierte Tabellen) |
**Property-Typen** (`apps/web/app/application/enums/entities/PropertyType.ts`): NUMBER, TEXT,
DATE, MEDIA, SELECT, BOOLEAN, MULTI_SELECT, MULTI_TEXT, RANGE_NUMBER, RANGE_DATE, FORMULA.
→ deckt die Spec-Custom-Field-Typen `text|number|date|select|multiselect|boolean` ab;
**fehlend** als eigene Typen: `url`, `email` (Spec Block F) — in der Boilerplate über TEXT +
`subtype`/`PropertyAttribute`-Validierung gelöst; HiveGrid muss `url`/`email` als
`field_type` neu vorsehen.
---
## Lücken / komplett neu zu bauen
**Daten-Layer (alles neu, nach `prisma/schema/app.prisma`):**
- `Contact` (alle Felder: salutation, title, first/last_name, address_*, birthdate, notes,
language, assigned_to_user_id, lead_source-Enum, is_endkunde, archived_at) — **fehlt**
- `Company` (legal_form, vat_id, tax_number, industry, website, address_*, …) + optionale
Mutter-Tochter-Hierarchie (M043) — **fehlt**
- `ContactCompanyRelation` (M:N, role, is_primary, since/until_date) — **fehlt**
- `ContactEmail` / `ContactPhone` (value, label-Enum, is_primary) — **fehlt**
- **Tenant-scoped `Lead`** (mit Status `new|qualified|converted|lost|spam`,
converted_to_contact_id, converted_to_deal_id) — **fehlt** (Marketing-`Lead` ist anders)
- `Activity` (zentrale Event-Sourcing-Tabelle: actor_kind, activity_type-Enum ~25 Werte,
subject_type/subject_id, related_entity_refs[], metadata, summary_text) — **fehlt**
(kein generisches subject-polymorphes Activity-Modell in der Boilerplate; `Log` ist row-gebunden)
- `CustomFieldDefinition` + `CustomFieldValue` (applicable_to contact/company/lead,
field_type inkl. url/email, options[], JSONB-Wert) — **fehlt** als dedizierte Tabellen
- `Tag` (8 Farben-Constraint, applicable_to[]) + `EntityTag`-Äquivalent für CRM-Entities — **fehlt**
(No-Code-`EntityTag`/`RowTag` ist row-gebunden, nicht übernehmbar)
- Spezifische Indizes: `(tenant_id, archived_at, last_activity_at)`,
`pg_trgm`-Trigram-Index auf Namen, FTS-Index — **alle neu** (Spec Block C/G)
- Branchen-Template-Seeding (SHK-Custom-Fields + Tag-Defaults) als Konfig-Datei (AV #3, A.3) — **neu**
**Domänen-Logik / Services (neu):**
- Lead-Promotions-Transaktion mit Auto-Email-Match (4 Optionen a–d) — **neu**
- Duplikat-Erkennung (Hard: Email/Phone; Soft: Name+Firma / Name+PLZ) + Inline-Live-Check +
Bulk-Merge-Tool mit Field-by-Field-Auswahl + Verknüpfungs-Umhängen — **neu**
(Dedupe-Primitiven aus `packages/imports/src/dedupe.ts` als Basis, aber CRM-Merge-Logik neu)
- `logActivity()`-Service (`@hivegrid/activity`, INTEGRATION-CONTRACTS §5) + Activity-Stream-VM
(Tag-Bucket-Gruppierung, Filter, Permission-aware, Firma=Aggregat der Kontakt-Activities) — **neu**
- Tag-Merge / Auto-Cleanup, Custom-Field-Verwaltung (Drag&Drop-Sortierung, Archive vs. Hard-Delete) — **neu**
**Querschnitt-Verdrahtung (HiveGrid-Konventionen — Ziel-Pfade existieren in Boilerplate noch nicht):**
- `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` — **fehlt** (kein `packages/ui-hivegrid`
in der Boilerplate); Sidebar-Gruppen STAMMDATEN (Kontakte/Firmen/Tags/Custom-Felder) + ARBEITEN (Lead-Inbox)
- `packages/ui-hivegrid/src/adapters/` (Subframe-Adapter) + `breadcrumbs/` + `mobile/tab-bar.config.ts`
+ `customer-portal/portal-shell.config.ts` — **alle neu** (DoD §13/§14)
- `packages/db/src/search/indexed-entities.ts` — **fehlt** (Verzeichnis `packages/db/src/search`
existiert nicht); Contact/Company/Lead als suchbare Entitäten registrieren (M056)
- `packages/entitlements/src/permissions.ts` (`crm.*`-Keys) — **fehlt** als Datei
- `@hivegrid/*`-Service-Fassaden (`activity`, `audit`, `notifications`) — Boilerplate nutzt
`@toolctrl/*`; Umbenennung/Fassade ist HiveGrid-Aufgabe (kein PR-blockierender Unterschied)
**UI (neu, aber stark gestützt):**
- Subframe-Designs für jede Route (MEMORY: Subframe pflicht) — **neu**, Boilerplate-`ui-subframe`
ist leerer Platzhalter
- Inline-Edit-Felder, Markdown-Notiz-Editor, Tag-Editor (ad-hoc anlegbar), Promotions-Modal,
Side-by-Side-Merge-UI, Custom-Field-Renderer pro Typ — als Komposition aus vorhandenen
shadcn-Primitiven, aber CRM-spezifisch **neu**
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Boilerplate-Bereinigung (vor M042):**
1. Boilerplate-CRM (Entity-Builder-basiert) zur Seite legen/entfernen, damit die andere
Architektur nicht in HiveGrid einsickert: `apps/web/app/modules/crm/`,
`apps/web/app/routes/app.$tenant/crm/`, `apps/web/app/routes/admin/crm/` (und der
No-Code-`crm`-Seed in `ProductCoreCrmEntities.server.ts`). Den `crm`-i18n-Namespace und
die `crm-basic`-Feature-Gate-Infrastruktur behalten.
2. HiveGrid-Querschnitt-Pakete anlegen, die noch fehlen: `packages/ui-hivegrid/` (sidebar.config,
adapters, breadcrumbs, mobile, customer-portal), `packages/db/src/search/indexed-entities.ts`,
`packages/entitlements/src/permissions.ts`. (Diese sind modul-übergreifend — ggf. eigenes
Fundament-Milestone, aber M01 ist der erste Konsument.)
**Phase 1 — Daten-Fundament (M042 → M043):**
3. CRM-Modelle in `prisma/schema/app.prisma` neu: `Contact`, `ContactEmail`, `ContactPhone`,
dann `Company`, `ContactCompanyRelation` (M:N). Forward-Only-Migration mit Inverse-SQL-Kommentar
(DoD). `pg_trgm`-Extension + Trigram-/FTS-Indizes + `(tenant_id, archived_at, last_activity_at)`-Index.
4. **Sofort übernehmen:** `withTenantScope()`+`withPermission()`+`withOwnerCheck()`
(`packages/foundation/src/permissions.ts`) für jeden Loader/Action; `auditEvent`/Middleware
für Schreib-Aktionen; neue User-FKs in `packages/db/src/dsgvo/user-fk-map.ts` (sonst CI-Bruch);
VM-Builder gegen `VMState`/`ActionCallbacks` (`packages/view-models`).
5. UI per Subframe → `ui-hivegrid`-Adapter, gestützt auf shadcn-Primitiven (`apps/web/app/components/ui/**`).
Sidebar-Einträge STAMMDATEN registrieren (INTEGRATION-CONTRACTS §1/§2).
**Phase 2 — Querschnitt-Features (M044 → M045):**
6. Tags (`Tag`+CRM-Tag-Join, 8-Farben-Constraint) und Custom-Felder
(`CustomFieldDefinition`+`CustomFieldValue`) neu — `PropertyType`-Enum + Entity-Builder-Custom-Field-UI
(`apps/web/app/components/entities/properties/*`) als **Vorlage**, `url`/`email`-Typen ergänzen.
SHK-Defaults als Seed-Konfig (A.3).
7. `Activity`-Tabelle + `logActivity()` neu (zentrales Event-Sourcing, INTEGRATION-CONTRACTS §5);
`Log`-Modell + `hasActivity`-Konzept der Engine als **Vorlage**. Activity-Stream-VM mit
Tag-Buckets/Filtern/Permission-Gate; Firma=Aggregat.
**Phase 3 — Listen, Suche, DSGVO (M046):**
8. Listen-VM mit server-side Filter (Permission-aware-Default, AV #5), Cursor-Pagination
(`RowsLoadMoreCard`/`GridPagination` als Vorlage), Spalten-Selektor (`ColumnSelector`),
Bulk-Actions. Such-Anbindung via `@toolctrl/search` (`searchWithFallback`, SQL-Fallback) auf
die neuen Tabellen; Registrierung in `indexed-entities.ts`.
9. Duplikat-Erkennung: `packages/imports/src/dedupe.ts`-Primitiven als Basis; Inline-Live-Check +
Bulk-Merge-Tool (`/admin/duplicates/`) neu.
10. DSGVO: `packages/exports` + `apps/worker/src/jobs/dsgvo-export.ts` an Contact-Schema anpassen
(Per-Contact-JSON-Export, Audit-Event); CSV-Export der gefilterten Listen-Auswahl.
**Durchgängig:** i18n-Keys (Namespace `crm`), Feature-Flag-Gate (M006), Smoke-Tests +
Hot-Swap-Drill (`ui-mock`) + Visual-Regression (DoD D.18–21), Klartext-States (DoD E.22–25).
---
## Anti-Erfindungs-Vorbehalte
- Es gibt **keine** dedizierten CRM-Prisma-Modelle in der Boilerplate (verifiziert per Grep).
- Das Boilerplate-CRM ist **Entity-Builder-basiert** (`Entity`+`Row`+`RowValue`), nicht
tabellen-typisiert — verifiziert in `CrmService.ts` und `ProductCoreCrmEntities.server.ts`.
- `packages/ui-hivegrid`, `packages/db/src/search`, `packages/entitlements/src/permissions.ts`
existieren in der Boilerplate **nicht** (verifiziert per `ls`/`find`).
- `@toolctrl/ui-subframe` ist **leer** (Platzhalter) — kein gebauter Subframe-Adapter-Layer.
- Der Boilerplate-`Lead` ist operator-/marketing-scoped (`@@unique([email])`, kein `tenantId`,
Status `new|contacted|qualified|trial|customer|churned|disqualified`) — **nicht** der
HiveGrid-Tenant-CRM-Lead.
- `url`/`email` sind keine eigenen `PropertyType`-Werte (nur via TEXT+subtype gelöst).
@@ -0,0 +1,112 @@
# Boilerplate-Abgleich: M02 — Lead-Inbox / Lead-Management
| Feld | Wert |
| --- | --- |
| Modul-ID | M02 (Modul 2) |
| Name | Lead-Inbox / Lead-Management |
| Milestones | M047 (Inbox + Quellen-Adapter), M048 (Routing pro Quelle), M049 (Auto-Verkaufsfall), M050 (Spam/Duplikat + DSGVO-Auto-Lösch), M051 (Status-Pipeline + Listen/Detail-UI + Statistik + Permissions) |
| Pflichtenheft-Block | Block 2, Modul 2 (Abschnitte 2.1–2.13) |
| **Reuse-Level** | **medium** |
## Kurz-Verdikt
Die Boilerplate enthält ein **vollständiges Marketing-/Funnel-Lead-System** (`Lead`/`LeadEvent`/`TenantAcquisition`/`MarketingIntegration` + Admin-Inbox-UI + Capture/Convert-Services + Outbound-Adapter). Das ist als **Vorlage / Muster** hochwertig, aber das Daten-Modell ist **bewusst operator-/marketing-scoped (NICHT tenant-scoped)** und mit `@@unique([email])` global eindeutig — das ist **inkompatibel** mit dem tenant-isolierten CRM-Lead-Inbox aus M02. Der HiveGrid-Lead muss daher ein **eigenes, tenant-scoped Modell** sein (gehört fachlich ohnehin zu Modul 1/CRM-Kern, das das `Lead`-Datenmodell besitzt). Solider, breiter Querschnitt (Form-Widget inkl. Honeypot, Outbox, Audit, Rate-Limiter, Export, Realtime, Apps-Engine-Schema) ist 1:1 nutzbar. Die eigentliche Inbox-Domänen-Logik (tenant-scoped Listen/Filter/Triage/Routing/Statistik) ist neu zu bauen, aber mit starken Vorlagen.
> Hinweis: `HiveGrid-Cloud` ist aktuell ein reines Spec-/Docs-Repo (`_bmad`, `_bmad-output`, `docs`, `prisma` leer). Es existiert noch **kein** `packages/ui-hivegrid`, kein `apps/*`, kein HiveGrid-Lead-Modell. Alle Boilerplate-Pfade unten beziehen sich auf `/Users/raffaelsheikh/Documents/GitHub/boilerplate`.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/marketingLeads.prisma` (`Lead`, `LeadEvent`) | Lead-Datenmodell + Event-Timeline-Pattern (Status-Enum, Attribution, `lastIpHash` SHA-256, Indizes auf `(status, createdAt desc)` / `(source, createdAt desc)`) | **als-vorlage** — Felder/Indizes-Muster übernehmen, aber tenant-scoped neu modellieren (siehe Lücken) |
| `apps/web/app/utils/leads/leads.db.server.ts` | DB-Helper für Inbox: `listLeads` (Filter status/source/search + Pagination), `listLeadsForExport` (Cap 50k), `getLead`, `updateLeadStatus`, `appendNote`, CSV-Export-Row-Typ | **als-vorlage** — Loader/Action-Plumbing-Muster ist direkt adaptierbar; Queries um `tenantId`-Scope + Permission-Filter (read_own/read_all) erweitern |
| `apps/web/app/routes/admin/marketing-leads/index.tsx` | Inbox-Listen-Route: Status-Badges als Filter-Shortcuts, Such-Box, Pagination, CSV-Export mit Audit-Event, `groupBy`-Status-Counts | **als-vorlage** — Strukturmuster für Loader→VM→UI; HiveGrid braucht Tenant-Route (`/{tenant}/leads`), Multi-Select-Filter, Bulk-Actions, View-Model-Adapter, i18n-Keys, Subframe-UI |
| `apps/web/app/routes/admin/marketing-leads/$id.tsx` | Lead-Detail: Status-State-Machine-Buttons (forward/back), Inline-Notes-Editor, LeadEvent-Activity-Timeline, Konversions-Flow | **als-vorlage** — Triage-Detail-Muster; HiveGrid-Übergänge (new/qualified/converted/lost/spam) + Promotion-Modal (Modul 1) abweichend |
| `apps/web/app/utils/leads/captureLead.server.ts` | Idempotenter Lead-Upsert: Trim/Blank-Fill-Semantik, `hashIp()` (SHA-256, kein Raw-IP), First-Touch-Merge, Event-Append | **als-vorlage** — Auto-Anlage-Pfad (Form/Mail/Phone/Manuell). `hashIp` 1:1; Upsert-Logik tenant-scoped + Kontakt-Match-Probe ergänzen |
| `apps/web/app/utils/leads/convertLead.server.ts` | Atomare Konversion in `$transaction` (5 Effekte: Update + Event + Acquisition + Outbox), Idempotenz via `dispatchKey`, Up-front-Check | **als-vorlage** — Promotion Lead→Kontakt (Modul 1) folgt demselben Transaktions-/Idempotenz-Muster; Ziel ist Contact statt Tenant |
| `packages/form-widget/src/honeypot.ts` (`isHoneypotTriggered`, `HONEYPOT_FIELD_KEY`) | Honeypot-Spam-Erkennung (stilles 204) | **1:1** — direkt für Anti-Spam-Heuristik „Honeypot gefüllt" (Spec 2.8.4) |
| `packages/form-widget/src/schema.ts` / `origin.ts` / `routing.ts` | Form-Definition-Zod-Schema, Origin-Allowlist, Submission-Routing (`generic`/`crm-contact`/`entity-row`) + Field-Mapping | **anpassen** — Quelle Form→Lead (2.2.1); Routing-Target um „Lead-Inbox" + Field-Mapping pro Routing-Regel (M048/M049) erweitern |
| `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) | Eingebettetes Formular + Submission-Inbox (`payload` JSON, `ipHash`, `status` received/processed/failed/spam, `config` Anti-Spam) | **anpassen** — Form-Submission ist Hauptquelle für Leads; `status=spam` koppelt an Spam-Heuristik. Form-Builder selbst = Modul 5 (M121-M125) |
| `packages/shared-store/src/helpers/rate-limit-fixed.ts` + `rate-limit-sliding.ts` | `createFixedWindowRateLimiter` / `createSlidingWindowRateLimiter` (Redis/Memory) | **1:1** — Hard-Limit pro Quelle/h (Default 100) und pro IP/h (Default 20) aus Spec 2.8.1/2.8.2 |
| `apps/worker/src/jobs/audit-retention.ts` | Täglicher Cron mit injizierten Seams (`tenantLister`/`eventDeleter`/`auditWriter`), Retention-Schwelle, meta-auditiertes Löschen | **als-vorlage** — DSGVO-Auto-Lösch-Job (Spam→30 Tage, Lost→90 Tage konfigurierbar, Spec 2.7); selbes Cron-+Seam-+Meta-Audit-Muster |
| `apps/worker/src/jobs/dsgvo-grace-cron.ts` + `outbox-done-retention-cron.ts` | Weitere Retention-/Grace-Cron-Muster | **als-vorlage** — Referenz für Auto-Lösch-Implementierung + Anonymisierungs-Trail (Spec 2.7.4) |
| `apps/web/app/utils/leads/leadsCsv.ts` (`serializeLeadsCsv`, `leadsCsvFilename`) + `packages/exports` | CSV-Serialisierung + Streaming-Export-Framework (CSV/JSON/XLSX/PDF, Plan-Row-Caps, Spreadsheet-Injection-Schutz) | **1:1 / anpassen** — Export gefilterter Auswahl + Statistik-Export (Spec 2.3.5/2.9.6, Permission `leads.admin`) |
| `packages/marketing-outbound` (`adapterRegistry`, `resolveAdapter`, slack/discord/mailchimp/hubspot/brevo/webhook) | Outbound-Adapter-Registry, dispatched via Outbox-Events | **als-vorlage** — Muster für Apps-Engine-Quellen-Adapter (2.2.5) und Routing-Notifications; HiveGrid braucht **inbound** Lead-Adapter (Meta/Google/Funnel), nicht outbound |
| `packages/realtime/src/{client,events,server,guards}.ts` | Realtime-Pub/Sub (WebSocket) | **1:1** — Live-Aktualisierung neuer Leads in der Inbox (Spec 2.3.7 / M047 „Real-Time-Updates via packages/realtime") |
| `packages/db/src/outbox.ts` (`publishOutboxEvent`, `OUTBOX_EVENT_TYPE_PATTERN`) | Transaktionales Outbox-Pattern (`<domain>.<entity>.<verb>`, `dispatchKey @unique`) | **1:1** — `lead.created`-Event als Automation-Trigger (Spec Block I / Modul 17), Routing-Aktionen, Side-Effects |
| `packages/db/src/audit-hash.ts` + `prisma/schema/core.prisma` (`AuditEvent`) | Tamper-evidente Audit-Hash-Kette, `dataSensitivity`/`regulatoryScope[]` | **1:1** — Audit-Trail für Status-/Verantwortlichen-Wechsel, Bulk-Action, Hard-Delete (AV #6, Spec 2.11.5) |
| `prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncItem`) | Integrations-/Sync-Engine mit verschlüsselten Credentials + rollback-fähigen Sync-Runs | **als-vorlage** — Quellen-Adapter aus externen Marketing-Tools (Spec 2.2.5, M047 „Quellen-Adapter via Apps-Engine M008"). Modelle vorhanden, aber kein Service-/UI-Layer in `apps/web/app/modules` gefunden |
| `prisma/schema/permissions.prisma` (`Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser`) + `apps/web/app/utils/helpers/.server/PermissionsService` (`verifyUserHasPermission`) | RBAC-Fundament + Permission-Check-Helper | **1:1 / anpassen** — Permission-Bundle `leads.*` (read_own/read_all/write/delete/admin) als Daten seeden; `verifyUserHasPermission`-Muster für Route-Gates. Owner-Check-Filter (read_own) selbst zu bauen |
| `prisma/schema/notifications.prisma` + `packages/db` notifications-Modul | `NotificationDelivery`/`UserNotificationPreference`/`DeviceToken` (In-App/Email/Push) | **1:1** — Tenant-Admin-Alerts bei Anomalie/Auto-Pause/Hard-Limit (Spec 2.8.3, Block K) via `notify()` (M011) |
| `packages/db/src/dsgvo/{user-fk-map.ts, pseudonymize.ts}` | DSGVO-FK-Karte (CI-erzwungen) + Pseudonymisierungs-Helfer | **1:1** — Pflicht-Eintrag für jeden neuen User-FK am HiveGrid-Lead; Anonymisierung vor Hard-Delete (Spec 2.7.4) |
| `prisma/schema/imports.prisma` + `packages/imports` | Import-Job + Dry-Run/Dedupe-Framework | **als-vorlage** — nur für Phase 2 (CSV/JSON-Lead-Import, Spec 2.12.1) — in Phase 1 explizit Out-of-Scope |
---
## Vorhandene Daten-Modelle
Konkret in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
- **`marketingLeads.prisma`** — `Lead`, `LeadEvent`, `TenantAcquisition`, `MarketingIntegration`, Enum `LeadStatus`.
- `Lead`: `email @@unique` (GLOBAL, nicht pro Tenant), **kein `tenantId`** (operator-scoped per Design-Kommentar), `status LeadStatus @default(new)`, First-Touch-UTM-Attribution, `score`, `notes Json?`, `convertedToTenantId?`, `lastIpHash` (SHA-256), Indizes `@@index([status, createdAt(sort:Desc)])`, `@@index([source, createdAt(sort:Desc)])`.
- Enum `LeadStatus`: `new | contacted | qualified | trial | customer | churned | disqualified` — **funnel-/SaaS-Akquise-Semantik**, NICHT die HiveGrid-CRM-Semantik (`new | qualified | converted | lost | spam`).
- `LeadEvent`: append-only Timeline (`type` String, `actorId?`, `payload Json`).
- **`formWidget.prisma`** — `Form`, `FormSubmission` (Quelle „Formular" für Leads; `ipHash`, `status` received/processed/failed/spam, Anti-Spam-`config`).
- **`appsEngine.prisma`** — `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (externe Quellen-Adapter, Spec 2.2.5).
- **`permissions.prisma`** — `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` (Bundle `leads.*` + Group für Round-Robin).
- **`notifications.prisma`** — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` (Admin-Alerts).
- **`core.prisma`** — `AuditEvent` (Audit-Trail), `IdempotencyKey`.
- **`outbox.prisma`** — `OutboxEvent` (`lead.created`-Trigger, Side-Effects).
- **`accounts.prisma`** — `Tenant`, `User`, `TenantUser` (Tenant-Scope-Anker + Verantwortlicher-FK).
**Nicht vorhanden (kritisch):** Es gibt **kein tenant-scoped CRM-`Contact`/`Company`-Modell** in der Boilerplate. Das `crm`-Modul (`apps/web/app/modules/crm/`) enthält nur `services` (z.B. `CrmService.ts`, `crmContactSearch.server.ts`) — eine Integrations-Schicht zu EXTERNEN CRMs (ConvertKit etc.), kein eigener Contact-Datastore. Das Form-Widget-Routing-Target `crm-contact` upsertet entsprechend über diese externe Service-Schicht. Promotion Lead→Kontakt (Spec Block D/2.5) zielt auf das HiveGrid-eigene Contact-Modell aus **Modul 1 (M042-M046)** — das ebenfalls neu gebaut wird.
---
## Lücken / komplett neu zu bauen
1. **Tenant-scoped HiveGrid-Lead-Modell** — Der Boilerplate-`Lead` ist operator-scoped mit globalem `@@unique([email])`. HiveGrid braucht ein neues Modell (`tenantId` pflicht, FK auf `Tenant` mit `onDelete: Cascade`, `assigned_to_user_id`, Status-Enum `new/qualified/converted/lost/spam`, `source`, `message`, `metadata` JSON für Quellen-Detail). Geplanter Ort: `prisma/schema/app.prisma` (HiveGrid-Platzhalter). FK→User in `user-fk-map.ts` eintragen (CI-Pflicht). Indizes laut Spec: `(tenant_id, status, created_at desc)`, `(tenant_id, assigned_to_user_id, status)`, Trigram auf `email`/`phone`/`last_name`.
2. **Lead-Status-State-Machine (HiveGrid-Semantik)** — Übergangs-Matrix aus Spec Block F (inkl. `converted`-Lock, Re-Engagement `lost↔qualified`, False-Positive `spam→qualified`, Begründungs-Pflicht bei `lost`). Boilerplate-State-Machine (`new→…→customer/churned`) ist semantisch anders → neu.
3. **Permissions-aware Owner-Check-Filter (`read_own` vs `read_all`)** — Server-side-Filter, der nicht-eigene Leads in Listen/Statistik/Bulk ausblendet (AV #5). RBAC-Tabellen + `verifyUserHasPermission` vorhanden, aber der scope-bewusste Query-Filter + Bundle `leads.*`-Seed sind neu.
4. **Multi-Select-Filter + Bulk-Actions + gemischte-Rechte-Pre-Check** — Boilerplate-Inbox hat nur Single-Status-Filter + Such-Box, keine Bulk-Auswahl. Neu: Multi-Select (Status/Quelle/Verantwortlicher inkl. „Nicht zugewiesen"/Tags/Custom-Felder), Date-Range, Toggles „Spam ausblenden"/„Konvertierte einblenden", Bulk-Assign/Status/Tag/Spam/Hard-Delete/Export, Pre-Check mit Klartext-Übersprungen (Spec 2.10.1).
5. **Lead-Routing pro Quelle (M048)** — Routing-Regel-DSL mit Bedingungs-Kombinatoren, Reihenfolge-Auswertung (erste Treffer-Regel), Round-Robin-State pro Gruppe, Status/Verantwortlicher/Tags-Default. Komplett neu (Apps-Engine + Outbox als Fundament).
6. **Auto-Verkaufsfall-Anlage (M049)** — Routing-Action, die aus Lead automatisch Verkaufsfall in Ziel-Pipeline anlegt mit Field-Mapping. Abhängig von Sales-Pipeline (M059/M060) — neu.
7. **Anomalie-Detection + Auto-Pause pro Quelle (M050)** — 10x-Rate-Spike-Erkennung → Quelle pausieren + Notification. Rate-Limiter (fixed/sliding) als Baustein vorhanden, aber Anomalie-Heuristik + Quellen-Pause-State + Klartext-Notification neu (M010 Apps-Engine-Webhook-Schutz als Re-Use-Referenz).
8. **DSGVO-Auto-Lösch-Job mit Lead-Semantik** — Cron-Muster (`audit-retention.ts`) als Vorlage, aber Lead-spezifisch: Spam→30 Tage, Lost→90 Tage (tenant-konfigurierbar, 0=nie), anonymisierter Activity-Trail + Audit-Eintrag, Klartext-Hinweis „wird gelöscht am [Datum]".
9. **Lead-Statistik-Seite (M051 / Spec Block H)** — KPI-Kacheln (Konversionsraten, Reaktionszeit, Spam-Quote, offene Leads), Aufschlüsselungen (Quelle/Verantwortlicher/Tag/Wochentag), Trend-Charts, Vorperioden-Vergleich, Drill-Down. Aggregat via Materialized-View/Cron-Tabelle. Komplett neu — Boilerplate hat kein Lead-Statistik-Dashboard.
10. **Quellen-Verwaltung-UI** (`/admin/lead-sources`) + **Anti-Spam-Settings-UI** (`/admin/lead-anti-spam`) — Custom-Quellen (Name/Default-Verantwortlicher/Default-Tags), Hard-Limits-Toggles, Heuristik-Schalter. Neu.
11. **Kontakt-Match-Probe + Duplikat-/Soft-Match-Marker** — Inline-Match-Check beim Tippen (Spec 2.2.4), Marker „Mögliches Duplikat"/„Spam-Verdacht"/„Auto-promoviert" (2.3.2). Abhängig vom HiveGrid-Contact-Modell (Modul 1) — neu.
12. **App-Shell-Anbindung (HiveGrid)** — Sidebar-Eintrag „Lead-Inbox" in Gruppe ARBEITEN (INTEGRATION-CONTRACTS §1), Tenant-Routen `/{tenant}/leads*`, Breadcrumb, Mobile-Tab-Bar, View-Model-Konvention (M013), Subframe-Adapter (M015), i18n-Keys (M003). `packages/ui-hivegrid` existiert noch nicht; Boilerplate `packages/ui`/`ui-app`/`ui-subframe` sind Fundament/Vorlage.
13. **Gespeicherte Ansichten** (max. 5 Filter-Kombinationen pro User, Spec 2.3.8) + user-spezifische Spalten-Konfiguration — neu (Entity-Builder `EntityView` als konzeptionelle Vorlage, aber Lead ist eigenes Modell).
14. **Inbound-Quellen-Adapter (Meta/Google/Funnel)** — `packages/marketing-outbound` ist OUTBOUND. Für 2.2.5 braucht es INBOUND-Adapter über Apps-Engine — Registry-Muster übertragbar, Implementierungen neu.
---
## Empfohlenes Vorgehen
**Phase 0 — Fundament 1:1 übernehmen (kein neuer Code, nur verdrahten):**
1. Querschnitt aktivieren: `packages/db/src/outbox.ts`, `audit-hash.ts` + `AuditEvent`, `notifications`, `permissions` + `verifyUserHasPermission`, `realtime`, `shared-store` Rate-Limiter, `exports`/CSV. Diese stehen für alle 5 Milestones bereit.
2. `hashIp()` aus `captureLead.server.ts` und `isHoneypotTriggered` aus `form-widget` direkt einziehen.
**Phase 1 — Eigenes tenant-scoped Lead-Modell (M047):**
3. HiveGrid-`Lead`-Modell in `prisma/schema/app.prisma` neu definieren (NICHT den marketing-`Lead` wiederverwenden) — `marketingLeads.prisma` als Feld-/Index-Vorlage nehmen, tenant-scopen, Status-Enum auf HiveGrid-Semantik. `user-fk-map.ts` ergänzen.
4. DB-Helper nach Muster `leads.db.server.ts` bauen, aber mit `withTenantScope()` + Owner-Check (M004).
5. Quellen-Auto-Anlage (Form/Mail/Phone/Manuell) nach Muster `captureLead.server.ts` + Apps-Engine-Schema; `lead.created`-Outbox-Event publizieren; Realtime-Push.
**Phase 2 — Listen/Detail/Triage-UI + Permissions (M051-Teil):**
6. Inbox-Route nach Muster `admin/marketing-leads/index.tsx`, aber Tenant-Route + Multi-Select-Filter + Bulk-Actions + View-Model-Adapter + Subframe + i18n.
7. Detail-/Triage-Route nach Muster `$id.tsx`; HiveGrid-State-Machine + Promotion-Modal (Modul 1) + Activity-Stream (M045).
8. Permission-Bundle `leads.*` seeden + scope-bewusste Filter.
**Phase 3 — Routing + Auto-Verkaufsfall (M048, M049):**
9. Routing-Regel-DSL + Round-Robin (neu, Outbox/Apps-Engine als Basis); Auto-Verkaufsfall als Routing-Action (nach Sales-Pipeline M059/M060).
**Phase 4 — Spam/DSGVO (M050):**
10. Rate-Limiter (fixed/sliding) für Hard-Limits; Anomalie-Detector (neu, M010-Webhook-Schutz als Re-Use); Auto-Lösch-Cron nach Muster `audit-retention.ts`/`dsgvo-grace-cron.ts` mit Lead-Semantik + Anonymisierung.
**Phase 5 — Statistik + Admin-UIs (M051-Rest):**
11. Statistik-Page (komplett neu) + Quellen-Verwaltung + Anti-Spam-Settings-UI.
**Faustregel:** Querschnitt (Outbox/Audit/Notif/Permissions/Realtime/Rate-Limit/Export/Honeypot) = 1:1. Daten-Modell + Status-Logik + Listen/Statistik/Routing/Spam-Domäne = neu, aber mit den genannten Boilerplate-Dateien als konkrete Code-Vorlage. **Nicht** den marketing-`Lead` mitbenutzen — Scope-Inkompatibilität.
@@ -0,0 +1,219 @@
# Boilerplate-Abgleich: M03 — Sales-Pipeline (Verkaufsfälle / Deals)
> Abgleich-Report: Was liefert die Boilerplate (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`)
> für M03 fertig, was muss angepasst werden, was fehlt komplett.
> Quellen: Detail-Spec `_bmad-output/specs/M03-sales-pipeline.md`, Pflichtenheft `block3.md` (3.1–3.13),
> Milestones M059–M064, `AGENTS.md`, `INTEGRATION-CONTRACTS.md`, Boilerplate-Inventur.
> Eigene Greps/Reads in der Boilerplate verifiziert (keine Inventur-Blind-Übernahme).
| Feld | Wert |
| --- | --- |
| Modul-ID | M03 |
| Name | Sales-Pipeline (Verkaufsfälle / Deals) |
| Milestones | M059 (Pipeline-Konfig + SHK-Seed), M060 (Verkaufsfall-CRUD + Pflicht-Vertriebler), M061 (Kanban-UI + Drag&Drop), M062 (Verlust/Gewinn-Gründe), M063 (Auto-Auftragsprojekt + Setter-Closer), M064 (Reporting + Stuck/Auto-Archiv + KWP-Sync) |
| Block | Block 3 — Workflow-Kern (Vertrieb & Auftrag) |
| Reuse-Level | **low** (solides Querschnitt-Fundament + Bau-Vorlagen, aber **kein** Sales-Domänen-Modell vorhanden — Datenkern komplett neu) |
---
## Kernbefund (Realität)
- **Es existiert KEIN Sales-/Deal-/Pipeline-Datenmodell in der Boilerplate.** Grep über `prisma/schema/*.prisma`
nach `Deal|Pipeline|Stage|Forecast|Kanban|SalesPipeline` liefert **null Treffer** bei Modellen. Treffer für
`Lead`/`LeadEvent` betreffen das **marketing-scoped** `Lead`-Modell (operator-scoped, NICHT tenant-scoped,
`email @unique`) — das ist die M01/M02-Funnel-Welt, nicht der tenant-scoped Verkaufsfall aus M03.
- **Es existiert KEIN zentrales `Activity`-Modell** wie es M03 (`DealActivity` → zentrale `Activity` aus M1)
und `INTEGRATION-CONTRACTS §5` (`logActivity`) verlangen. Vorhanden sind nur `LeadEvent` (Lead-Timeline,
`marketingLeads.prisma`) und `RowComment`/`Entity.hasActivity`-Flag im EntityBuilder — kein generischer,
cross-entity Activity-Stream. → M045 (Activity-Service) ist Vorbedingung und muss separat existieren.
- **HiveGrid-Cloud-Repo enthält derzeit noch KEINEN Boilerplate-Code** (`packages/`, `apps/`, `prisma/schema/`
sind leer/abwesend; nur `docs/`, `_bmad*`, leeres `prisma/`). Der Abgleich erfolgt also gegen das separate
Boilerplate-Repo; die Übernahme = Code aus Boilerplate als Fundament + neue Sales-Schicht darauf.
- **Das stärkste vorhandene Sales-nahe Asset ist der EntityBuilder** (`board`-View = Kanban, `groupBy`, Row/Property/
Tag/Task/Comment/RowPermission, Custom-Felder). Er ist als **Vorlage/Pattern** sehr wertvoll, aber für ein
Kern-Vertriebsmodul mit Pflicht-FKs (Kontakt/Firma/Lead/Projekt), Stage-Probabilities, Won/Lost-Reverse-Window,
Forecast und Field-Level-Volumen-Permissions **nicht 1:1 als Datenmodell tauglich** (LP-4: Commodity sauber bauen,
kein Über-Engineering über generischen No-Code-Layer).
---
## Übernehmbar aus Boilerplate
### Querschnitt / Foundation (1:1 nutzbar)
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/foundation/src/permissions.ts` | `withTenantScope()`, `withPermission()`, `withOwnerCheck()`, `requirePermission()`; 404-statt-403 bei Deny | 1:1 — deckt Block I (read_own/read_all, 404 für nicht-eigenen Deal, Stage-Change-Gate) |
| `packages/foundation/src/audit.ts` | `auditEvent()`, `withAuditMiddleware()` (`AuditEvent`-Hash-Kette) | 1:1 — AV #6 Audit-Default für Stage-Wechsel u. a. (S/W außerhalb Prisma manuell) |
| `packages/foundation/src/notifications.ts` | `notify()`, `bundleNotifications()`, Preference-Check, i18n-Key-Zwang | 1:1 — `deal.won`/`deal.stuck`-Notifications (INTEGRATION-CONTRACTS §7) |
| `packages/foundation/src/errors.ts` | `CatalogError`, `foundationErrors`, `toPinoLogObject` | 1:1 — Klartext-Diagnostik (3.13, LP-10): Stage-Validation, Stuck, Won/Lost-Confirm |
| `packages/foundation/src/idempotency.ts` | `withIdempotency()` | 1:1 — idempotente Deal-Anlage aus Lead/Form/Email/Anruf/Automation (3.7) |
| `packages/foundation/src/flags.ts` + `packages/feature-flags/*` | Feature-Flag-Engine (defineFlag/evaluateFlag, React-Hooks) | 1:1 — DoD „Modul ohne Deploy abschaltbar"; Sidebar-`feature_flag` |
| `packages/view-models/src/index.ts` | `VMState`, `ActionCallbacks`, `RegistryGate`, `SidebarRegistryItem`, `assertI18nLabel` | 1:1 — VM-Layer-Vertrag (AGENTS A.1–A.5, INTEGRATION §11/§13) |
| `packages/i18n/src/index.ts` | Locales (de/en), `formatCurrency`/`formatNumber`/`formatDate`, ICU, `useTranslate` | 1:1 — Volumen-/Datum-Formatierung, i18n-Keys `sales.*` |
| `packages/logger`, `packages/observability`, `packages/error-reporter`, `packages/metrics` | Pino-Redaction, PII-Span-Scrub, Sentry, prom-Counter | 1:1 — Logging/Tracing/Error-Querschnitt |
| `packages/url/src/canonical.ts` | `appPath`/`appUrl` host-aware | 1:1 — Deal-Routes/Links (`/deals/...`) |
| `packages/db/src/client.server.ts` | `getReadDbClient()` (Replica) / `getWriteDbClient()` / `getExtendedDbClient()` | 1:1 — Read-heavy Kanban/Listen via Read-Replica (Performance-Anforderung Block D) |
| `packages/db/src/transactions.server.ts` + `packages/db/src/outbox.ts` | `runDbTransaction()`, `publishOutboxEvent()` (atomic Side-Effects) | 1:1 — Stage-Wechsel + Activity + Notification + Automation-Trigger transaktional (`deal.stage_changed`, `deal.won`) |
| `packages/db/src/dsgvo/user-fk-map.ts` | Pflicht-Karte aller User-FKs (CI-Gate) | anpassen — neue Deal-FKs auf `User` (`created_by`, `assigned_to`) MÜSSEN ergänzt werden, sonst bricht CI |
### Apps / Infra (1:1 / als-Vorlage)
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `apps/worker/src/jobs/*` + `apps/worker/src/group-runtime.ts` | BullMQ-Cron-Pattern (single-instance, Gruppen, DI `HandlerDependencies`) | als-vorlage — Daily-Cron für Stuck-Detection (3.8.1/3.8.2), Auto-Archiv Won 30d / Lost 90d (3.8.3/3.8.4, M064) |
| `apps/worker/src/outbox/{dispatcher,event-router}.ts` | Outbox-Dispatcher (FOR UPDATE SKIP LOCKED) + Prefix-Routing | anpassen — neues Prefix `deal.` / `sales.` in `DEFAULT_OUTBOX_ROUTING` für Automation-Trigger (3.6/H/M075) |
| `packages/queue/src/*` | Queue-Namen, typisierte Producer, `buildIdempotentJobId`, Plan-Prioritäten | 1:1 — Cron-/Job-Infrastruktur für Stuck/Archiv/Forecast-Cache |
| `packages/realtime/src/{events,server,client}.ts` | SSE-Serialisierung + Client/Server-Helfer | anpassen — Live-Kanban-Updates (3.4.11, M061). **Achtung:** Boilerplate hat **nur SSE, kein WebSocket** — der „WebSocket vs SSE"-Offene-Punkt der Spec ist faktisch auf **SSE** zu entscheiden; `REALTIME_EVENT_NAMES` um Deal-Events erweitern |
| `packages/exports/src/csv/*` + `packages/exports/src/limits.ts` + Worker `export.ts` | CSV-Export (Streaming, Plan-Row-Caps, Injection-Safety) | 1:1 — CSV-Export gefilterter Deals (3.4.10, M061) |
| `packages/search/src/schemas/` (`crm-contacts.ts`, `rows.ts` als Muster) + `outbox-publisher.ts` | Meilisearch tenant-scoped Index + Outbox-Reindex | als-vorlage — neues Index-Schema `deals` (Titel/Description/Kontakt-/Firmen-Name, 3.4.5); Registrierung in `indexed-entities.ts` (INTEGRATION §8) |
### UI / App-Shell (als-Vorlage / anpassen)
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `apps/web/app/components/layouts/sidebars/shadcn/*` + `apps/web/app/application/sidebar/{AppSidebar,SidebarItem}.tsx` | Datengetriebene Sidebar mit Permission-/Feature-Gating, `data-ui-id` | als-vorlage — Sidebar-Eintrag „Verkaufsfälle" (Gruppe ARBEITEN) + „Pipelines" (Gruppe EINSTELLUNGEN); HiveGrid nutzt `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (neu) |
| `apps/web/app/components/ui/*` (shadcn/Radix: table, tabs, dialog, sheet, drawer, badge, card, command, multi-select, pagination, calendar) | Primitive-Bibliothek (~707 Komponenten) | 1:1 / als-vorlage — Deal-Detail-Tabs, Bulk-Select, Filter-Bar, Confirm-Dialoge (Won/Lost), Listen-Tabelle |
| `apps/web/app/components/ui/tables/*` (`TableNew`, `TablePagination`, `ColumnSelector`, `RowsLoadMoreCard`) | Tabellen-Bausteine: Cursor-Pagination, Spalten-Konfig, „Mehr laden" | 1:1 — Listen-View (3.4.8 Spalten-Konfig pro User, Cursor-Pagination, Default „zuletzt geändert" |
| `apps/web/package.json` → `@dnd-kit/core` 6.3.1, `@dnd-kit/sortable`, `@dnd-kit/utilities` | Drag&Drop bereits als Dependency vorhanden | 1:1 — Kanban-D&D (3.4.3, M061) **und** Pipeline-/Stage-Reorder (3.2.7, M059). Hinweis M061 nennt `react-beautiful-dnd` — faktisch ist **@dnd-kit** vorhanden, das nutzen |
| `apps/web/app/modules/formWidget/builder/{Canvas,SortableField,palette}.tsx` | Drag&Drop-Sortier-Editor (SortableField) als konkretes @dnd-kit-Beispiel | als-vorlage — Stage-Liste-Reorder im Pipeline-Editor (M059) |
| `packages/ui-mock/src/index.ts` (`MockPage`, `generateMockArtifacts`) + `apps/web/.../hot-swap/HotSwapPageRenderer.tsx` | Hot-Swap-Drill + Visual-Snapshot-Fundament | 1:1 — DoD Hot-Swap-Drill (M017) + Visual-Regression (M016) für Kanban/Detail |
| `apps/storybook/*` (lost-pixel, axe a11y, i18n-Decorator) | Visual-Regression + a11y-Gate | 1:1 — Snapshot der Hauptansicht (M016) |
### Domänen-nahe Bau-Vorlagen (als-Vorlage)
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/entityBuilder.prisma` — `EntityView` (`layout="board"`, `groupByPropertyId`, `pageSize`, `EntityViewFilter`/`Sort`/`Property`) | Generische Kanban/Board-View-Konfiguration | als-vorlage — Pattern für Stage-Spalten + Filter/Sort/Spalten-Konfig (NICHT als Deal-Datenmodell übernehmen) |
| `prisma/schema/entityBuilder.prisma` — `Property` + `PropertyOption`/`PropertyAttribute` (typisierte Custom-Felder, `applicable_to` via `entityId`) | Custom-Felder mit Typen/Optionen | anpassen — Deal-Custom-Felder „Anlagen-Typ"/„Wärmebedarf kW"/„Bestandsanlage" (3.1.14, Block H). Entweder über EntityBuilder koppeln (`applicable_to=deal`) oder eigene schlanke Deal-Custom-Field-Tabelle |
| `prisma/schema/entityBuilder.prisma` — `RowTag`/`EntityTag`, `RowTask`, `RowComment` | Tags / Aufgaben-Link / Notizen an Rows | als-vorlage — Deal-Tags (3.1.13), Deal↔Task-Link (M26/3.9.1), Notizen |
| `packages/db/src/rows.server.ts` — `getNextRowMutationNumber()` / `Row.folio` (`aggregate _max.folio + 1`, tenant+entity-scoped) | Fortlaufende Nummer pro Tenant/Entity | als-vorlage — Sequenz-Mechanik für `HiveNumberSeq` / `deal_number`. **Lücke:** kein Prefix-/Format-Layer (`D-2026-0042`), keine konfigurierbare Reset-Strategie — neu zu bauen (M060) |
| `prisma/schema/marketingLeads.prisma` — `Lead` + `LeadEvent` (Timeline, `convertedToTenantId`) | Lead-Modell + Event-Timeline (operator-scoped) | als-vorlage — Lead→Deal-Promotion-Wiring (3.7.2, Block H/M1). Achtung: dies ist das **Marketing-Lead**; M03 `lead_id` zeigt vermutlich auf das M01/M02-Lead-Konstrukt — Mapping mit M01/M02-Team klären |
| `prisma/schema/helpDesk.prisma` — `Feedback`/`SupportTicket` (`archived`-/`status`-Muster) & `prisma/schema/entityBuilder.prisma` — `Row.deletedAt`/`ExportJob` (Soft-Archiv) | Soft-Archive-Muster (`archived_at` statt Hard-Delete) | als-vorlage — Deal/Pipeline/Stage/LostReason-Archivierung (3.2.3/3.3.4/3.8) |
| `apps/api/src/routes/entity-row-routes.ts` + `route-access-inventory.ts` | REST-CRUD + Auth-Klassen-Matrix | als-vorlage — falls Deals über Public-API exponiert werden (INTEGRATION §3 `api/v1`) |
| `apps/web/app/utils/services/.server/*` + `application/dtos/*` Muster | Service-/DTO-/View-Model-Schichtung (SaasRock-Stil) | als-vorlage — Struktur für `app/domain/sales/*`, `view-models/sales/*.vm.ts` |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
Direkt für M03 **wiederverwendbar/anbindbar** (kein Deal-Modell darunter):
| Modell | Pfad | Rolle für M03 |
| --- | --- | --- |
| `Tenant`, `User`, `TenantUser` | `prisma/schema/accounts.prisma` | Tenant-Scope-Anker; `assigned_to_user_id`, `created_by_user_id`, Vertriebler-Pflicht [N6] |
| `Role`, `Permission`, `RolePermission`, `UserRole`, `Group` | `prisma/schema/permissions.prisma` | RBAC-Fundament für `deals.*`-Bundles (Block I) — neue Permission-Keys einseeden |
| `AuditEvent` | `prisma/schema/core.prisma:55` | Audit-Trail Stage-Wechsel (Hash-Kette, AV #6) |
| `IdempotencyKey` | `prisma/schema/core.prisma:84` | Idempotente Deal-Anlage aus Quellen (3.7) |
| `FileObject` / `FileUploadProgress` / `FileChunk` | `prisma/schema/core.prisma` | Verknüpfte Files am Deal (Block E, Won-Handoff-Files) |
| `NotificationDelivery`, `UserNotificationPreference` | `prisma/schema/notifications.prisma` | `deal.won`/`deal.stuck`-Notifications |
| `OutboxEvent` | `prisma/schema/outbox.prisma` | Atomic Side-Effects (Stage-Change → Activity/Notify/Automation) |
| `FeatureFlag` (+ Filter/Audit) | `prisma/schema/featureFlags.prisma` | Modul-Kill-Switch |
| `Form`, `FormSubmission` | `prisma/schema/formWidget.prisma` | Quelle „Deal aus Form" (3.7.3) + `DealForm`-Verknüpfung (Block A) |
| `Lead`, `LeadEvent` | `prisma/schema/marketingLeads.prisma` | Lead-Origin-Bezug (`lead_id`), Promotion-Pattern (3.7.2) |
| `Entity`/`EntityView`/`Property`/`Row`/`RowTag`/`RowTask`/`RowComment`/`RowPermission` | `prisma/schema/entityBuilder.prisma` | NUR als Pattern/optionale Custom-Feld-Kopplung — nicht als Deal-Kernmodell |
| `ExportJob` (+ Enum) | `prisma/schema/queue.prisma` | CSV-Export-Job-Tracking |
**Ablageort für die neuen HiveGrid-Modelle:** `prisma/schema/app.prisma` ist der vorgesehene leere Platzhalter
(`// custom database models`) — dort gehören `Pipeline`, `PipelineStage`, `Deal`, `DealActivity`/`Activity`,
`DealForm`, `LostReason`/`WinReason`, `HiveNumberSeq` hinein (bzw. eigene `sales.prisma`).
---
## Lücken / komplett neu zu bauen
**Datenmodell (komplett neu, kein Boilerplate-Äquivalent):**
- `Pipeline` (Multi-Pipeline ab Tag 1, `is_default`, `position`, `archived_at`) — 3.2, M059
- `PipelineStage` (`stage_kind open|won|lost`, `win_probability`, `auto_archive_after_days`, `color`, `position`)
+ Validierung „mind. 1 won + 1 lost" — 3.2.5/3.2.6, M059
- `Deal` (alle Pflicht-FKs: `contact_id` Pflicht, `company_id` optional, `lead_id`, `lost_reason_id`,
`won_handoff_project_id`, `volume numeric(12,2)`, `expected/actual_close_date`, `deal_number`) — 3.1, M060
- `LostReason` **und Gewinn-Gründe** (WinReason) — Tenant-pflegbar, archivierbar, Pflicht/Optional-Toggle pro
Liste [N8] — 3.3, M062 (in Boilerplate gar nichts)
- `HiveNumberSeq` mit `prefix`/`format` (`D-2026-0042`) + Reset-Strategie — 3.1.1, M060 (Boilerplate hat nur
`folio`-Counter ohne Format-Layer)
- **Zentrale `Activity`/`DealActivity`** mit Typen (`deal_stage_changed` inkl. `from/to_stage_id` +
`duration_in_previous_stage_seconds`, `deal_won`/`deal_lost`, …) — Block A/M045. **Vorbedingung M045 prüfen.**
**Domänen-Logik (neu):**
- Stage-Wechsel-Engine inkl. Vorwärts/Rückwärts (Klartext-Hinweis), Won/Lost-Confirm-Workflow,
**24h-Reverse-Window** (Soft-Revert vs. neue Stage-Activity — Offener-Punkt der Spec), `change_stage`-Gate — 3.5
- **Won-Handoff zu M4** (Projekt-Anlage, Feld-Mapping Deal→Projekt, Ziel-Pipeline-/Start-Stage-Wahl,
`won_handoff_project_id`, Mehrfach-Projekte aus einem Deal, Option A vs. B [N7], Wartung/Service kein Projekt [N9])
— 3.6, M063. Hängt an M065 (Auftragspipeline) — noch nicht vorhanden.
- **Setter-Closer-Termin-Anlage** mit konfigurierbarem Feld-Mapping Deal→Termin [N17] — 3.9.5, M063. Hängt an
M119/M25 (Calendar-Sync) — nicht vorhanden.
- **Forecast-Berechnung** (`volume × win_probability/100`, Zeitraum-Split, realisierter Umsatz),
Vertriebler-KPIs, Stage-Conversion-Rates, Lost-Reason-Verteilung + Aggregat-/Forecast-Cache — 3.10, M064.
Kein generischer KPI-Builder in Boilerplate für diese Sales-Metriken vorhanden.
- **Field-Level-Volumen-Permission-Redaction** (`read_volume_own/all`, `read_aggregates`) — Volumen „—" je Rolle
in Kanban-Karte/Detail/Liste/Aggregat — 3.11.2–3.11.4, Block I. Boilerplate kennt nur Object-Level + Row-Level
ACL (`RowPermission`), **kein** Field-Level-Redaction-Pattern → neu.
- **Stuck-Detection-Logik** + Stage-Verweildauer-Berechnung aus Stage-Change-Activities — 3.8, M064.
**UI (neu, auf Boilerplate-Primitiven aufbauend):**
- Kanban-Board-Komponente mit @dnd-kit (Spalten=Stages, Aggregat pro Spalte, Karten-Redaction, Live-SSE-Update,
„Mehr laden" pro Spalte ab 100+) — M061. (EntityBuilder-`board`-View ist nicht der HiveGrid-Kanban.)
- Pipeline-Switcher + „Nur meine Deals"-Quickfilter + Filter-Bar (Multi-Select) — M061
- Deal-Detail mit Stage-Pipeline-Komponente, Inline-Edit, Tab-Navigation, Klartext-Bannern (Won/Lost/Stuck/
Kontakt-archiviert) — Block E
- Pipeline-Editor (Stage-Liste D&D, Won/Lost-Validation-Anzeige) + Lost-/Win-Reason-Editor — M059/M062
- `packages/ui-hivegrid/` selbst existiert in der Boilerplate **nicht** (nur leerer `ui-subframe`-Stub +
Adapter-Metadaten in `@toolctrl/ui`) — der Adapter-Layer + Sidebar-/Breadcrumb-Config muss als HiveGrid-
Infrastruktur erst angelegt werden (Querschnitt M013–M017, nicht M03-spezifisch).
**Querschnitt-Wiring, das M03 voraussetzt, aber in Boilerplate fehlt:**
- `@hivegrid/activity` (`logActivity`, M045) — kein Äquivalent
- `packages/db/src/search/indexed-entities.ts` (M056) — existiert nicht (nur statische `search/schemas/*`)
- `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` / `breadcrumbs/` / `mobile/tab-bar.config.ts` /
`customer-portal/portal-shell.config.ts` (INTEGRATION §2/§4/§13/§14) — alle neu
- `packages/entitlements/src/permissions.ts`-Keys `sales.*`/`deals.*` (INTEGRATION §10) — neu zu definieren
**Integrationen mit anderen Modulen (out of M03-scope, aber harte Abhängigkeiten):**
- M4/M065 Auftragspipeline (Won-Handoff-Ziel) · M045 Activity · M042/M043 CRM-Kontakt/Firma · M048 Lead-Routing
(Default-Vertriebler) · M25/M119 Kalender (Setter-Closer) · M147 Dashboard (KPI-Widgets) · M5/M9/M12/M17
(Deal-Quellen) — keines davon in der Boilerplate fertig; M03 baut die **Hooks/Producer**, die Gegenseite separat.
---
## Empfohlenes Vorgehen (Reihenfolge)
1. **Fundament aktivieren (vor M03):** Boilerplate-Code als HiveGrid-Codebase übernehmen (AGENTS Pre-Flight),
Querschnitt-Pakete (`foundation`, `view-models`, `feature-flags`, `i18n`, `db`, `queue`, `realtime`, `exports`,
`search`, `logger`) 1:1 nutzen. Sicherstellen, dass die HiveGrid-Querschnitt-Milestones (M001 Audit,
M004 Permissions, M013–M017 UI/VM/Adapter/Hot-Swap, M045 Activity, M056/M057 Search) vorhanden sind —
M03 setzt sie laut DoD/INTEGRATION-CONTRACTS voraus.
2. **M059 — Daten + Pipeline-Konfig (neu, mit Vorlagen):** `Pipeline`/`PipelineStage` in `app.prisma`
(bzw. `sales.prisma`) neu modellieren. Stage-Reorder-UI via **@dnd-kit** (Vorlage: formWidget
`SortableField`/`Canvas`). Won/Lost-Validation als `CatalogError` (foundation/errors). SHK-Seed als
Konfig-Datei (Bauprinzip A.3) im Seed-Pfad (`prisma/seed.ts`-Muster). Soft-Archive-Pattern übernehmen.
`user-fk-map.ts` für neue User-FKs ergänzen (CI-Gate).
3. **M060 — Verkaufsfall-CRUD (neu):** `Deal` + `DealForm` modellieren; `HiveNumberSeq` neu (Sequenz-Mechanik
als-Vorlage aus `rows.server.ts:getNextRowMutationNumber`, Prefix/Format-Layer neu). Deal-Anlage-Quellen
über `withIdempotency` + Outbox. Pflicht-Vertriebler [N6] über `withOwnerCheck`/Default aus Routing.
Stage-Wechsel + 24h-Reverse transaktional (`runDbTransaction` + `publishOutboxEvent`). View-Model-Layer
(`view-models/sales/*.vm.ts`) + Smoke-Test + Hot-Swap-Drill (DoD).
4. **M061 — Kanban/Listen-UI (neu auf Primitiven):** Kanban mit @dnd-kit; Listen-View mit `TableNew`/
`ColumnSelector`/`TablePagination` (1:1). Live-Updates über `@toolctrl/realtime` (**SSE**, neue Deal-Events).
Server-side Filter (`getReadDbClient`). CSV-Export via `@toolctrl/exports`. **Field-Level-Volumen-Redaction
im VM-Builder** (neu) — Volumen „—" je Permission. Search-Index `deals` registrieren.
5. **M062 — Verlust/Gewinn-Gründe (neu, klein):** `LostReason`/`WinReason` (Soft-Archive, Pflicht/Optional-Toggle
pro Liste [N8]) + 5+5 SHK-Seeds + Aggregations-Auswertung (gehört konzeptionell zu M064-Reporting).
6. **M063 — Won-Handoff + Setter-Closer (neu, abhängig):** Erst nach M065 (Auftragspipeline) und M119/M25
(Kalender). Won-Handoff-Modal + Feld-Mapping Deal→Projekt + Option A/B [N7] + Wartung/Service-kein-Projekt [N9];
Setter-Closer-Termin mit konfigurierbarem Mapping [N17]. Automation-Trigger über Outbox-Prefix `deal.`.
7. **M064 — Reporting + Jobs (neu):** Forecast/KPIs/Conversion/Lost-Verteilung + Aggregat-/Forecast-Cache;
Daily-Cron (Stuck-Detection, Auto-Archiv Won 30d/Lost 90d) nach BullMQ-Cron-Pattern (Worker-Vorlage).
Optionaler KWP-Sync (Wartung ausgenommen [N9]) — externe Adapter-Schicht.
**Querschnitt-Entscheidungen, die die Spec offen lässt und durch Boilerplate-Realität präjudiziert sind:**
- Real-Time-Kanban: **SSE** (`@toolctrl/realtime`), **kein** WebSocket (in Boilerplate nicht vorhanden).
- Cache-Invalidierung Aggregate: über **Outbox/Pub-Sub** (`shared-store` DB-Index 2) bei Stage-Wechsel.
- Custom-Felder: Kopplung an EntityBuilder-`Property` (`applicable_to=deal`) prüfen vs. schlanke eigene Tabelle —
Entscheidung mit M044-Team (LP-4: kein Über-Engineering).
@@ -0,0 +1,148 @@
# Boilerplate-Abgleich — M04 Auftrags- / Projektpipeline
| | |
| --- | --- |
| **Modul-ID** | M04 |
| **Name** | Auftrags- / Projektpipeline (Geerkens-Kern) |
| **Milestones** | M065 (Pipeline-Konfig) · M066 (Auftrag-CRUD + KWP-Archiv) · M067 (Plantafel) · M068 (Mitglieder-Mgmt) · M069 (Abnahme-Workflow) · M070 (Material-Listen + Lager) |
| **Block** | Pflichtenheft Block 3, Abschnitt 4.1–4.14 |
| **Reuse-Level** | **low** (nur Fundament + Querschnitts-Bausteine + UI-Primitive nutzbar; KEINE Domänen-Modelle, kein Pipeline-/Kanban-/Plantafel-/Abnahme-Code vorhanden) |
| **Boilerplate-Wurzel** | `/Users/raffaelsheikh/Documents/GitHub/boilerplate` |
| **Verifiziert am** | 2026-06-04 (Greps/Reads direkt im Schema + package.json, nicht nur Inventur) |
## Kernbefund (Anti-Erfindung)
Die Boilerplate enthält **kein einziges Domänen-Modell** für dieses Modul. Grep über alle 27 `prisma/schema/*.prisma` (190 Modelle) liefert für `Project|Order|Auftrag|Pipeline|Stage|Schedule|Acceptance|Plantafel|Deal|Verkaufsfall|Contact|Kontakt|Company|Firma` → **NONE FOUND**. `prisma/schema/app.prisma` ist ein leerer Platzhalter (`// custom database models`). Alle M04-Entitäten (ProjectPipeline, ProjectPipelineStage, Project, ProjectMember, ScheduleEntry, AcceptanceProtocol, ProjectTemplate, ProjectForm) sind **komplett neu** zu modellieren.
Was vorhanden ist: ein generischer No-Code-EntityBuilder (mit `board`/`calendar`-View-Layout-Flag), die volle App-Shell + shadcn/Radix-Komponenten, DnD-/PDF-/Push-/Realtime-Libs, sowie das DB-Layer-Fundament (Outbox, Audit-Hash-Kette, Notification-Delivery, RBAC-Schema). Die HiveGrid-Querschnittsdienste (`logActivity` M045, `notify` M011, `withTenantScope`/`withPermission` M004) existieren **noch nicht** als Code — nur ihre DB-Bausteine.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/app.prisma` | Leerer Platzhalter für HiveGrid-eigene Modelle | **als-vorlage** — hier kommen ALLE M04-Modelle rein, ohne Boilerplate-Domänen zu berühren |
| `packages/db/src/client.server.ts` | `getDbClient` / `getWriteDbClient` / `getReadDbClient` / `getExtendedDbClient` | **1:1** — Read-Replica wichtig für Plantafel/Kanban (read-heavy) |
| `packages/db/src/transactions.server.ts` | `runDbTransaction` / `runDbTransactionBatch` | **1:1** — Project-Anlage + Channel + ScheduleEntries atomar |
| `packages/db/src/outbox.ts` | `publishOutboxEvent(tx, …)`, Event-Pattern `<domain>.<entity>.<verb>` | **1:1** — alle Side-Effects (KWP-Sync, Notifications, Auto-Chat, Calendar-Push, Mängel→Tasks) transaktional |
| `packages/db/src/audit-hash.ts` | Tamper-evidente Hash-Kette (`computeAuditHash`, `verifyAuditChain`) | **1:1** — Pflicht für AcceptanceProtocol (rechtssichere 6-Jahre-Aufbewahrung) |
| `packages/db/src/rows.server.ts` (`getNextRowMutationNumber`, `folio`-Aggregat) | Fortlaufende Nummern-Vergabe pro Tenant/Entity via `_max`-Aggregat | **als-vorlage** — Muster für `project_number` „P-2026-0042" (eigener Sequenz-Generator, da Project kein Row ist) |
| `packages/db/src/dsgvo/user-fk-map.ts` | Zentrale FK-auf-User-Karte (CI-Test erzwingt Vollständigkeit) | **anpassen** — Pflicht-Eintrag für jedes neue Modell mit `user_id` (ProjectMember, ScheduleEntry.assigned_user_id, AcceptanceProtocol.staff_signature_user_id …), sonst bricht CI |
| `prisma/schema/permissions.prisma` (`Role`/`Permission`/`RolePermission`/`UserRole`/`Group`/`GroupUser`) | RBAC-Schema inkl. Gruppen | **1:1** — Object/Field/Plantafel/Acceptance-Permissions hängen hier dran; `Group`/`GroupUser` deckt „Team Süd"-Gruppen-Add (4.10.2 / M068) ab |
| `prisma/schema/core.prisma` (`AuditEvent`, `FileObject`/`FileUploadProgress`/`FileChunk`) | Audit-Trail-Modell + Storage-Metadaten | **1:1** — Audit auto via M001-Middleware; FileObject für Baustellen-Fotos + Acceptance-PDF (M23/M052-M055) |
| `prisma/schema/notifications.prisma` (`NotificationDelivery`, `UserNotificationPreference`, `DeviceToken`) | In-App/Email/Push-Delivery + Geräte-Token (APNs/FCM/WebPush) | **1:1** — Push bei ScheduleEntry-Zuweisung / Stage-Wechsel / Mängeln (4.6.13.5 / 4.12.12) |
| `apps/worker/src/jobs/push-notification.ts` | Fertiger Push-Job (firebase-admin FCM + node-apn APNs + WebPush, pro `DeviceToken`) | **1:1** — Mobile-Push für Monteur |
| `prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`) | Integrations-/Sync-Engine mit Rollback-fähigen Sync-Runs + Source→Destination-Mapping | **anpassen** — Träger für KWP-Plantafel-Bidi-Sync (4.6.14, M094) + KWP-Dokumenten-Archiv (M066/M095); `AppSyncItem` modelliert die cross-System-ID-Zuordnung (4.6.14.2) |
| `packages/foundation/src/adapters.ts` (`defineAdapter`/`getAdapter`, Status-Lifecycle) | Adapter-Registry (von AGENTS.md als KWP-Adapter-Pfad genannt, LP-11) | **1:1** — KWP-Adapter-Kapselung (4.12.11) |
| `packages/queue/*` (`@toolctrl/queue`: factory, producers, priority, groups, names) | BullMQ-Wrapper inkl. Idempotenz-Hilfen | **1:1** — Plantafel-Pull-Fallback-Cron (4.6.14.3), PDF-Gen, Auto-Email, Auto-Archive-Jobs |
| `packages/shared-store/*` (`@toolctrl/shared-store`) | Redis-KV: Cache, Rate-Limit, Idempotenz | **1:1** — Aggregat-Cache für Wochen-/Monats-Plantafel (Perf-Anforderung 4.6), Sync-Idempotenz |
| `@hocuspocus/server` + `@hocuspocus/provider` (`packages/hocuspocus`) | Realtime-Server (WebSocket/Y.js) | **als-vorlage** — Realtime-Plantafel-Updates (Spec G „Realtime-Updates (WebSocket)") |
| `packages/exports/src/audit-pdf.ts` + `./pdf` (`@react-pdf/renderer` ^4.3.2) | PDF-Streaming-Renderer + S3-Multipart-Sink | **anpassen** — Acceptance-Protokoll-PDF (4.7.4.5); eigenes PDF-Template nötig, aber Renderer + S3-Sink 1:1 |
| `@dnd-kit/core` + `@dnd-kit/sortable` + `react-dnd` (Root-deps) | Drag-&-Drop-Bibliotheken | **1:1** — Kanban-Stage-Move (4.5.3) + Plantafel-Block-Move/Resize (4.6.4) |
| `apps/web/app/components/ui/calendar.tsx` + `date-fns` / `date-fns-tz` | Kalender-Primitive + Datums-Utils | **als-vorlage** — Plantafel-Raster (Tag/Woche/Monat) muss eigenes Grid bauen (kein react-big-calendar/fullcalendar vorhanden) |
| `apps/web/app/components/layouts/sidebars/shadcn/*` + `apps/web/app/application/sidebar/AppSidebar.tsx` + `SidebarItem.ts` | Datengetriebene Sidebar mit Permission-/Feature-Gating | **1:1 / anpassen** — Sidebar-Eintrag „Aufträge (Projekte)" (Gruppe ARBEITEN, INTEGRATION-CONTRACTS §1) |
| `apps/web/app/components/ui/tables/*` (`TableNew`, `TablePagination`, `ColumnSelector`) | Tabellen-Komponenten | **1:1** — Listen-View `/projects/list` (4.5.1) |
| `apps/web/app/components/ui/modals/*` (`ConfirmDialog`, `ActionResultModal`, `ErrorModal`) | Bestätigungs-/Ergebnis-Dialoge | **1:1** — Klartext-Confirms (Konflikt „Trotzdem zuweisen?", Storno-Grund-Pflicht, Hard-Delete-Block) |
| `apps/web/app/components/ui/{emptyState,loaders}` | Empty-/Loading-States | **1:1** — DoD-Pflicht (Empty/Loading-State mit Klartext) |
| `apps/web/app/components/ui/forms/*` + `.../editors` (Markdown/Rich) | Formulare + Editoren | **1:1** — Stammdaten-Edit, Markdown-Description |
| `apps/web/app/components/entities/{rows,views,properties}/*` + `EntityView.layout` (`board`/`calendar`) | No-Code-Board/Calendar-View-Engine | **als-vorlage** — Kanban-/Board-Render-Muster studieren; M04 braucht aber dedizierte relationale Modelle, NICHT generische Rows |
| `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) + `packages/form-widget` + Form-Builder UI (`apps/web/app/modules/formWidget/builder/*`) | Form-Builder + Submission-Inbox + Field-Mapping/Routing | **anpassen** — Acceptance-Form-Templates (Subtyp `acceptance_form`, 4.7.1) + „Projekt aus Formular" (4.4.4) bauen auf M5/M121 auf; Field-Mapping-Helfer (`applyFieldMapping`) wiederverwendbar |
| `prisma/schema/portals.prisma` + `apps/web/app/modules/portals/*` | Customer-Portal-System | **anpassen** — Kunden-Sicht auf Projekt-Status + Acceptance-PDF (4.12.9, M15/M141-M146) |
| `packages/view-models/*` (`VMState`, `ActionCallbacks`, `I18nLabel`, `assertI18nLabel`) | View-Model-Vertrag + i18n-Key-Zwang | **1:1** — M013-Layer-Pflicht (Loader baut VM, UI nur VM+Actions) |
| `packages/ui-app/*` (`createSidebarRegistry`/`createShellRegistries`, `generateA11yTest`) | Shell-Registry-Factories + a11y-Test-Template | **1:1** — Navigations-Wiring + a11y-Gate |
| `packages/ui-mock/*` + `packages/i18n/*` (de/en, `@toolctrl/i18n`) | Hot-Swap-Mock-Generator + i18n-Setup | **1:1** — Hot-Swap-Drill (M017) + i18n-Keys (M003), de Default |
| `prisma/schema/featureFlags.prisma` (`FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit`) | Feature-Flag-Engine | **1:1** — Modul ohne Deploy abschaltbar (DoD-Pflicht, M006) |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
**Direkt M04-relevant (Querschnitt + Träger):**
- `prisma/schema/app.prisma` — leerer Platzhalter, Ziel für alle M04-Modelle.
- `prisma/schema/accounts.prisma` — `User`, `Tenant`, `TenantUser`, `Group`-Bezug (Mitarbeiter, Mandanten-Scope, Mitglieder).
- `prisma/schema/permissions.prisma` — `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` (Berechtigungen 4.11 + Gruppen-Add 4.10.2).
- `prisma/schema/core.prisma` — `AuditEvent` (Hash-Kette → Acceptance-Compliance), `FileObject`/`FileUploadProgress`/`FileChunk` (Fotos + PDF), `IdempotencyKey`.
- `prisma/schema/notifications.prisma` — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` (Push 4.6.13.5 / 4.12.12).
- `prisma/schema/appsEngine.prisma` — `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (KWP-Bidi-Sync-Träger 4.6.14, Dokumenten-Archiv M066/M095).
- `prisma/schema/outbox.prisma` — `OutboxEvent` (transaktionale Side-Effects).
- `prisma/schema/featureFlags.prisma` — Feature-Flag-Gating.
- `prisma/schema/formWidget.prisma` — `Form`, `FormSubmission` (Acceptance-Forms / Projekt-aus-Form, via M5/M121).
**Als Pattern/Vorlage (NICHT direkt M04-Daten):**
- `prisma/schema/entityBuilder.prisma` — `Entity`, `Property`, `EntityView` (Layout-Flag `table|board|calendar|list|gallery`, Zeile 95), `EntityViewFilter/Sort`, `Row`, `RowValue`, `RowTag`, `RowTask`, `RowComment`, `RowPermission`, `RowMedia`. Generische No-Code-Engine — als Render-/Filter-/Board-Muster studierbar, ersetzt aber NICHT die dedizierten M04-Relationen.
**NICHT vorhanden (Beweis: Schema-Grep = NONE):** `Project`, `ProjectPipeline`, `ProjectPipelineStage`, `ProjectMember`, `ScheduleEntry`, `AcceptanceProtocol`, `ProjectTemplate`, `ProjectForm`, `Deal`/`Verkaufsfall`, `Contact`/`Kontakt`, `Company`/`Firma`, `Task`/`Aufgabe`.
---
## Lücken / komplett neu zu bauen
**Daten-Layer (alles neu, in `app.prisma`):**
- Alle 8 Kern-Entitäten der Spec Block A: ProjectPipeline, ProjectPipelineStage (inkl. `stage_kind`-Enum, `requires_acceptance_protocol`, `auto_archive_after_days`, `color`), Project (inkl. `project_number`-Sequenz, `source_deal_id` nullable, Baustellen-Adresse, `cancellation_reason`), ProjectMember (M:N + frei-textuelle Rolle), ScheduleEntry (Status-Enum, Index `(tenant_id, assigned_user_id, start_at, end_at)`), AcceptanceProtocol (nicht-löschbar, Signatur-Bilder, IP+Timestamp, `defects[]` JSON, `acceptance_kind`-Enum), ProjectTemplate, ProjectForm.
- Verfügbarkeits-Regeln pro MA (4.6.10 — `/admin/users/:id/availability`), neues Modell.
- Stage-Historie-Modell (4.8.1).
- Material-Listen-Modell (M070 — Position/Menge/Status; Phase 1 read-only aus KWP via M095).
**Domänen-Logik (neu, in `app/domain/**`):**
- Pipeline-Engine wird laut M065 aus M059 (Sales-Pipeline) wiederverwendet — beide sind HiveGrid-Milestones, NICHT Boilerplate. Reine Boilerplate-Wiederverwendung gibt es hier nicht.
- Stage-Wechsel-Validation (Acceptance-Pflicht-Block, Storno-Grund-Pflicht, 24h-Reverse-Window).
- Sequenz-Generator „P-YYYY-NNNN" (Muster aus `rows.server.ts` adaptierbar, aber eigene Implementierung).
- Konflikt-Detektor Plantafel (Doppel-Belegung, Urlaub/Krankheit aus M14, Verfügbarkeit, Arbeitszeit — 4.6.9).
- Acceptance-Workflow-State-Machine (Mängel-Klassifizierung → `acceptance_kind` → Folge-Aktionen 4.7.5; Mängel→Tasks-Auto-Erzeugung 4.7.5.2/4.12.15).
- Sales-Verlauf-View-Model-Composition (read-only Snapshot aus Deal, Field-Level-Volumen-Gate — 4.8.4).
- Auto-Projekt-Chat-Lifecycle (4.10.3/4.12.7, hängt an M104).
- Auto-Archive-Jobs (90/30 Tage) + Stuck-Detection.
**UI (neu, in `packages/ui-hivegrid/**` via Subframe-Adapter):**
- Kanban-Board mit Project-Karten (DnD via @dnd-kit vorhanden; Karten-/Board-Layout neu).
- **Plantafel-Grid** (Y=Mitarbeiter, X=Zeit, Resize+Move, Konflikt-Indikatoren, Zoom) — größte UI-Lücke; KEIN react-big-calendar/fullcalendar in der Boilerplate, nur `calendar.tsx`-Primitive + date-fns. Eigenes Grid (ggf. @xyflow/react oder Custom).
- Project-Detail mit Tab-/Sektions-Navigation, visueller Pipeline-Komponente, Activity-Stream.
- Mobile-first Acceptance-Workflow (mehrschrittig, Foto-Kamera-Upload, Touch-Signatur).
- Mobile „Meine Termine heute" / „Meine Woche" (4.6.13).
**Querschnitt-Dienste (noch nicht als Code in BP — HiveGrid-Milestones):**
- `logActivity` (M045) — Grep: keine Implementierung in BP.
- `notify({…})` (M011) — kein standalone `@toolctrl/notifications`-Paket; nur DB-Modelle + Worker-Job. Service-Fassade neu.
- `withTenantScope()` / `withPermission()` (M004) — Permission-Filter-Fassade neu (RBAC-Schema vorhanden, Filter-Logik nicht).
- i18n-Keys-Namespace `projects.*` neu (M003-Build-Lint blockt sonst).
**Externe Lib, die FEHLT und ergänzt werden muss:**
- **`signature_pad`** — NICHT in der Boilerplate (Grep über alle package.json = NONE). **Die Behauptung im M069-PLAN.md „`signature_pad` ist in Boilerplate-Deps" ist falsch** und muss korrigiert werden (Dependency neu hinzufügen für Touch-Signatur 4.7.4.3/4.7.4.4).
- **`firebase-admin` / `node-apn`** — der Push-Worker-Job referenziert sie; Verifizieren, dass die SDKs tatsächlich installiert sind (Job-Header nennt sie, aber als optionale Adapter).
**Integrationen, die auf andere HiveGrid-Milestones warten (keine BP-Lücke i.e.S.):**
- KWP-Bidi-Sync (M094/M095, LP-11) · Calendar-Sync M25/M119 · Email-Versand M092 · Whisper-Transkription M18 · HR-Hub-Konflikte M14/M129/M135.
---
## Empfohlenes Vorgehen
**Phase 0 — Fundament aus BP übernehmen (vor jedem Modul-Code):**
1. M04-Modelle in `prisma/schema/app.prisma` modellieren (NICHT EntityBuilder-Rows nutzen — dedizierte Relationen wegen Deal-/Contact-/User-FKs, Sequenznummer, Field-Level-Volumen, rechtlicher Aufbewahrung). Forward-Only-Migration mit Inverse-SQL-Kommentar.
2. Für jedes neue Modell mit `user_id` SOFORT Eintrag in `packages/db/src/dsgvo/user-fk-map.ts` (sonst CI-Block). AcceptanceProtocol als `retain-tombstone` (6-Jahre-Pflicht), nicht `hard-delete`.
3. DB-Zugriff über `getDbClient`/`getReadDbClient` + `runDbTransaction`; alle Side-Effects über `publishOutboxEvent`.
**Phase 1 — Pipeline-Konfig (M065):**
4. Pipeline-/Stage-Modelle + SHK-Default-Seeding (3 Pipelines, LP-3-Branchen-Template). RBAC-Permissions (`projects.*`, `plantafel.*`, `acceptance.*`) in `permissions.prisma`-Seed registrieren.
5. ProjectTemplate-Modell + Admin-UI (shadcn-Forms aus BP).
6. Sidebar-Eintrag „Aufträge (Projekte)" (Gruppe ARBEITEN) + Settings-Eintrag „Pipelines" via `sidebar.config.ts` / `AppSidebar.tsx`-Muster.
**Phase 2 — Auftrag-CRUD + Detail (M066):**
7. Project-CRUD, Sequenz-Generator (Muster `rows.server.ts`), Kanban + Liste (DnD via @dnd-kit, Tabellen aus BP). Stage-Wechsel-Validation.
8. Project-Detail-VM (View-Model-Composition inkl. read-only Sales-Verlauf mit Volumen-Gate). FileObject-Anbindung für Fotos.
9. KWP-Dokumenten-Archiv über `appsEngine` + `defineAdapter` (M095).
**Phase 3 — Mitglieder (M068, blockt Plantafel):**
10. ProjectMember + Gruppen-Add über `Group`/`GroupUser` (BP) + Auto-Chat-Channel (M104).
**Phase 4 — Plantafel (M067, größter Neubau):**
11. Eigenes Calendar-Grid (kein BP-Fertigbaustein) mit DnD-Resize/Move. Konflikt-Detektor. Read-Replica + shared-store-Aggregat-Cache für Perf. Hocuspocus für Realtime. Push via vorhandenem Worker-Job + DeviceToken.
**Phase 5 — Abnahme (M069):**
12. **Zuerst `signature_pad` als Dependency ergänzen** (fehlt!). Acceptance-Form auf Form-Builder (M5/M121). Mobile-Workflow. PDF via `@react-pdf/renderer` + `packages/exports`-S3-Sink (eigenes Template). Audit-Hash-Kette für Manipulationssicherheit. Mängel→Tasks (M073). Auto-Email (M092).
**Phase 6 — Material/Lager (M070):**
13. Material-Listen-Modell; Phase 1 read-only KWP-Daten via M095/appsEngine; Lagerist-Permission-Cluster (M023.1).
**Querschnitt durchgängig:** `logActivity` (M045), `notify` (M011), `withTenantScope`/`withPermission` (M004), i18n `projects.*` (M003), Feature-Flag (M006), VM-Layer (M013), Subframe-Adapter (M015) — alle als HiveGrid-Querschnitt nutzen, NICHT im Modul nachbauen (PR-Block sonst).
@@ -0,0 +1,118 @@
# Boilerplate-Abgleich — M05 Form-Builder
| Feld | Wert |
| --- | --- |
| Modul-ID | M05 |
| Name | Form-Builder (Formular-Werkstatt) |
| Milestones | M121 (Editor), M122 (Veröffentlichung/Sharing/Embed), M123 (Submission-Eingang/CRM-Aktionen), M124 (Conditional-Display), M125 (Rate-Limit/Captcha/DSGVO/SHK-Vorlagen) |
| Pflichtenheft-Block | Block 6, Abschnitt „Modul 5: Form-Builder" (5.1–5.13) |
| Spec | `_bmad-output/specs/M05-form-builder.md` (Size XL, „Voll Google-Forms-Niveau zu Phase 1") |
| **Reuse-Level** | **medium** |
## Reuse-Zusammenfassung
Die Boilerplate enthält ein **fertiges, aber bewusst minimales** Form-Widget (`packages/form-widget` + `prisma/schema/formWidget.prisma` + `apps/web/app/modules/formWidget/builder/*` + Submit-Route + 3 Worker-Jobs). Es ist ein **embeddable Lead-Capture-Widget**, kein Google-Forms-Klon: 8 Feldtypen, 3-Tab-Builder (Palette/Canvas/Properties/Settings/Preview), Drag-&-Drop (`@dnd-kit`), Origin-Allowlist, Honeypot, Sliding-Window-Rate-Limit, Turnstile (feature-gegated), und Routing auf `generic | crm-contact | entity-row` plus Webhook-/Notify-Email-Follow-ups über Outbox.
Das deckt das **Architektur-Skelett** von M121–M123 und den **Spam-Schutz-Kern** von M125 ab. Es fehlt jedoch der **Großteil des fachlichen Funktionsumfangs**: 9 von 17 Feldtypen (u.a. Datei, Foto, Signatur, Adresse, Datum/Zeit, Telefon-E.164, hidden), das gesamte explizite Datenmodell der Spec (`FormField`/`FormSubmissionAnswer`/`FormFile`/`FormLink`/`FormAction`/`FormActionLog`/`FormLog`/`FormTag`), die 11 Submission-Aktionen (Lead/Deal/Projekt/Task/KWP/Automation/...), Public-URL/QR/iFrame-Auto-Resize, Submissions-Verwaltung (Liste/Filter/CSV/PDF/Re-Run), Conditional-Display (M124), und die 8 SHK-Vorlagen. Querschnitt (DB-Client/Outbox/Audit/Notifications/Feature-Flags/File-Storage/i18n/View-Models/App-Shell) ist solide vorhanden und direkt nutzbar.
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/form-widget/src/schema.ts` | Zod-Schemas `FormDefinitionSchema`/`FormFieldSchema`/`FormThemeSchema`/`FormSubmissionPayloadSchema`/`FieldTypeSchema`; Feldtypen-Enum, Length-Validation, Duplicate-Key-Check, `HONEYPOT_FIELD_KEY` | **als-vorlage** — Struktur 1:1, aber Feldtyp-Enum von 8 auf 17 erweitern + `field_config`/`validation_rules` (min/max_value, regex, accepted_file_types, max_file_size, custom_error_message) ergänzen |
| `packages/form-widget/src/origin.ts` | `matchAllowedOrigin`/`normalizeOrigin` (Wildcard-Subdomain, leere Allowlist = nicht submittbar) | **1:1** — direkt für Embed-/CORS-Schutz |
| `packages/form-widget/src/honeypot.ts` | `isHoneypotTriggered` (still 204/Silent-Drop) | **1:1** — deckt 5.9.1 ab |
| `packages/form-widget/src/routing.ts` | `resolveSubmissionTarget`/`applyFieldMapping` (Field-Mapping-Helper, worker-hot-path, sync) | **anpassen** — Mapping-Mechanik 1:1; Target-Set von 3 (`generic/crm-contact/entity-row`) auf die 11 Action-Typen der Spec erweitern |
| `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) | Tenant-scoped Form-Definition (JSON) + Submission-Inbox (`payload` JSON, `ipHash` SHA-256, `status`, `result`, `allowedOrigins[]`, `notifyEmails[]`, `webhookUrl`, `config`, `key @unique`) | **als-vorlage** — gutes Fundament für `Form`+`FormSubmission`, aber Spec verlangt zusätzlich `slug`/`subtype`/`status`(draft/published/archived)/`is_public`/`requires_login`/`submission_limit`/`submission_close_at`/`success_message`/`redirect_url` und die normalisierten Tabellen (`FormField`, `FormSubmissionAnswer`, `FormFile`, `FormLink`, `FormAction`, `FormActionLog`, `FormLog`, Tags) |
| `apps/web/app/modules/formWidget/builder/FormBuilder.tsx` + `Canvas.tsx`/`SortableField.tsx`/`FieldPalette.tsx`/`FieldProperties.tsx`/`PreviewTab.tsx`/`SettingsTab.tsx`/`palette.ts`/`types.ts` | Kompletter Tab-Builder mit Drag-&-Drop-Canvas, Feld-Eigenschaften-Editor, Live-Preview, Settings (Origins/Notify/Webhook/Target/Field-Mapping), i18n-Keys durchgängig | **als-vorlage** — Editor-Grundgerüst & Drag-&-Drop-Pattern direkt übernehmbar; Palette von 8 auf 17 Feldtypen erweitern, FieldProperties um typ-spezifische Configs (Datei-Typen, Datums-Format, Adresse, Signatur, hidden-Prefill) ausbauen. ACHTUNG: liegt in `apps/web` (nicht in `packages/ui-hivegrid`) — für HiveGrid in den View-Model/Adapter-Layer umziehen (AGENTS Layer-Disziplin, M013/M015) |
| `apps/web/app/routes/api.embed.forms.$formKey.submit.tsx` | Public-Submit-Endpoint: Origin-Check → Honeypot-Silent-Drop → Sliding-Window-Rate-Limit (pro IP **und** pro Origin) → Turnstile (feature-flagged via `evaluateFlagForContext`) → `ipHash` → Payload-Validation gegen gespeicherte Definition → Outbox-Publish | **anpassen** — deckt M125 (5.9.1–5.9.4) fast vollständig ab; Rate-Limit-/Honeypot-/Captcha-Pipeline 1:1, fehlende Stücke: Datei-Upload-Annahme, Signatur+IP/Zeitstempel-Persistenz (5.5), Anomalie-Drosselung (5.9.4) |
| `apps/web/app/routes/embed.forms.$formKey.tsx` | iFrame-gerenderte Public-Form-Mini-App | **als-vorlage** — Basis für Embed; Auto-Resize via postMessage (M122) + Public-URL-Pattern `f/<tenant>/<slug>` (INTEGRATION-CONTRACTS §3) ergänzen |
| `apps/web/app/routes/app.$tenant/forms.tsx` + `forms.$id.tsx` | Tenant-Admin: Form-Liste + Create (mit Submission-Count + Embed-Snippet) und Detail/Edit-Route (Loader baut VM, Action speichert via Prisma, Permission-Gate, CSRF) | **als-vorlage** — Route-Topologie & Loader/Action-Muster übernehmbar; Permission ist aktuell `app.settings.account.update` (admin-only) statt der M05-`forms.*`-Permissions |
| `apps/worker/src/jobs/form-submission-route.ts` | Outbox-getriebener Routing-Worker (generic/crm-contact/entity-row, Idempotenz via dispatch-key `form-submission:<id>`, Status-Rückschreibung, Fehler nicht verschluckt → BullMQ-Retry + Sentry) | **anpassen** — Worker-Gerüst + Idempotenz-Muster 1:1; Target-Handler um Lead/Deal/Projekt/Task/KWP/Automation erweitern (M123, 5.7) |
| `apps/worker/src/jobs/form-submission-followups.ts` + `form-submission-webhook-delivery.ts` | Pure Follow-up-Planner (Webhook + Notify-Email als Outbox-Events) + Webhook-Delivery-Worker | **1:1** für `webhook_send` + `send_email_to_team`/`send_email_to_submitter` (5.7.1/5.7.2/5.7.8) |
| `apps/web/app/utils/turnstile.server.ts` (`verifyTurnstileToken`) + Feature-Flag `form-widget-turnstile` | Captcha-Verifikation | **anpassen** — vorhanden, aber **Cloudflare Turnstile**; M125 fordert explizit **hCaptcha (EU-konform)**. Adapter-Tausch oder zweiter Provider nötig |
| `packages/db` (`getDbClient`/`runDbTransaction`/`outbox.ts`/`audit-hash.ts`/`dsgvo/user-fk-map.ts`) | DB-Client, Transaktionen, transaktionale Outbox (`publishOutboxEvent`), Audit-Hash-Kette, DSGVO-FK-Karte | **1:1** — Querschnitt-Fundament; `user-fk-map.ts` ist Pflicht-Ergänzung bei neuen User-FKs (Submission `submitter_user_id`, `FormLog.created_by_user_id`) |
| `prisma/schema/core.prisma` (`AuditEvent`, `FileObject`/`FileUploadProgress`/`FileChunk`, `IdempotencyKey`, `Event`/`EventWebhookAttempt`) | Audit-Trail (Hash-Kette, `dataSensitivity`/`regulatoryScope`), File-Storage-Metadaten, Idempotenz, Webhook-Attempts | **1:1** — `AuditEvent` deckt `FormLog`/AV#6; `FileObject` deckt M052-Anbindung für Datei-/Foto-Upload (5.4); `IdempotencyKey` für Action-Re-Run (5.8.6) |
| `prisma/schema/notifications.prisma` + `apps/web/app/modules/notifications/services/.server/NotificationService.ts` | `NotificationDelivery`/`UserNotificationPreference`/`DeviceToken` + Service-Layer (In-App/Email/Push) | **1:1** — `notify()`-Querschnitt (M011) für „neue Submission"-Notification (5.7.2, M22-Integration) |
| `prisma/schema/featureFlags.prisma` + `evaluateFlagForContext` | Feature-Flag-Engine (scope/rules/variants, append-only Audit) | **1:1** — DoD-Pflicht „Feature-Flag-fähig" (M006); bereits im Submit-Endpoint genutzt |
| `apps/web/app/utils/integrations/storageService.ts` + `apps/web/app/utils/helpers/.server/MediaService.ts` | S3/Scaleway-Storage-Service + Media-Handling | **anpassen** — Backend für Datei-/Foto-Upload aus Submissions (5.4.1 „landen im Tenant-Datei-Speicher", M052/M053) |
| `packages/exports` (`./csv`, `./pdf`, `audit-pdf`, `EXPORT_PLAN_ROW_CAPS`, S3-Multipart-Sink) + Worker `export.ts`/`dsgvo-export.ts` | Streaming-Export CSV/PDF, Spreadsheet-Injection-Safety, DSGVO-Export | **anpassen** — CSV-Export der Submissions (5.8.4) + PDF-Export einer Submission (5.8.7) + DSGVO-Löschung (5.8.8) |
| `packages/view-models` (`VMState`, `ActionCallbacks`, `I18nLabel`, `assertI18nLabel`) | View-Model-Statusmodell + i18n-Key-Zwang | **1:1** — Konvention M013; Loader baut VM, UI empfängt nur VM+Actions (DoD Layer-Disziplin) |
| `apps/web/app/application/sidebar/{AppSidebar.tsx,SidebarItem.ts}` + `packages/ui-app` Registry-Factories | Datengetriebene Sidebar mit Permission-/Feature-Gating | **als-vorlage** — Sidebar-Eintrag „Forms" (Gruppe gem. INTEGRATION-CONTRACTS §1, Zeile 53 verweist bereits auf M121–M125) |
| `apps/web/app/components/ui/*` (shadcn/Radix: tables, forms, modals, tabs, multi-select, empty/loading states, calendar) | Komponenten-Bibliothek | **1:1** — Submissions-Liste (TableNew/ColumnSelector/TablePagination → 5.8.1–5.8.3), Filter, Empty-/Loading-States, Datums-Picker (`calendar.tsx` für `date`-Feldtyp) |
| `packages/db/src/notifications.server.ts` + `OutboxEvent` (`outbox.prisma`) | Transaktionales Side-Effect-Muster | **1:1** — `form.submitted`-Event (M17-Integration 5.7.9) + alle Actions als Outbox-Events |
| `qrcode.react` (Root-Dependency `^4.2.0`) | QR-Code-Generator-Lib | **1:1** — QR-Code für Print-Material (M122, 5.6.5) — Lib bereits vorhanden, kein neuer Dep |
| `@dnd-kit/{core,sortable,utilities}` (Root-Dependencies) | Drag-&-Drop | **1:1** — Editor-Sortierung (M121, 5.3.1); bereits in Builder verwendet |
## Vorhandene Daten-Modelle
| Modell | Pfad | Deckt Spec-Entität | Lücke |
| --- | --- | --- | --- |
| `Form` | `prisma/schema/formWidget.prisma:8` | `Form` (teilweise) | Fehlen: `slug`, `subtype`, `status`(draft/published/archived) + `published_at`/`archived_at`, `is_public`, `requires_login`, `submission_limit`, `submission_close_at`, `success_message`, `redirect_url`, `description`, `created_by_user_id`. Vorhanden statt Felder: `definition` JSON, `theme`, `targetType`/`fieldMapping` (1 Target), `allowedOrigins[]`, `notifyEmails[]`, `webhookUrl`, `config`, `key` |
| `FormSubmission` | `prisma/schema/formWidget.prisma:40` | `FormSubmission` (teilweise) | Vorhanden: `payload` JSON, `sourceOrigin`, `ipHash`, `userAgent`, `status`, `result`. Fehlen: `submitter_user_id`/`submitter_email`/`submitter_phone`, `linked_entity_type`/`linked_entity_id`, `is_complete`, `archived_at`, `submitted_at` (nur `createdAt`) |
| `AuditEvent` | `prisma/schema/core.prisma` | `FormLog` (AV#6) | Generisches Audit mit Hash-Kette; reicht als `FormLog` oder als Vorlage für dediziertes `FormLog`-Modell |
| `FileObject`/`FileUploadProgress`/`FileChunk` | `prisma/schema/core.prisma` | `FormFile` (Storage-Seite) | `FormFile`-Join (`submission_id`/`field_key`/`file_id`) selbst fehlt; Storage-Metadaten vorhanden |
| `OutboxEvent` | `prisma/schema/outbox.prisma` | Action-/Event-Dispatch | Trägt `form.submission.*`-Events; `FormAction`/`FormActionLog` als eigene Modelle fehlen |
| `NotificationDelivery` etc. | `prisma/schema/notifications.prisma` | M22-Notification bei Submission | 1:1 |
| `FeatureFlag` | `prisma/schema/featureFlags.prisma` | Feature-Flag-Querschnitt | 1:1 (`form-widget-turnstile` existiert bereits) |
| `app.prisma` (leerer Platzhalter) | `prisma/schema/app.prisma` | — | Vorgesehener Ort für die neuen HiveGrid-Form-Modelle (`FormField`, `FormSubmissionAnswer`, `FormFile`, `FormLink`, `FormAction`, `FormActionLog`, `FormLog`, `FormTag`) |
**Nicht vorhandene Spec-Modelle (komplett neu):** `FormField` (normalisiert — BP speichert Felder als JSON in `Form.definition`), `FormSubmissionAnswer` (pro Feld/Submission — BP speichert alles als `payload` JSON), `FormFile`, `FormLink` (personalisierte Tracking-Links mit Token/expires/usage_limit), `FormAction`, `FormActionLog`, `FormLog` (dediziert), `FormsTag`/`FormTag`.
## Lücken / komplett neu zu bauen
**Feldtypen (M121, 5.1):** 9 von 17 fehlen — `number` ist da, aber nicht `date`/`datetime`/`time`, `multiselect`, `boolean`(toggle), `url`, `phone` (E.164-Norm), `file`, `photo` (Mobile-Kamera-Direktzugriff), `signature` (Touch — **kein** `signature_pad`/Signatur-Komponente in der Boilerplate vorhanden), `address` (Auto-Complete via Maps-Adapter M25), `section_header`, `description_block` (Markdown), `hidden` (URL-Param-Prefill). BP hat nur text/email/number/textarea/select/radio/checkbox/honeypot.
**Validation (M121, 5.2):** BP hat `min/max_length` + `required`. Fehlen: `min_value`/`max_value`, `regex_pattern`, `accepted_file_types[]`/`max_file_size_mb`, `custom_error_message` (Klartext pro Feld, 5.13).
**Veröffentlichung/Sharing/Embed (M122, 5.6):** Public-URL-Pattern `app.hivegrid.de/f/<tenant>/<slug>` (INTEGRATION-CONTRACTS §3) — BP nutzt `embed.forms.$formKey` (Key, kein slug/tenant-Pfad). `is_public`/`requires_login`-Gating fehlt. iFrame-**Auto-Resize** (postMessage) fehlt. **QR-Code-Generator** fehlt (Lib `qrcode.react` vorhanden, Integration neu). **FormLink** (personalisierte Tracking-Links mit Token/expires/usage_limit, 5.6.2) komplett neu. JS-Snippet/`embed.js` (5.6.4) — BP hat Embed-Script-Base, aber CORS-konformes Inline-Snippet neu zu verifizieren.
**Submission-Aktionen (M123, 5.7):** BP routet nur auf `crm-contact`/`entity-row` + Webhook + Notify-Email. Fehlen: `create_lead` (M2), `create_deal` mit Pipeline-Wahl (M3), `create_project` (M4), `create_task` (M26), `link_to_existing_entity` (Auto-Match Email/Phone), `trigger_automation` (M17), `kwp_push` (M19). **Mehrere Actions in Reihenfolge** pro Form + **Conditional Actions** (`filter_rules`) + per-Action-Field-Mapping als Konfig — BP kennt nur 1 Target pro Form.
**Datei-/Foto-/Signatur-Submission (M123, 5.4/5.5):** Datei-Upload-Annahme im Submit-Endpoint fehlt (Schema schließt File explizit aus). Foto-Upload mit Kamera (mobile). Touch-Signatur **mit IP+Zeitstempel-Persistenz** (rechtliche Beweiskette, 5.5.2). File-→-Tenant-Storage-Verknüpfung (`FormFile`).
**Submissions-Verwaltung (M123, 5.8):** BP zeigt nur Submission-Count auf der Liste. Komplett neu: Submission-Liste mit Spalten-Konfiguration (5.8.3), Filter nach Datum/Submitter/Entität, Detail-Ansicht mit allen Antworten + Metadaten + Action-Status + File-Vorschau, **Action-Re-Run** (5.8.6), CSV-Export (5.8.4 — `packages/exports` als Basis), PDF-Export (5.8.7 — `packages/exports/pdf`), Archivieren/DSGVO-Löschen (5.8.8).
**Conditional-Display (M124, 5.12.1-as-Phase-1-Variante):** Show/Hide-Logik basierend auf anderem Feldwert (ODER/UND), im Editor setzbar + im Renderer ausgewertet — **komplett neu** (BP-Schema kennt kein `conditional_visibility`). KEIN Branching (Anti-Liste).
**Spam-Schutz (M125, 5.9):** Honeypot ✅, Rate-Limit pro IP ✅, Origin-Check ✅, Captcha ✅ (aber **Turnstile statt hCaptcha** — Provider-Tausch nötig, 5.9.2). Fehlt: Anomalie-Drosselung bei verdächtigen Mustern (sehr schnelles Ausfüllen / mehrfach gleicher Inhalt, 5.9.4).
**SHK-Branchen-Vorlagen (M125, 5.10):** Alle 8 Vorlagen (Kontakt-Anfrage, Sales-Aufnahme, Foto-Checkliste, Acceptance-Protokoll, Wartungs-Buchung, Krankmeldung, Urlaubsantrag, Customer-Feedback) als deklarative Seed-Konfiguration (LP-3/AV#3) — **komplett neu**, an M158-Provisionierung gekoppelt.
**Permissions (M05 Block J):** Die 8 atomaren `forms.*`-Permissions + 4 Bundles + Default-Rollen-Mapping (SHK-Rollen aus M023) — neu zu seeden. BP-Forms nutzen ein einzelnes `app.settings.account.update`.
**i18n:** BP-Builder nutzt `settings.forms.builder.*`-Keys (Namespace `settings`/`translations`). HiveGrid-eigene Keys (de/en) für alle neuen Felder/Texte (M003-Build-Lint blockt sonst).
**Layer-Disziplin:** Boilerplate-Builder + Routen liegen in `apps/web/app` (gemischter Loader/UI-Layer). HiveGrid verlangt UI in `packages/ui-hivegrid` (kein Prisma-Import), Loader baut VM, Subframe via Adapter (M013/M015, DoD). Beachte MEMORY: jede Route MUSS `mcp__subframe__design_page` nutzen; `.server.ts`-Re-Export-Blocker → nur Component-Extraktion.
## Empfohlenes Vorgehen
1. **Datenmodell zuerst (M121-Basis):** `formWidget.prisma` als Vorlage nehmen, aber das volle Spec-Schema in `prisma/schema/app.prisma` bauen — `Form` (alle Stammdaten-Felder + `slug` unique pro Tenant + `subtype`/`status`), normalisierte `FormField`, `FormSubmission` + `FormSubmissionAnswer`, `FormFile`, `FormLink`, `FormAction`, `FormActionLog`, `FormLog`, `FormTag`. Entscheidung normalisiert-vs-JSON bewusst treffen (Spec listet beide normalisierten Tabellen UND `submission_data` JSON — Hybrid wie BP ist legitim, aber `FormField`-Normalisierung ist für Editor/Spalten-Konfig/Conditional-Display sinnvoll). User-FKs in `dsgvo/user-fk-map.ts` ergänzen.
2. **Zod-Schema erweitern (M121):** `packages/form-widget/src/schema.ts` als Startpunkt kopieren/erweitern (eigenes HiveGrid-Paket oder erweitern), Feldtyp-Enum auf 17 erweitern, typ-spezifische `field_config` + volle `validation_rules` + Klartext-`custom_error_message`.
3. **Editor übernehmen + ausbauen (M121):** `FormBuilder.tsx` + Canvas/`@dnd-kit`-Drag-&-Drop + FieldProperties + PreviewTab als Vorlage in den View-Model/Adapter-Layer ziehen (Layer-Disziplin!). Palette auf 17 Feldtypen, FieldProperties um typ-spezifische Configs, Live-Preview + Klartext-Validation (5.13.1/5.13.2). Neue Components: Signatur-Pad (neuer Dep, z.B. `signature_pad`), Foto/Kamera, Adress-Autocomplete (M25), Datums-Picker (`calendar.tsx` vorhanden).
4. **Submit-Endpoint + Spam-Schutz (M125 vorziehen, da BP es fast fertig hat):** `api.embed.forms.$formKey.submit.tsx` als Vorlage — Honeypot/Rate-Limit/Origin/ipHash 1:1, Turnstile → **hCaptcha** tauschen, Anomalie-Drosselung ergänzen. Public-URL auf `f/<tenant>/<slug>` (INTEGRATION-CONTRACTS) umstellen, `is_public`/`requires_login` gaten.
5. **Sharing/Embed (M122):** iFrame-Auto-Resize (postMessage), QR-Code (`qrcode.react`), `FormLink`-Tracking-Links (Token/expires/usage_limit). `embed.forms.$formKey.tsx` als Render-Basis.
6. **Submission-Routing/Actions (M123):** `form-submission-route.ts`-Worker + `applyFieldMapping` + Outbox-Idempotenz-Muster als Skelett; Action-Registry auf alle 11 Typen erweitern, jede Action als eigener Outbox-Event-Handler (`create_lead`/`create_deal`/`create_project`/`create_task`/`kwp_push`/`trigger_automation`/...). Webhook + Notify-Email-Follow-ups 1:1. `FormActionLog` + Re-Run (5.8.6) über `IdempotencyKey`.
7. **Datei/Foto/Signatur-Persistenz (M123):** Submit-Endpoint um Multipart-/File-Annahme erweitern, in `FileObject`/Storage (`storageService.ts`/M052) ablegen, `FormFile`-Join schreiben; Signatur als File + IP/Zeitstempel in Submission.
8. **Submissions-Verwaltung (M123):** Liste (shadcn `TableNew`/`ColumnSelector`/`TablePagination`) + Filter + Detail-Ansicht; CSV-Export via `packages/exports/csv`, PDF via `packages/exports/pdf`, DSGVO-Löschen via `dsgvo-export`/Hard-Delete-Muster.
9. **Conditional-Display (M124):** `conditional_visibility`-JSON pro Feld im Editor setzbar, Show/Hide-State im Renderer (kein Routing-Pfad-Wechsel). Komplett neu.
10. **SHK-Vorlagen + Permissions (M125):** 8 Vorlagen als deklarative Seed-Konfig (an M158 gekoppelt). `forms.*`-Permissions + Bundles + Rollen-Mapping seeden.
11. **Querschnitt-Wiring (alle, DoD):** Sidebar-Eintrag „Forms" (INTEGRATION-CONTRACTS §1, Zeile 53), Breadcrumbs, `AuditEvent`/`FormLog`, `notify()` (M011) bei Submission, Search-Index (M24, falls suchbar), Feature-Flag pro Modul (M006), View-Model-Konvention (M013), Customer-Portal-Sichtbarkeit explizit konfigurieren.
## Notizen / Vorbehalte
- **„Reif" in der Inventur ist relativ:** Die Domain-Packages-Inventur listet Form-Widget als „Reif" — das stimmt für das **embeddable Widget**, aber gemessen am M05-„Google-Forms-Niveau"-Anspruch ist es ein **Bruchteil** des Scopes. Daher Reuse-Level **medium**, nicht high.
- **Provider-Diskrepanz Captcha:** BP nutzt Cloudflare **Turnstile**, M125 fordert explizit **hCaptcha (EU-konform statt Google-OAuth-Trigger)**. Architektur ist feature-flagged → Adapter-Tausch machbar, aber bewusste Entscheidung nötig.
- **Keine Signatur-Komponente:** Trotz Spec-Hinweis „Touch-Signatur via signature_pad (Boilerplate-Deps)" in M121-PLAN ist **kein** `signature_pad`/Signatur-Code in der Boilerplate vorhanden (nur Treffer in unrelated Files). Neuer Dependency erforderlich.
- **Speicher-Modell-Bruch:** BP speichert Felder als `definition`-JSON und Antworten als `payload`-JSON; Spec listet normalisierte `FormField`/`FormSubmissionAnswer`. Für Spalten-Konfiguration (5.8.3), Conditional-Display (M124) und CSV-Export pro Feld ist die normalisierte Variante deutlich tragfähiger — Architektur-Entscheidung früh treffen.
- **Layer-Umzug Pflicht:** BP-Builder/Routen sind nicht layer-getrennt (UI + Prisma im selben `apps/web`-Modul). HiveGrid-DoD blockt das — Component-Extraktion in `packages/ui-hivegrid` + VM-Loader nötig (MEMORY: `.server.ts`-Re-Export-Blocker beachten).
@@ -0,0 +1,142 @@
# Boilerplate-Abgleich: M06 — Booking / Termin-Buchung (Calendly-Style)
| Feld | Wert |
| --- | --- |
| **Modul-ID** | M06 (Block 6, Modul 6) |
| **Name** | Booking / Termin-Buchung (Calendly-Style) |
| **Milestones** | M126 (Buchungs-Seite + Time-Slot-Engine), M127 (Verfügbarkeits-Berechnung), M128 (Bestätigungs-Flow + Verknüpfungen), M129 (Stornierung + Verschiebung + No-Show) |
| **Pflichtenheft-Block** | block6.md §6.1–6.12 |
| **Detail-Spec** | `_bmad-output/specs/M06-booking.md` |
| **Reuse-Level** | **low** |
## Reuse-Verdikt (Kurzfassung)
Das **gesamte Booking-Domänen-Modell fehlt** in der Boilerplate. Es gibt **kein** Prisma-Modell für `BookingPage`, `BookingPageProvider`, `AvailabilityRule`, `AvailabilityException` oder `Appointment` — verifiziert mit `grep '^model (Booking|Appointment|Availability|Slot|Calendar|...)'` über alle 27 `prisma/schema/*.prisma`-Dateien (Treffer: 0). Auch die im Spec als Dependency genannte **Calendar-Sync (Modul 25, Google/MS)** existiert in der Boilerplate NICHT (kein `googleapis`, kein `@microsoft/microsoft-graph`, kein Calendar-Service). Die **Slot-Berechnungs-Engine** und der **Doppelbuchungs-Schutz** (`EXCLUDE USING gist`/`tstzrange`/`btree_gist` — 0 Treffer in `prisma/migrations`) sind komplett neu zu bauen.
Was die Boilerplate liefert, ist **ausschließlich das Querschnitt-Fundament** (Permissions/Audit/Notify/Idempotenz/Adapter/CatalogError/View-Models/Feature-Flags/i18n), der **Mail-Stack** (für Bestätigungs-/Storno-Mails inkl. `handlebars` als Template-Engine), das **Form-Widget** (für Intake-Form-Renderer/Submissions, deckt M5-Kopplung), das **Lead-Modell** (für die „neuer Lead bei unbekannter Email"-Verknüpfung) und Infrastruktur (Queue/Outbox/Redis-Cache für die Slot-Cache-TTL, Public-Site-Pattern, Storage). Die Geschäftslogik des Moduls — Slots, Verfügbarkeit, Provider-Zuteilung, Public-Booking-Flow, iFrame-Embed, .ics, Kalender-Sync — ist vollständig HiveGrid-Neubau.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/foundation/src/permissions.ts` | `withTenantScope()`, `withPermission()`, `withOwnerCheck()`, `requirePermission()` — RLS-Tenant-Scope, Permission-Gate, Owner-Check für `bookings.read_own` (A.5/K.5); 404-statt-403 bei Denied | **1:1** |
| `packages/foundation/src/audit.ts` | `auditEvent()`, `withAuditMiddleware()` — Audit-Trail für Termin-/Booking-Page-Änderungen (AV #6); Hash-Kette über `AuditEvent` | **1:1** |
| `packages/foundation/src/notifications.ts` | `notify()`, `notifyMany()`, `bundleNotifications()` — interne Notifications (z.B. „Bestätigungsmail fehlgeschlagen — bitte manuell kontaktieren", I.3) statt Direkt-Mail | **1:1** |
| `packages/foundation/src/idempotency.ts` | `withIdempotency()` — replay-sicherer Booking-Submit (verhindert Doppel-POST des Public-Flows) | **1:1** |
| `packages/foundation/src/errors.ts` | `CatalogError`, `foundationErrors` (`notFound` 404, `forbidden`, `idempotencyConflict` 409) — Klartext-Diagnostik (LP-10): 404 für nicht-publizierte Page (G.4), 409 bei Slot-Race (G.3) | **als-vorlage** (HiveGrid-Catalog-Errors ergänzen, z.B. Slot-Konflikt, Sync-Fehler, Slug-Konflikt) |
| `packages/foundation/src/adapters.ts` | `defineAdapter()`, `getAdapter()` mit Status — Adapter-Pattern für Calendar-Sync (LP-11: Sync über Modul-25-Adapter, nicht direkt gegen Google/MS) | **als-vorlage** (Calendar-Adapter selbst existiert nicht) |
| `packages/view-models/src/index.ts` | `VMState<T>`, `ActionCallbacks<T>`, `RegistryGate`, `SidebarRegistryItem`, `ready/empty`, `assertI18nLabel` — VM-Status/Action-Vertrag für Listen-View (C), Detail-View (D), Editor (E), Verfügbarkeits-Page (F) | **1:1** |
| `packages/feature-flags/src/*` + `packages/foundation/src/flags.ts` | `evaluateFlag()` / `featureFlag()` — Modul ohne Deploy abschaltbar (DoD „Feature-Flag-fähig") | **1:1** |
| `packages/i18n/src/*` | Locale-Config (de/en), `formatDate`/`formatNumber`/ICU, `useTranslate` — alle UI-Texte + Datums-/Zeitformat in Endkunden-/Tenant-Timezone (A.3/G) | **1:1** |
| `packages/mail/src/mailersend.ts` + `src/queue.ts` + `src/templates-react/*` | MailerSend-Provider (EU) + Queued-Mail + React-Email-Layout-Primitives (BaseLayout/Header/Footer/Button mit `assertSafeUrl`) — Bestätigungs-/Storno-/Update-Mail (I, 6.5, 6.8.4/6.8.5) | **anpassen** (Booking-spezifische Templates neu; Layout 1:1) |
| `handlebars` (Root-Dependency, `package.json`) | Template-Engine für `confirmation_email_subject`/`_body` + `internal_calendar_event_title` mit `{{...}}`-Variablen (I.1/I.2) — löst die im Spec offene Frage „Liquid vs. Handlebars vs. Mustache" zugunsten Handlebars (bereits vorhanden) | **1:1** (Engine), **anpassen** (Variablen-Resolver für Booking-Kontext) |
| `packages/shared-store/src/*` (`createCacheStore`, TTL, Cross-Instance-Invalidation) | Redis-KV für Slot-Cache (A.6: 60s-TTL pro `(booking_page_id, date)` + Invalidation bei neuer/gelöschter Appointment etc.) | **1:1** (Engine), **anpassen** (Booking-Cache-Keys/Invalidation) |
| `packages/queue/src/*` + `packages/db/src/outbox.ts` (`OutboxEvent`) | BullMQ + transaktionaler Outbox-Publisher — async Kalender-Sync-Re-Try-Queue (J.3, 6.4.4), Outbox für Activity-/Sync-Side-Effects in der Submit-Transaktion | **1:1** (Infra), **anpassen** (Booking-Jobs/Event-Typen neu) |
| `packages/form-widget/src/*` + `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) | Form-Definition/Renderer/Submission-Inbox inkl. `ipHash`, Honeypot, Origin-Allowlist — Intake-Form (G.2): Standard-Mini-Form ODER `intake_form_id`→Modul-5-Form; `FormSubmission` ist das von `Appointment.form_submission_id` referenzierte Modell | **anpassen** (Renderer wiederverwenden; Booking-Submit erzeugt `FormSubmission` + Activity `form_submitted`, J.5) |
| `apps/web/app/modules/formWidget/builder/*` (`FormBuilder.tsx`, `PreviewTab.tsx`, `SettingsTab.tsx`) | Editor-/Preview-/Settings-Tab-Muster — Vorlage für Booking-Page-Editor (E.2: sektionierte Anzeige, Live-Preview, Publish-Toggle, Embed-Generator) | **als-vorlage** |
| `prisma/schema/marketingLeads.prisma` (`Lead`, `LeadEvent`) | Lead-Modell — „unbekannte Email → neuer Lead mit Quelle Buchung" (J.1, 6.9.1). Achtung: `Lead` ist **operator-scoped, NICHT tenant-scoped** (`email @unique` global). HiveGrid braucht hier ggf. einen tenant-scoped Lead — Abgleich mit M047 (Lead-Inbox) nötig | **anpassen** / Klärung mit M047 |
| `prisma/schema/sites.prisma` (`Site`, `type = "booking"`, `serverResolution domain/path/subdomain`) | Multi-Site-Konfig-Record mit Branding/Copy + Host-Resolution — Vorlage für Public-Booking-Site-Auflösung (`/b/{tenant}/{slug}`, B/G). **Kein** Booking-Domänenmodell, nur Site-Routing/Branding-Hülle | **als-vorlage** |
| `packages/url/src/canonical.ts` | host-aware `appPath`/`appUrl` — Public-URL-Bau für Page-Liste (E.1 Copy-to-Clipboard) + Embed-Src (H.1) | **1:1** |
| `apps/web/app/components/ui/calendar.tsx` (`react-day-picker`) | Kalender-Primitive (date-fns-Locale, i18n) — Datum-Auswahl im Public-Slot-Picker (G.2) + Date-Range-Filter (C) | **anpassen** (Verfügbarkeits-Indikator/Ausgrauen pro Tag ergänzen) |
| `apps/web/app/components/ui/*` (shadcn: `table.tsx`, `tabs.tsx`, `multi-select.tsx`, `stepper.tsx`, `pagination.tsx`, `dialog.tsx`, `command.tsx`, `tables/ColumnSelector.tsx`, `tables/TablePagination.tsx`) | UI-Primitives — Listen-View (C: sortierbare Tabelle, Tabs, Filter, Spalten-Config, Cursor-Pagination), Multi-Step-Flow (G: Stepper), Provider-Multi-Select (E.2) | **1:1** (Primitives), **anpassen** (Booking-Pages bauen) |
| `apps/web/app/components/layouts/sidebars/shadcn/*` + `application/sidebar/SidebarItem.ts` + `AppSidebar.tsx` | Datengetriebene Sidebar mit Permission-/Feature-Gating — Sidebar-Gruppe „Arbeiten" → „Buchungs-Seiten" (INTEGRATION-CONTRACTS §1, M126-M129) | **1:1** (Muster); HiveGrid-Ziel ist `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` |
| `packages/exports/src/csv/*` + Worker `export.ts` | CSV-Export-Framework mit Plan-Row-Caps + Injection-Safety — CSV-Export gefilterter Buchungs-Liste (C: „Export als CSV") | **1:1** |
| `packages/storage/src/*` (S3/Scaleway, Signed-URLs) | EU-Storage — Datei-Uploads aus verknüpftem Intake-Form (falls Custom-Form Upload-Felder hat) | **1:1** |
| `packages/db/src/client.server.ts` + `transactions.server.ts` (`runDbTransaction`) | Prisma-Client-Boundary + Transaktionen — atomarer Submit (Appointment + FormSubmission + Lead/Contact-Link + Outbox-Event in einer Tx, J/G.3) | **1:1** |
| `packages/db/src/dsgvo/user-fk-map.ts` | DSGVO-FK-Karte — **Pflicht-Eintrag** für jeden neuen User-FK (`Appointment.provider_user_id`, `AvailabilityRule.tenant_user_id`, `BookingPageProvider.tenant_user_id`); CI-Test bricht sonst | **1:1** (erweitern, kein Skip) |
| `packages/db/src/search/indexed-entities.ts`-Pattern + `packages/search/*` (Meilisearch, tenant-scoped) | Search-Index-Registry — falls Buchungen global suchbar sein sollen (DoD „Search-Index, falls suchbar") | **als-vorlage** |
| `packages/ui-app` + `packages/ui-mock` + `apps/web/app/components/ui/hot-swap/*` | Shell-Registry-Factories + Hot-Swap-/Visual-Mock — DoD „Hot-Swap-Drill grün" + „Visual-Regression-Snapshot" | **1:1** (Test-Infra) |
---
## Vorhandene Daten-Modelle (konkret)
**Booking-Domäne: NICHTS vorhanden.** Verifiziert: kein `model BookingPage|BookingPageProvider|AvailabilityRule|AvailabilityException|Appointment` in irgendeiner `prisma/schema/*.prisma`-Datei (`grep '^model'`-Treffer 0). `prisma/schema/app.prisma` ist der leere Platzhalter (`// custom database models`) — vorgesehener Ort für die neuen HiveGrid-Booking-Modelle.
Indirekt nutzbare / referenzierte Bestands-Modelle:
| Modell | Pfad | Rolle für M06 |
| --- | --- | --- |
| `User`, `TenantUser`, `Tenant` | `prisma/schema/accounts.prisma` | Provider = `TenantUser`; Tenant-Scope-Anker; `User`-FK für `provider_user_id`/`tenant_user_id` |
| `Form`, `FormSubmission` | `prisma/schema/formWidget.prisma` | `intake_form_id`-Ziel (Custom-Intake) + `Appointment.form_submission_id` (Intake-Daten der Buchung) |
| `Lead`, `LeadEvent` | `prisma/schema/marketingLeads.prisma` | „neuer Lead bei unbekannter Email" (operator-scoped — Klärung mit M047 nötig) |
| `Site` | `prisma/schema/sites.prisma` | `type="booking"`-Site-Config + Host-Resolution (Routing/Branding-Hülle, KEIN Booking-Modell) |
| `AuditEvent`, `IdempotencyKey` | `prisma/schema/core.prisma` | Audit-Trail + idempotenter Submit |
| `OutboxEvent` | `prisma/schema/outbox.prisma` | transaktionale Side-Effects (Sync/Activity/Mail) |
| `NotificationDelivery`, `UserNotificationPreference` | `prisma/schema/notifications.prisma` | interne Hinweise an Provider (Mail-Fehler etc.) |
| `FeatureFlag` | `prisma/schema/featureFlags.prisma` | Modul-Abschaltung ohne Deploy |
| `Email`, `OutboundEmail` | `prisma/schema/email.prisma` | E-Mail-Infrastruktur (Bestätigungs-/Storno-Mail-Tracking; Tenant-Sending-Domain = Modul 9 separat) |
**Neu anzulegen (in `app.prisma`):** `BookingPage`, `BookingPageProvider`, `AvailabilityRule`, `AvailabilityException`, `Appointment` — komplett gemäß Spec A.1–A.5, inkl. Indizes und Enums (`assignment_strategy`, `status`, `cancelled_by_kind`, `kind`, `day_of_week`).
---
## Lücken / komplett neu zu bauen
1. **Komplettes Booking-Daten-Modell** (A.1–A.5): `BookingPage`, `BookingPageProvider` (M:N), `AvailabilityRule`, `AvailabilityException`, `Appointment` — inkl. aller Felder/Enums/Indizes. Forward-Only-Migration mit Inverse-SQL als Kommentar.
2. **Doppelbuchungs-Schutz auf DB-Ebene** (G.3): `EXCLUDE USING gist` mit `tstzrange` pro Provider — `btree_gist`-Extension muss aktiviert werden (pgvector-Migration zeigt das Muster für Extension-Aktivierung; gist/tstzrange selbst: 0 Treffer in `prisma/migrations`).
3. **Slot-Berechnungs-Engine** (A.6, M127): Layer-Modell Standard-Regel → Exceptions → bestehende Appointments (+Buffer) → externe Calendar-Events → Plantafel → min/max-Vorlauf → Slot-Increment → Assignment-Strategy-Merge. Server-side, gecacht 60s in Redis (`shared-store` liefert nur die Cache-Primitive, nicht die Logik).
4. **Provider-Zuteilungs-Strategien** (A.2): `round_robin` (wenigste Buchungen letzte 30 Tage), `specific_provider_choice`, `first_available` — reine HiveGrid-Logik.
5. **Public-Booking-Flow** (G, M126): Multi-Step-Wizard (Slot → Intake → Bestätigung), Verfügbarkeits-Kalender mit ausgegrauten Tagen, Timezone-Wechsler, Race-Condition-Handling mit Klartext + aktualisierten Alternativen, .ics-Add-to-Calendar. Kein Bestandscode.
6. **Public-Route ohne Login + Embed** (B/H): `/b/{tenant}/{slug}` und `/b/{tenant}/{slug}/embed`; Embed ohne Branding-Header + `X-Frame-Options: ALLOWALL`/CSP für `/embed`. Boilerplate-Public-Routes existieren (Forms `/f/...`), aber Booking-Routen + Embed-CSP-Setup sind neu.
7. **Embed-Code-Generator** (H.3): iFrame-Snippet + Copy-to-Clipboard + Klartext-Hilfe. Optional JS-Snippet-Loader (`booking.js`) — Phase-2-Tendenz.
8. **Calendar-Sync (Modul 25)** — **fehlt komplett in der Boilerplate**: kein interner Kalender (`CalendarEvent`), kein Google/MS-Adapter, kein `googleapis`/MS-Graph-Dep, kein bidirektionaler Sync, keine externen Events als Slot-Blocker (A.6/J.2/J.3). M118–M120 (Calendar) sind harte Vorbedingung von M126/M127/M128 und müssen vorher gebaut sein. M06 konsumiert sie nur über den Adapter (LP-11).
9. **Bestätigungs-/Storno-/Update-Mail-Inhalt** (I, M128/M129): Booking-spezifische Handlebars-Templates + Variablen-Resolver (`appointment.*`, `booking_page.*`, `provider.*`, `contact.*`, `tenant.company_name`); Default-Seeds (SHK-Branche); Versand über Tenant-Sending-Domain (Modul 9) mit Fallback `noreply@hivegrid.de`. Mail-Stack/Layout vorhanden, Templates neu.
10. **.ics-Generator** (G.3/6.5.3): Add-to-Calendar-Datei für Endkunde — keine `ics`/`ical-generator`-Dependency vorhanden.
11. **Verknüpfungs-Logik** (J, M128): Email-Match gegen Contact → `contact_id` ODER neuer Lead; `FormSubmission`-Erzeugung; Activity-Typen (`appointment_scheduled/held/cancelled/rescheduled/no_show`, `form_submitted`) via `logActivity` (Activity-Service `@hivegrid/activity` ist HiveGrid-M045, nicht Boilerplate). Deal-Verknüpfung wenn Contact in Deal.
12. **Interne Termin-Verwaltung** (C/D/M129): Listen-View (Filter/Tabs/Bulk-Cancel/CSV-Export/Spalten-Config/Cursor-Pagination), Detail-View (Sektionen, Inline-Notes, Sync-Status-Badge, Action-Buttons), Status-Transitions (`held`/`no_show`/`cancelled`/`rescheduled`), Reschedule mit Slot-Picker, Provider-Re-Assignment mit Kalender-Resync + Update-Mail.
13. **Verfügbarkeits-Verwaltung-UI** (F, M127): Wochen-Editor (mehrere Fenster/Tag, Auto-Merge überlappender Fenster), Ausnahmen-Editor, Timezone pro Regel, Bulk „diese Woche nicht verfügbar" (7 Exceptions).
14. **Booking-Page-Editor** (E, M126): sektionierter Editor, Live-Slug-Validation (Eindeutigkeit + Reserved-Words + Auto-Vorschlag), Markdown-Editor, Provider-Multi-Select mit Drag&Drop-`display_order`, Intake-Form-Dropdown, Publish-Toggle, Duplizieren/Archivieren/Hard-Delete mit Klartext-Warnungen.
15. **Booking-Permission-Set** (K): `bookings.read_own / read_all / write / admin` + Bundle-Mapping in `packages/entitlements/src/permissions.ts` (HiveGrid-Konvention) — Boilerplate hat RBAC-Modelle (`Permission`/`Role`), aber keine Booking-Keys.
16. **`packages/ui-hivegrid` + `packages/ui-subframe`-Booking-Pages**: In der Boilerplate ist `ui-hivegrid` nicht vorhanden und `ui-subframe` ist leerer Platzhalter (`{ status: "empty" }`). Subframe-Design + Adapter-Integration sind komplett neu (User-Memory: jede Route via Subframe).
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Vorbedingungen prüfen (blockierend):**
- M118–M120 (Calendar: interner `CalendarEvent` + Google/MS-Sync-Adapter) müssen existieren, sonst sind A.6 (externe Events als Slot-Blocker) und J.2/J.3 nicht baubar. Calendar-Sync ist **nicht** in der Boilerplate — vor M06 sicherstellen.
- M042/M047 (Contact/Lead-Inbox) für die Submit-Verknüpfung (J.1); Lead-Scope (operator vs. tenant) mit M047 klären.
- M5 (Form-Builder) für `intake_form_id`-Renderer (G.2) — Boilerplate-`form-widget` ist die Basis.
**Phase 1 — Querschnitt 1:1 übernehmen (kein Neubau):**
1. `foundation` (permissions/audit/notify/idempotency/errors/adapters) + `view-models` + `feature-flags` + `i18n` + `url` als Service-Imports verdrahten.
2. `db`-Boundary (`client.server`, `runDbTransaction`, Outbox-Publisher) + `queue` + `shared-store` (Cache) als Infra einziehen.
3. Mail-Stack (`@toolctrl/mail`) + `handlebars` als Template-Engine festschreiben (löst offene Spec-Frage).
**Phase 2 — Daten-Modell + DB-Schutz (M126-Fundament):**
4. Neue Modelle in `prisma/schema/app.prisma` (A.1–A.5) + Forward-Only-Migration; `user-fk-map.ts` für alle neuen User-FKs ergänzen (CI-Pflicht).
5. `EXCLUDE USING gist`/`tstzrange` + `btree_gist`-Extension für Doppelbuchungs-Schutz (G.3) — Muster aus pgvector-Extension-Migration.
6. Booking-Permission-Keys + Bundles (K) in `entitlements/permissions.ts`.
**Phase 3 — Engine + Public-Flow (M126/M127, der Neubau-Kern):**
7. Slot-Berechnungs-Engine (A.6) als pure Domain-Logik in `app/domain/**` (keine React/Prisma-UI-Kopplung) + Redis-Cache via `shared-store` + Invalidation.
8. Provider-Zuteilungs-Strategien (A.2).
9. Verfügbarkeits-Verwaltung (F) und Booking-Page-Editor (E) — Editor/Preview-Muster aus `formWidget/builder` als Vorlage.
10. Public-Booking-Flow (G) inkl. Race-Condition-Handling + .ics-Generator (neue `ics`/`ical-generator`-Dependency); Public-Route `/b/{tenant}/{slug}` (+`/embed` mit CSP), Site-Resolution via `sites.prisma`-Muster.
**Phase 4 — Verknüpfungen + Bestätigung (M128):**
11. Submit-Transaktion: Appointment + FormSubmission (`form-widget`) + Contact-Match/Lead-Erzeugung + Outbox-Events (Activity/Sync/Mail) atomar.
12. Bestätigungs-Mail-Templates (Handlebars + Booking-Variablen-Resolver) über Tenant-Sending-Domain (Modul 9) mit Fallback; Kalender-Eintrag intern + extern (Modul-25-Adapter) + Re-Try-Queue.
**Phase 5 — Interne Verwaltung (M129):**
13. Listen-View (C) mit shadcn-Tabelle/Tabs/Filter/CSV-Export (`exports`).
14. Detail-View (D) + Status-Transitions + Storno/Reschedule/Re-Assignment mit Auto-Mails (Storno/Update) und Kalender-Resync.
**Querschnitt durchgehend (DoD/INTEGRATION-CONTRACTS):** Sidebar-Eintrag „Buchungs-Seiten" (Gruppe Arbeiten), Breadcrumbs, alle Texte als i18n-Keys, `withTenantScope`+`withPermission`, Audit auto, `logActivity` (M045), `notify` (M011), Feature-Flag, Permission-Denied → 404, Unit-Test (VM + Zod), Smoke-Test, Hot-Swap-Drill, Visual-Snapshot, Forward-Only-Migration mit Inverse-SQL. Subframe-Design pro Route (User-Memory) + Adapter in `packages/ui-hivegrid/src/adapters/`.
---
## Anti-Erfindungs-Hinweise (faktisch verifiziert)
- **Kein** Booking/Appointment/Availability/Calendar/Slot-Prisma-Modell in der Boilerplate (`grep '^model ...'` über alle 27 Schemas: 0).
- **Kein** Calendar-Sync (Google/MS): kein `googleapis`/`@microsoft/microsoft-graph`-Dep, kein Calendar-Service in `apps/web`/`apps/worker`.
- **Kein** `ics`/`ical-generator`-Dep (Add-to-Calendar neu).
- **Kein** `EXCLUDE USING gist`/`tstzrange`/`btree_gist` in `prisma/migrations` (Doppelbuchungs-Schutz neu).
- **`handlebars` IS vorhanden** (Root-`package.json`) — direkt als Mail-/Title-Template-Engine nutzbar.
- `Site.type = "booking"` in `sites.prisma` ist nur ein Site-Config/Routing-Record, **kein** Booking-Domänenmodell.
- `core.prisma.Event` ist ein generisches Webhook-/Domain-Event, **kein** Kalender-Event.
- `packages/ui-subframe` ist leer; `packages/ui-hivegrid` existiert in der Boilerplate nicht — beides HiveGrid-Neubau.
- `Lead` ist operator-scoped (`email @unique` global), nicht tenant-scoped — Verknüpfungs-Scope mit M047 klären.
@@ -0,0 +1,117 @@
# Boilerplate-Abgleich: M07 — Angebot + Signatur
| Feld | Wert |
| --- | --- |
| **Modul-ID** | M07 (Modul 7) |
| **Name** | Angebot + elektronische Signatur |
| **Milestones** | M130 (Angebot-Erstellung / PDF-Upload + Send-Wizard), M131 (PandaDoc/DocuSign via Apps-Engine + Status-Webhooks), M132 (Status-Tracking + Auto-Stage-Wechsel + Detail-Sicht) |
| **Pflichtenheft-Block** | Block 6, Modul 7 (`_bmad-output/pflichtenheft/blocks/block6.md` §7.1–7.9) |
| **Detail-Spec** | `_bmad-output/specs/M07-angebot-signatur.md` |
| **Reuse-Level** | **low** |
## Reuse-Verdikt (Kurzfassung)
Das **Signatur-Fachdomäne selbst existiert NICHT** in der Boilerplate: kein PandaDoc/DocuSign-Adapter, kein `DealSignatureDocument`/`-Signer`/`-StatusTransition`, kein `SignatureProviderConnection`, kein `SignatureWebhookEvent`, und — fundamental — **kein Deal/Sales/Pipeline-Modell** (M3), an dem das Angebot überhaupt hängt. Verifiziert per Grep über alle `*.prisma`/`*.ts`/`*.tsx`: die einzigen `signature`-Treffer sind (a) HMAC-Webhook-Verify für Stripe/MailerSend, (b) Ed25519-Plugin-Signaturen — beides themenfremd.
Wiederverwendbar ist ausschließlich das **Querschnitt-Fundament + Infrastruktur-Pattern**: Adapter-Registry, SSRF-sicherer Outbound-HTTP-Client, Inbound-Webhook-Handler-Vorlage (Stripe/MailerSend), HMAC-Verify, Idempotenz, Transactional-Outbox, File-Storage (Source-/Signed-PDF), `appsEngine.prisma` (`App`/`DataConnection`) als OAuth-Connection-Träger, sowie der komplette UI-/View-Model-/i18n-/Notification-Stack. Damit ist M07 **kein "Felder einfüllen", sondern ein Neubau auf solidem Fundament** — daher `low` (nicht `none`, weil die Querschnitt-Hülle und das Adapter-/Webhook-Pattern erheblich Arbeit sparen).
---
## Übernehmbar aus Boilerplate
> Boilerplate-Wurzel (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/foundation/src/adapters.ts` | `defineAdapter()` / `getAdapter()` + `AdapterStatus` — Registry für den `SignatureProvider`-Interface-Pattern (PandaDoc/DocuSign) | **1:1** als Registry-Mechanik; die konkreten Provider-Adapter (`createDocument`/`sendDocument`/`getDocumentStatus`/`revokeDocument`/`handleWebhook`) sind neu zu schreiben |
| `packages/foundation/src/outbound-http.ts` | `fetchOutboundHttpWithRedirects()` mit Timeout, Redirect-Limit, SSRF-Schutz (Blockliste interner Hosts), Response-Byte-Cap | **1:1** für alle PandaDoc/DocuSign-REST-Calls (PDF-Upload, Send, Status-Poll, Revoke, Reminder) |
| `packages/foundation/src/idempotency.ts` | `IdempotencyClient`/`IdempotencyResponse` + Catalog-Errors, gestützt auf `IdempotencyKey`-Modell | **1:1** für idempotente Webhook-Verarbeitung (Spec verlangt M007-Idempotenz im Webhook-Empfänger) |
| `packages/foundation/src/errors.ts` | `CatalogError` / `foundationErrors` — Klartext-Diagnostik-Basis (AGENTS.md DoD §22, LP-10/AV#1) | **als-vorlage** — HiveGrid-Klartext-Texte (PDF >25 MB, Signer ohne Email, Provider nicht erreichbar) als eigene Catalog-Einträge ergänzen |
| `packages/foundation/src/{audit,notifications,permissions,flags}.ts` | Querschnitt-Hooks: Audit, `notify`, Permission-Checks, Feature-Flags | **1:1** als Service-Aufrufe (DoD-Pflicht: Audit, Notification via `notify()`, Permission-Filter, Feature-Flag-fähig) |
| `apps/api/src/billing/stripe-webhook-route.ts` | Vollständiger **Inbound-Webhook-Handler**: Signatur-Header lesen → HMAC-Verify → 400/503 bei invalid/missing → `$transaction` mit Outbox-Publish atomar → Metrik | **als-vorlage** — exakte Blaupause für `/api/v1/webhooks/pandadoc/{tenant_id}/{connection_id}` und `…/docusign/…` (Provider-spezifischer Verify + Event-Mapping einsetzen) |
| `apps/api/src/email-sequences/provider-webhook-route.ts` | Inbound-Provider-Webhook mit Event-Type-Mapping (`MAILERSEND_BOUNCE_EVENT_TYPES`-Set → Domain-Aktion) | **als-vorlage** — gleiche Mechanik für `document.viewed/signed/declined/completed/expired` → `DealSignatureDocument`/`-Signer`-Update |
| `apps/api/src/webhooks/mailersend-signature.ts` | `verifyMailerSendWebhookSignature()` (Header-Kandidaten, konstantzeit) | **als-vorlage** für provider-spezifischen Webhook-Verify (PandaDoc/DocuSign HMAC) |
| `packages/api-client-ts/src/webhooks.ts` | `verifyWebhookSignature()` / `signWebhookPayload()` — generisches konstantzeit-HMAC-SHA256 mit Replay-Window | **1:1**/**anpassen** als HMAC-Verify-Helper, falls Provider HMAC-SHA256 nutzen |
| `apps/api/src/route-access-inventory.ts` | Auth-Klasse `webhook-signature` für Inbound-Webhook-Routen (Quelle der Wahrheit der API-Auth-Matrix) | **1:1** — Signatur-Webhook-Routen unter `webhook-signature` registrieren |
| `prisma/schema/appsEngine.prisma` — `App`, `DataConnection`, `AppSyncRun` | Apps-Engine-Daten-Sync-Modell: `App` (`@@unique([tenantId, type])`, `config`-JSON), `DataConnection` (verschlüsselte Credentials, `type` "oauth2"/"webhook"), `AppSyncRun` (Status/Mode/Metriken/Rollback) | **anpassen** — `SignatureProviderConnection` (Spec Block A) kann auf `App`/`DataConnection` aufsetzen (`data_connection_id` referenziert M33a). Verschlüsselte OAuth-Tokens passen in `DataConnection.config` |
| `packages/storage/src/index.ts` + `signed/index.ts` | `createS3StorageAdapter()` (Scaleway-S3), `createSignedDownloadUrl`/`createSignedUploadUrl`, Virus-Scan, Quarantäne | **1:1** für Source-PDF-Upload (M23) + automatischen Download des signierten PDF nach `document.completed` (Spec §7.4.6) |
| `prisma/schema/core.prisma` — `FileObject` | Datei-Metadaten (provider/bucket/key/contentType/byteSize/checksum/signedUrl-Timestamps) | **1:1** als Speicher-Referenz für `source_pdf_file_id` / `signed_pdf_file_id` (sofern M23/Files dieses Modell adoptiert) |
| `prisma/schema/outbox.prisma` + `packages/db/src/outbox.ts` (`publishOutboxEvent`) + `apps/worker/src/outbox/event-router.ts` | Transactional-Outbox: atomares Event-Publish in `$transaction`, longest-prefix-Routing (`webhook.`, `notification.`, `mail.`, …) | **1:1** für `signature.sent/signed/declined/expired`-Trigger an M17 (Spec Block G) und Notification-Fan-out an Vertriebler |
| `apps/worker/src/jobs/form-submission-webhook-delivery.ts` + `packages/queue` (`WebhookDeliveryJob`, `enqueueJob`, `buildIdempotentJobId`) | Worker-Job-Pattern für (a) Reminder-Versand über Provider, (b) Status-Refresh-Poll, (c) Signed-PDF-Download als Hintergrund-Job | **als-vorlage** — neuen Worker-Job + Queue-Payload für Signatur-Async-Arbeit anlegen |
| `packages/queue/src/{names,payloads,producers,priority}.ts` | BullMQ-Wrapper: typisierte Job-Payloads, `enqueueJob()`, `buildIdempotentJobId()`, plan-basierte Prioritäten | **1:1**/**anpassen** — neue `signature.*`-Job-Payloads in die Map ergänzen |
| `prisma/schema/notifications.prisma` (`NotificationDelivery`, `DeviceToken`, `UserNotificationPreference`) + `packages/realtime` + `apps/worker` notification-Job | Push/In-App-Notification-Stack (Spec §7.4: Push an Vertriebler bei Status-Änderung) | **1:1** via `notify()`-Service (M011), NIE direkt Mail/Push |
| `packages/view-models/src/index.ts` | `VMState<T>`, `ActionCallbacks<T>`, `SidebarRegistryItem`, `BreadcrumbRegistryItem`, `RegistryGate{permission,flag}` — die VM-/Action-Callback-Konvention (M013/M014) | **1:1** — Signatur-VMs (Document-Liste, Send-Wizard, Detail) bauen auf diesen Typen |
| `packages/ui-app/src/index.ts` | AppShell + `createSidebarRegistry`/`createBreadcrumbRegistry`/`createMobileRegistry`/`createPortalRegistry`/`createShellRegistries`, `EmptyPage` | **1:1** — Reachability-Wiring (Sidebar-Eintrag, Breadcrumb, Empty-State) erfolgt über diese Registries. **Hinweis:** Paket heißt `@toolctrl/ui-app`, nicht das in AGENTS.md genannte `ui-hivegrid` — Naming-Diskrepanz (siehe Lücken) |
| `packages/ui-subframe` + `packages/ui-mock` | Subframe-Adapter-Ziel + Hot-Swap-Mock (M015/M017) | **als-vorlage** — Send-Wizard/Detail-Sicht via Adapter integrieren; Mock-Variante für Hot-Swap-Drill |
| `packages/i18n/src/index.ts` + `useTranslate.ts` (ICU) | i18n-Engine mit ICU + `useTranslate` (M003) | **1:1** — alle UI-Texte + Klartext-Fehler als i18n-Keys |
| `packages/feature-flags/src/{evaluate,cache,publisher}.ts` + `prisma/schema/featureFlags.prisma` | Feature-Flag-Engine (M006) — Modul ohne Deploy abschaltbar (DoD-Pflicht) | **1:1** — `featureFlag('signature', tenant)`-Gate |
| `packages/db/src/{client.server,transactions.server,audit-hash}.ts` + `prisma/schema/app.prisma` | DB-Boundary, `runDbTransaction`, Audit-Hash-Kette; `app.prisma` = leerer Platzhalter für HiveGrid-eigene Modelle | **1:1** Infrastruktur; **`app.prisma` ist der vorgesehene Ort** für alle neuen M07-Modelle |
| `prisma/schema/permissions.prisma` (`Role`/`Permission`/`RolePermission`/`UserRole`) | RBAC-Fundament | **1:1** — `signature.read/send/revoke/admin` (Spec Block H) als `Permission`-Einträge + Rollen-Defaults seeden |
| `apps/api` Error-Envelope + Request-ID-Middleware (`middleware/error-envelope.ts`, `request-id.ts`) | Konsistentes API-Fehler-Envelope (`code`/`message`/`requestId`) für Webhook-Routen | **1:1** |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
**Direkt relevant / als Träger nutzbar:**
- `prisma/schema/appsEngine.prisma` → `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` — Apps-Engine-Connection + Sync-Lauf-Tracking. Kandidat-Basis für `SignatureProviderConnection` (über `data_connection_id`) und ggf. Status-Sync-Runs.
- `prisma/schema/core.prisma` → `FileObject` (Source-/Signed-PDF-Metadaten), `IdempotencyKey` (Webhook-Idempotenz), `AuditEvent` (tamper-evidente Hash-Kette, Audit-Trail für Status-Transitions — Spec AV#6), `Event` + `EventWebhookAttempt` (**outbound**-Webhook-Delivery, NICHT inbound — Achtung), `Credential`.
- `prisma/schema/notifications.prisma` → `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` — Push/In-App an Vertriebler.
- `prisma/schema/outbox.prisma` → `OutboxEvent` — atomare `signature.*`-Events.
- `prisma/schema/permissions.prisma` → `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` — Permissions Block H.
- `prisma/schema/featureFlags.prisma` → `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit`.
- `prisma/schema/queue.prisma` → `QueueFailedJob` (DLQ), `ExportJob`.
- `prisma/schema/app.prisma` → **leerer Platzhalter** (`// custom database models`) — vorgesehener Ort für alle neuen M07-Modelle.
**NICHT vorhanden (Kern der Lücke):**
- Kein `Deal` / `Sale` / `Pipeline` / `Verkaufsfall` / `Stage` / `Opportunity`-Modell (verifiziert per Grep). M07 hängt komplett an M3 (M059–M064), das ebenfalls neu gebaut wird. → `deal_id`, Auto-Stage-Wechsel und Activity-Stream-Anker existieren noch nicht.
- Kein `SignatureProviderConnection`, `DealSignatureDocument`, `DealSignatureSigner`, `DealSignatureStatusTransition`, `SignatureWebhookEvent` (alle aus Spec Block A) — komplett neu.
- Kein `Contact`/`Kontakt`-Modell (für `linked_contact_id` / Signer-Vorbefüllung aus M1) — neu in M042–M046.
- Kein Activity-Stream-Modell (`logActivity` / M045) — neu.
---
## Lücken / komplett neu zu bauen
1. **Daten-Modell (Block A) — komplett neu** in `prisma/schema/app.prisma`:
- `SignatureProviderConnection` (tenant, `data_connection_id`→`DataConnection`, `provider` pandadoc|docusign, `is_default`)
- `DealSignatureDocument` (deal_id, provider_connection_id, provider_document_id, title, status-Enum draft|sent|viewed|signed|declined|expired|revoked, sent/signed/expires_at, source_pdf_file_id, signed_pdf_file_id, archived_at)
- `DealSignatureSigner` (document_id, position, email/name/role, linked_contact_id, status pending|viewed|signed|declined, signed_at, ip_at_signing, user_agent_at_signing)
- `DealSignatureStatusTransition` (from/to_status, transitioned_at, triggered_by user|provider_webhook|system_timeout, metadata) — Audit-Historie
- `SignatureWebhookEvent` (provider_connection_id, received_at, event_type, payload, signature_validation_status, processed_at) — Inbound-Log
- Pflicht-Begleitung: `packages/db/src/dsgvo/user-fk-map.ts` ergänzen (sonst CI-Bruch), Forward-Only-Migration mit Inverse-SQL-Kommentar.
2. **PandaDoc-Provider-Adapter** — neu: `createDocument(pdf, signers)`, `sendDocument`, `getDocumentStatus`, `revokeDocument`, `handleWebhook`, OAuth2-Connect über M33a, Reminder-Email-Trigger. Nur die Adapter-Registry-Mechanik (`defineAdapter`) + Outbound-HTTP-Client sind vorhanden.
3. **DocuSign-Provider-Adapter** — neu (analog).
4. **Inbound-Webhook-Routen** `/api/v1/webhooks/pandadoc/{tenant_id}/{connection_id}` + `…/docusign/…` — neu, aber Stripe/MailerSend-Route als 1:1-Blaupause. Provider-spezifischer HMAC-Verify + Event-Mapping (`document.viewed|signed|declined|completed|expired`) neu.
5. **Send-Flow-Wizard (Block C, 5 Schritte)** im Deal-Detail — neue UI (PDF-Picker reuse aus M046, Signer-Konfig, Sequenz seriell/parallel, Provider-Auswahl, Send) + View-Models + Action-Callbacks.
6. **Status-Tracking-Verarbeitung (Block D)** — neuer Worker-/Service-Pfad: Webhook → Status-Update + StatusTransition + Activity-Stream + Notification + (bei completed) Signed-PDF-Download in M23 + `signature.signed`-Trigger für M17.
7. **Auto-Stage-Wechsel (M132)** — neu, hängt an M3-Deal-Stage (existiert noch nicht); Tenant-Konfig-Toggle „Auto-Stage-Wechsel" neu.
8. **Multi-Signer-Sequenz-Logik (Block E)** seriell/parallel — neu.
9. **Detail-Sicht im Deal (Block D/§7.5)**: Document-Liste, Pro-Signer-Status, Original-/Signed-PDF-Download, Reminder/Revoke/Resend/Refresh-Operationen — neue UI.
10. **Permissions seeden**: `signature.read/send/revoke/admin` + Rollen-Defaults (GF→admin; Vertrieb→read+send+revoke).
11. **Activity-Stream-Wiring (`logActivity`/M045)** — Service existiert in der Boilerplate nicht als HiveGrid-`@hivegrid/activity`; HiveGrid baut M045 selbst (außerhalb M07-Scope, aber Abhängigkeit).
12. **Naming-Diskrepanz Boilerplate↔HiveGrid-Contracts**: AGENTS.md/INTEGRATION-CONTRACTS referenzieren Pakete `@hivegrid/*` (`packages/ui-hivegrid`, `@hivegrid/notifications`, `@hivegrid/activity`, `@hivegrid/audit`) und `sidebar.config.ts`; in der Boilerplate heißen sie `@toolctrl/*` (`ui-app`, `foundation`, `view-models`) mit Registry-Funktionen statt `sidebar.config.ts`. → Vor M07 klären, ob die EU-Sterilisierung/Rebranding `@toolctrl/*`→`@hivegrid/*` bereits erfolgt ist oder M07 die Boilerplate-Namen nutzt.
---
## Empfohlenes Vorgehen (Reihenfolge)
**Vorbedingungen (außerhalb M07, müssen stehen):** M3-Deal-Modell (M059–M064), M23-Files (M052–M055), M33a-Apps-Engine-Adapter (M008–M010), M045-Activity-Stream, M001-Audit, M011-Notifications, M002-Error-Catalog. M07 dockt daran an — ohne Deal-Modell kein `deal_id`.
1. **Daten-Layer zuerst (M130-Basis):** Die 5 Block-A-Modelle in `prisma/schema/app.prisma` definieren; `SignatureProviderConnection` auf `appsEngine.prisma`-`DataConnection` aufsetzen (OAuth-Token in `config` verschlüsselt). `FileObject` für Source-/Signed-PDF referenzieren. `user-fk-map.ts` ergänzen, Forward-Only-Migration + Inverse-SQL-Kommentar. Permissions seeden.
2. **Querschnitt 1:1 übernehmen, nicht nachbauen:** `foundation` (adapters/outbound-http/idempotency/errors/audit/notifications/permissions/flags), `db` (client/transactions/outbox), `view-models`, `ui-app`-Registries, `i18n`, `feature-flags`, `storage`, `queue`, `notifications`. Feature-Flag `signature` als erstes Gate.
3. **M130 — Send-Flow-UI:** 5-Schritt-Wizard im Deal-Detail. PDF-Picker aus M046 reusen. VMs nach `view-models`-Konvention, Action-Callbacks, Subframe-Adapter, i18n + Klartext-Catalog (25-MB-/Email-/Provider-Hinweise). Sidebar/Breadcrumb-Wiring via `ui-app`-Registries (bzw. Inline-Verlinkung aus Deal — Modul ist deal-kontextuell, kein eigener Top-Level-Sidebar-Eintrag nötig, das im Milestone dokumentieren).
4. **M131 — Provider-Adapter + Webhooks:** PandaDoc zuerst (Standard), DocuSign analog, je via `defineAdapter` + `fetchOutboundHttpWithRedirects`. Inbound-Webhook-Routen nach Stripe-/MailerSend-Blaupause (`webhook-signature`-Auth-Klasse, HMAC-Verify, `$transaction`+Outbox, Idempotenz via `IdempotencyKey`). `SignatureWebhookEvent`-Log schreiben.
5. **M132 — Status-Tracking + Auto-Aktionen:** Worker-Job (nach `form-submission-webhook-delivery`-Vorlage) für Signed-PDF-Download (`storage` signed-URL → `FileObject` → M23), StatusTransition-Audit, `notify()` an Vertriebler, `signature.*`-Outbox-Events für M17, optional Auto-Stage-Wechsel (Tenant-Toggle, hängt an M3-Stage). Detail-Sicht im Deal mit Reminder/Revoke/Resend/Refresh.
6. **DoD-Abschluss:** Unit-Tests für VM-Builder (Zod), Smoke-Test (`e2e/smoke/signature.spec.ts`), Hot-Swap-Drill gegen `ui-mock`, Visual-Regression-Snapshot, Permission-Denied→404, Empty-/Loading-States mit Klartext, Rollback-Pfad dokumentiert.
---
## Quellen (verifiziert per Read/Grep am 2026-06-04)
- Boilerplate: `prisma/schema/{appsEngine,core,notifications,outbox,permissions,featureFlags,queue,app}.prisma`; `packages/foundation/src/{adapters,outbound-http,idempotency,errors}.ts`; `packages/{view-models,ui-app,i18n,feature-flags,storage,queue}/src/`; `apps/api/src/billing/stripe-webhook-route.ts`, `apps/api/src/email-sequences/provider-webhook-route.ts`, `apps/api/src/webhooks/mailersend-signature.ts`, `apps/api/src/route-access-inventory.ts`; `packages/api-client-ts/src/webhooks.ts`; `apps/worker/src/outbox/event-router.ts`.
- Negativ-Befund (Grep, kein Treffer als Domäne): `pandadoc|docusign|esignature|DealSignature|SignatureProviderConnection`; `model (Deal|Sale|Pipeline|Verkauf|Opportunity|Stage)`.
- HiveGrid: `_bmad-output/specs/M07-angebot-signatur.md`, `_bmad-output/pflichtenheft/blocks/block6.md`, `docs/milestones/M13{0,1,2}-*/PLAN.md`, `AGENTS.md`, `docs/INTEGRATION-CONTRACTS.md`, `docs/boilerplate-inventory/{domain-packages,integrations-ki,data-layer,apps-infra}.md`.
</content>
@@ -0,0 +1,125 @@
# Boilerplate-Abgleich: M09 — Email-Inbox + Sync
| Feld | Wert |
|---|---|
| Modul-ID | M09 |
| Name | Email Inbox + Sync (Gmail/Outlook) |
| Milestones | M096 (Gmail/Outlook-OAuth + Sende-Domain), M097 (Sync + Inbox-UI + Threading + Auto-Verknüpfung), M098 (Versand + Vorlagen), M099 (Tracking + Delivery-Status + Bounces) |
| Block | Block 5 · Pflichtenheft 9.1-9.7 |
| Spec | `_bmad-output/specs/M09-email-inbox.md` |
| **Reuse-Level** | **medium** (solides E-Mail-/Worker-/Adapter-Fundament vorhanden; der Kern von M09 — User-Mailbox-OAuth-Sync, Push-Webhooks, DKIM-Sende-Domain, Auto-Match — fehlt komplett und ist neu zu bauen) |
> Quelle Boilerplate (NUR GELESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`. Verifiziert per Grep/Read, nicht nur aus Inventur übernommen.
## Kurz-Verdict
Die Boilerplate liefert ein **Sending-/Marketing-/Transaktions-Mail-Fundament** (MailerSend-Provider, Queue, Templates, Outbox-Mail-Routing, Bounce-Webhook-Pattern, Open/Click-Tracking) und ein generisches **App-/DataConnection-/Sync-Run-Modell** (`appsEngine.prisma`) plus ein vorbildliches **Provider-Adapter-Pattern** (`marketing-outbound`). Das ist **gut für M098/M099** und als **Vorlage** für das Adapter-Interface aus Block J nutzbar.
Der **fachliche Kern von M09 fehlt aber vollständig**: Es gibt **keine** Gmail-/Microsoft-Mailbox-OAuth-Anbindung (mit Mail-Scopes), **keine** Pub/Sub- oder Graph-Subscription-Push-Sync, **keine** DKIM/SPF/DMARC-Sende-Domain-Verifikation, **keine** Auto-Match-Logik (Mail→Kontakt/Deal/Projekt) und das vorhandene `email.prisma`-Modell ist viel zu dünn (kein Tenant-Scope auf `Email`, kein Thread, keine Labels, kein gespiegelter Mailbox-Zustand).
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `packages/mail/src/types.ts` | `MailProvider`-Interface, `SendMailInput` (to/cc/bcc/subject/html/text/attachments/`inReplyTo`/`references`/`replyTo`/`sendAt`/`idempotencyKey`/`tenantId`/`priorityOverride`), `SendMailResult` | **als-vorlage** für den Outbound-Compose-Send-Pfad (M098). Versand geht in M09 jedoch über die **User-Mailbox** (Gmail-API `messages.send` / Graph `sendMail`), nicht über MailerSend → Interface-Form übernehmen, Implementierung neu |
| `packages/mail/src/queue.ts`, `packages/mail/src/mailersend.ts` | `createQueuedMailProvider()` (Versand async via Queue) + MailerSend-Provider | **als-vorlage** für transaktionalen Versand über System-Domain `noreply@hivegrid.de` (Spec Block C, Fallback). MailerSend-Provider zeigt das Provider-Adapter-Muster für SMTP-Side |
| `packages/mail/src/templates-react/` (`render.ts`, `_layout/`, `transactional/`) | React-Email-Templates + Layout-Primitives (BaseLayout, Header, Footer, Button mit `assertSafeUrl`) | **1:1** für transaktionale HiveGrid-Mails (Booking-Confirmation etc. = `Email`-Modell der Spec); `assertSafeUrl`/`InvalidActionUrlError` direkt für sichere Action-Links |
| `packages/marketing-outbound/src/types.ts` | `MarketingOutboundAdapter<TConfig>`-Interface (`type`/`parseConfig`/`send`), `adapterRegistry`/`resolveAdapter`, `adapterFetch()` (Timeout + SSRF-Allowlist), `maskEmailIfRequested()` (PII) | **als-vorlage** für `EmailProviderInterface` (Spec Block J / LP-11): identisches "Adapter-Interface + Registry + `resolveAdapter`"-Pattern für `GmailAdapter`/`MicrosoftAdapter`. SSRF-/PII-Helfer-Muster übernehmen |
| `packages/queue/src/payloads.ts`, `names.ts`, `producers.ts` | `queueNames.email`, `TransactionalMailJob`, `WebhookDeliveryJob`, `enqueueJob()`, `buildIdempotentJobId()`, `buildRetryJobOptions()` | **1:1/anpassen** — Basis für M09-Jobs (Initial-Sync, Push-Verarbeitung, Webhook-Renewal, Token-Refresh, DNS-Probe, Bounce). Neue typisierte Job-Payloads + ggf. neue Queue-Namen ergänzen |
| `packages/queue/src/priority.ts` | `resolveJobPriorityForTenant()` (plan-basiert), Prioritäten CRITICAL/HIGH/NORMAL/LOW | **1:1** für Quotenschutz/Drosselung pro Tenant (M098 9.6, M099) |
| `apps/worker/src/jobs/transactional-mail-outbox*` (Gruppe `mail`) | Outbox→Mail-Versand-Job, Worker-Gruppe `mail` (Concurrency 5) | **als-vorlage** für die M09-Worker-Jobs; Gruppen-/Concurrency-Modell direkt übernehmen |
| `apps/worker/src/outbox/event-router.ts` | `DEFAULT_OUTBOX_ROUTING` mit Prefix→Queue (u.a. `mail.`, `webhook.`, `notification.`, `audit.`, longest-prefix-wins) | **anpassen** — neue Prefixes (z.B. `email.sync.`, `email.match.`) registrieren für M09-Outbox-Events |
| `apps/worker/src/index.ts` + `apps/worker/src/jobs/*` (Cron-Muster, z.B. `dsgvo-grace-cron.ts` 24h, `workflow-execution-stalled-reconciler` 5m) | Single-instance Cron-Scheduler-Registrierung | **als-vorlage** für die M09-Cron-Jobs: DNS-Verifikation alle 5 Min (Block C), Microsoft-Subscription-Renewal täglich (Block D), Token-Refresh alle 30 Min (Block B), Fallback-Polling-Watchdog 4h (Block D) |
| `apps/api/src/email-sequences/provider-webhook-route.ts` + `apps/api/src/webhooks/mailersend-signature.ts` | Inbound-Provider-Webhook-Route mit Signaturverifikation + Bounce-Event-Mapping (`hard_bounced`/`soft_bounced`/`rejected`/`spam_complaint`) | **als-vorlage** für die Push-/Bounce-Webhook-Endpunkte: `/api/v1/webhooks/email/gmail`, `/api/v1/webhooks/email/microsoft` (Block D) und Delivery-/Bounce-Webhooks (M099). Hard-/Soft-Bounce-Mapping direkt wiederverwendbar |
| `apps/api/src/route-access-inventory.ts` (Klasse `webhook-signature`) | Auth-Klassen-Matrix inkl. `webhook-signature` für signierte Provider-Webhooks | **1:1** — neue M09-Webhook-Routen unter `webhook-signature` einordnen |
| `apps/web/app/modules/admin-sso/client.server.ts` + `state.server.ts` + `apps/web/app/routes/auth.admin.callback.tsx` | `openid-client`-Wrapper: Issuer-Discovery, PKCE/state/nonce-Generierung, Code-Exchange im Callback | **als-vorlage** für den OAuth-Connect-Flow (Block B). ACHTUNG: existierend nur für **Login-SSO (Authentik OIDC)**, NICHT für Gmail/Graph mit Mail-Scopes → Flow-Skelett übernehmen, Provider/Scopes/Token-Storage neu |
| `packages/storage/src/index.ts` + `signed/` + `scan/` | S3/Scaleway-Adapter, Signed-Upload/Download-URLs, ClamAV-/magic-bytes-Virus-Scan, Quarantäne | **1:1** für `EmailAttachment`-Storage (Spec: `tenants/{tenantId}/emails/{messageId}/{filename}`, LP-13 EU-Storage), Lazy-Download von Provider-Side, Download-Links im Detail-View |
| `packages/db/src/outbox.ts` (`publishOutboxEvent`) + `prisma/schema/outbox.prisma` | Transaktionales Outbox-Pattern (atomarer Side-Effect mit DB-Write, `dispatchKey`-Idempotenz) | **1:1** — jeder M09-Side-Effect (neue Mail gespiegelt → Auto-Match → Activity → Notification) läuft über Outbox |
| `packages/db/src/client.server.ts`, `transactions.server.ts` | `getWriteDbClient`/`getReadDbClient`, `runDbTransaction` | **1:1** Fundament; Read-Replica für Inbox-Listen-Heavy-Queries |
| `packages/db/src/dsgvo/user-fk-map.ts` | Pflicht-Karte aller User-FKs (CI-Test bricht sonst) | **anpassen (Pflicht)** — neue M09-Modelle mit User-FK (`owner_user_id`, `manual_override_user_id`, `EmailRead.reader…`) eintragen |
| `packages/realtime/src/*` (SSE) | SSE-Event-Serialisierung + Notification-Stream | **1:1** für Live-Inbox-Badge (Sidebar `badge: 'count'` für ungelesene Mails, Integration-Contracts §2) + Sync-Status-Live-Update |
| `packages/search/src/*` (Meilisearch, tenant-scoped, Outbox-Reindex) + `schemas/` | Such-Index-Pattern, `bulkIndex`, `searchInIndex`, Outbox-Publisher | **als-vorlage** für Inbox-Volltext-Suche (M097: Subject+Body+Absender). Spec nennt zusätzlich Trigram-Index in Postgres als Alternative — Meili-Pattern ist die saubere Querschnitt-Variante |
| `packages/i18n/*` + `apps/web/app/locale/*` (Namespace `mail` existiert) | i18n-Setup de/en, Klartext-Keys, `assertI18nLabel`-Zwang | **1:1** — alle M09-Klartext-Diagnose-Texte (LP-10) als i18n-Keys; vorhandener `mail`-Namespace erweiterbar |
| App-Shell: `packages/view-models`, `packages/ui-app` (Registry-Factories), `apps/web/app/application/sidebar/*`, `uiRegistry.ts` | Datengetriebene Sidebar mit Permission/Flag-Gating, `VMState`-Statusmodell, Breadcrumb-Registry, stabile `data-ui-id` | **1:1/anpassen** — Inbox-Route + Sidebar-Eintrag (Gruppe KOMMUNIKATION, Integration-Contracts §1) + Breadcrumb + View-Model-Vertrag |
| `packages/ui-mock` + Hot-Swap (`HotSwapPageRenderer`) + `apps/storybook` (lost-pixel, axe) | Hot-Swap-Drill, Visual-Regression, a11y-Gates | **1:1** für die DoD-Pflichten (Hot-Swap-Drill, Visual-Snapshot) |
| `prisma/schema/notifications.prisma` (`NotificationDelivery`, prefs, `DeviceToken`) + Notification-Wiring (Contracts §7 `notify()`) | Notification-Querschnitt In-App/Email/Push | **1:1** für OAuth-Disconnect-/revoked-/Send-Fehler-Benachrichtigungen (Block B/D, LP-10) |
| `prisma/schema/core.prisma` (`AuditEvent` Hash-Kette) + Audit-Wiring (Contracts §6, auto via Middleware; `auditEvent()` manuell für Nicht-Prisma) | Tamper-evidenter Audit-Trail | **1:1** — manueller Match-Override loggt `audit_event` (Spec AV #6); externe Provider-Calls manuell auditieren |
| `prisma/schema/featureFlags.prisma` + Feature-Flag-Querschnitt | Modul ohne Deploy abschaltbar (DoD-Pflicht) | **1:1** |
| `packages/entitlements` / Permissions (`permissions.prisma`, Contracts §10) | RBAC-Fundament + Permission-Key-Konvention | **anpassen** — neue Keys `email.read_own`/`email.read_all`/`email.write`/`email.admin` + Bundle-Mapping (Spec Block I) ergänzen |
---
## Vorhandene Daten-Modelle (Prisma) — Bestand vs. Bedarf
Schema-Pfad: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`
### `email.prisma` (10 Modelle) — teilweise relevant, aber dünn
- **`Email`** (`messageId @unique`, `type` inbound/outbound, `date`, `subject`, `fromEmail/fromName`, `toEmail/toName`, `textBody`, `htmlBody`) — deckt grob die HiveGrid-eigene `Email`-Entität (Spec Block A, transaktionale Mails) ab. **Lücken ggü. Spec:** **kein `tenantId`** (nur indirekt über `TenantInboundAddress`), kein `direction`-Enum, keine `cc/bcc`-Arrays am Modell (CC via separatem `EmailCc`-Modell), kein `delivery_status`/`bounce_type`/`bounce_reason`, keine `related_contact/company/deal/project`-FKs, kein `archived_at`, kein `provider_message_id` vom SMTP-Provider getrennt.
- **`EmailRead`** (`emailId`, `userId`, `createdAt`) — existiert, aber semantisch **anders**: trackt "von HiveGrid-User gelesen", nicht "vom Empfänger gelesen" (Spec `EmailRead` = Pixel-Tracking mit `reader_ip`/`reader_user_agent`). → **anpassen/erweitern**.
- **`EmailCc`** — separate CC-Tabelle. Spec modelliert cc/bcc als Arrays direkt am Message-Modell. → Designentscheidung.
- **`EmailAttachment`** (`name`, `type`, `length`, `content`, `publicUrl`, `storageBucket`, `storageProvider`) — gute Basis für Spec-`EmailAttachment`. **Lücken:** kein `parent_kind`/`parent_id`-Polymorphismus (hängt fest an `Email`), kein `provider_attachment_id`/`download_status` für Lazy-Download.
- **`EmailSender`** (`provider`, `stream`, `apiKey`, `fromEmail`, `replyToEmail`) — SMTP-Sender-Config. Nutzbar als Anker für transaktionalen Versand, **aber** das ist NICHT die DKIM-verifizierte `TenantSendingDomain` der Spec (kein `dkim_*`, kein `verification_status`).
- **`TenantInboundAddress`** (`address @unique`) — Name kollidiert mit Spec-`TenantInboundAddress`, ist aber simpler (kein `local_part`/`full_address`/`purpose`-Enum/`archived_at`). → **anpassen** oder neues Modell.
- **`Campaign`, `OutboundEmail`, `OutboundEmailOpen`, `OutboundEmailClick`** — Marketing-Kampagnen + Open/Click-Tracking. **Gehört primär zu M10 (Marketing)**, aber `OutboundEmail` (mit `sentAt`/`deliveredAt`/`bouncedAt`/`spamComplainedAt`/`unsubscribedAt`) ist ein **direkter Template-Bestand für M099** (Delivery-Status + Bounce-Tracking) und für Spec-`Email.delivery_status`.
### `appsEngine.prisma` (5 Modelle) — Template für OAuth-Connection + Sync-Runs
- **`App`** (`@@unique([tenantId, type])`, `config` JSON, `isActive`) — "installierte App pro Tenant". **als-vorlage** für die Email-Integration-Aktivierung pro Tenant.
- **`DataConnection`** (`type` "oauth2"/"rest-api"/"webhook", `config` = **encrypted JSON credentials**) — **direkt relevant** als Speicherort-Muster für OAuth-Tokens. Spec verlangt aber dedizierte Felder (`oauth_access_token_encrypted`, `oauth_refresh_token_encrypted`, `oauth_token_expires_at`, `oauth_scope_granted`, `sync_status`, `webhook_subscription_id`, `webhook_expires_at`) → entweder `DataConnection.config` als JSON nutzen ODER (empfohlen) dediziertes `EmailIntegrationMailbox`-Modell bauen.
- **`AppSyncRun`** (`status` pending/running/completed/partial/failed, `executionMode` manual/scheduled/webhook, `itemsProcessed/created/updated/failed`, `error`) — **als-vorlage** für `EmailIntegrationSyncCursor.initial_sync_status`/`progress` (Block A/D) und für Sync-Run-Observability.
- **`AppSyncRunLog`**, **`AppSyncItem`** (Source→Destination-Mapping + Rollback) — nützliches Muster für Per-Message-Sync-Logging, eher als Vorlage denn 1:1.
### `accounts.prisma` — OAuth-Bestand
- **`User.googleId`/`User.githubId` (`@unique`)** — Login-OAuth-Identitäten. **NICHT** das, was M09 braucht (das sind Auth-Login-IDs, keine Mailbox-Connections mit `gmail.modify`/`Mail.ReadWrite`-Scopes + Refresh-Tokens). Nur als Hinweis, dass Google-OAuth-Login schon existiert.
### `emailSequences.prisma` (3) + `marketingLeads.prisma` (`MarketingIntegration`)
- Bounce-/Open-/Click-Felder + verschlüsselte `configJson` — Template-Bestand für M099 und für verschlüsselte Provider-Config (relevanter für M10).
**Vorgesehener Ort für neue HiveGrid-Modelle:** `prisma/schema/app.prisma` (leerer Platzhalter `// custom database models`) — hier kommen die M09-eigenen Modelle hinein, ohne Boilerplate-Domänen zu verändern.
---
## Lücken / komplett neu zu bauen
Verifiziert: kein Treffer in `packages/`, `apps/`, `prisma/` für Gmail-API/`googleapis`, Pub/Sub, `graph.microsoft`/Graph-Subscriptions, `gmail.modify`/`Mail.ReadWrite`-Scopes, DKIM/SPF/DMARC, Sending-Domain-Verifikation. (Grep-Treffer auf "gmail/google/dkim" waren ausschließlich Falsch-Positive in feature-flags, config-catalog, Email-Template-Texten und `node_modules`.)
1. **Mailbox-OAuth-Connect (Block B) — KOMPLETT NEU.** Gmail-OAuth (`gmail.modify`/`gmail.send`/`gmail.labels`/`userinfo.email`) und Microsoft-OAuth (`Mail.ReadWrite`/`Mail.Send`/`User.Read`/`offline_access`). Vorhandener `openid-client`-Flow (Admin-SSO) nur als Skelett. Token-Refresh-Worker, Disconnect+Token-Revoke, `sync_status`-Lifecycle.
2. **Push-Sync (Block D) — KOMPLETT NEU.** Gmail-Watch-API + Pub/Sub-Push-Endpoint, Microsoft-Graph-Subscription auf `/me/messages` + tägliches Renewal (3-Tage-Lifetime), `historyId`/`deltaToken`-Cursor-Sync, Fallback-Polling-Watchdog (4h). Webhook-Routen `/api/v1/webhooks/email/{gmail,microsoft}` (Signatur-/Token-Verifikation analog `mailersend-signature`).
3. **Provider-Adapter `EmailProviderInterface` (Block J / LP-11) — NEU (Pattern vorhanden).** `connect/disconnect/fetchMessages/getMessage/sendMessage/subscribeToWebhook/renewWebhook/revokeWebhook/markRead/downloadAttachment` + `GmailAdapter`/`MicrosoftAdapter`. Interface-/Registry-Muster aus `marketing-outbound` als Vorlage; Implementierungen neu. Klartext-Fehler-Übersetzung pro Adapter (LP-10).
4. **Sende-Domain DKIM/SPF/DMARC (Block C) — KOMPLETT NEU.** `TenantSendingDomain`-Modell (Spec-Version), DKIM-Schlüsselpaar-Generierung (2048 Bit, encrypted Private-Key), DNS-TXT-Record-Bau (DKIM/SPF/DMARC), DNS-Lookup-Verification-Cron (alle 5 Min, 7-Tage-Timeout), Copy-to-Clipboard-UI. Plattform-Fundament für M10.
5. **Auto-Match-Logik (Block E) — KOMPLETT NEU.** Mail→Kontakt (Email-Match gegen `ContactEmail`/`Lead.email`), Mail→Deal/Projekt (Subject-Pattern `[Deal #X]`/`[Auftrag #X]`/`[Lead #X]`), Heuristik (genau-1-offener-Deal → medium), manueller Override (hält stand), Edge-Cases (Mehrfach-Contacts, eigene Adresse, Newsletter/Bulk via List-Unsubscribe-Header). Setzt M042 (Kontakt), M060/M066 (Deal/Auftrag) voraus.
6. **Vollständiges M09-Datenmodell — NEU (Teil-Bestand).** `EmailIntegrationMailbox`, `EmailIntegrationMessage` (mit Thread/Labels/Match-Feldern/Trigram-Suche), `EmailIntegrationSyncCursor`, `EmailIntegrationWebhookEvent` (mit Retention 30/90 Tage). Bestehende `Email`/`EmailAttachment`/`EmailRead`/`TenantInboundAddress` müssen erweitert oder zugunsten Spec-konformer Modelle ergänzt werden (Tenant-Scope, direction, Match-FKs, delivery_status, polymorphe Attachments).
7. **Inbox-UI (Block F) — NEU (Shell-/Komponenten-Fundament vorhanden).** Listen-View mit Filtern (Mailbox/Direction/Read/Verknüpfung/Datum/Anhang), Volltext-Suche, Bulk-Actions, Cursor-Pagination; Detail-View mit Thread-Aggregat, CSP-gehärtetem HTML-Body-Render ("Bilder anzeigen"-Toggle = Tracking-Pixel-Schutz), Attachment-Liste, Verknüpfungs-Editor, Reply/Reply-All/Forward, Provider-Deep-Link. shadcn-Tabellen/Modale/Forms aus `apps/web` wiederverwendbar, aber inbox-spezifische Komponenten neu.
8. **Outbound-Compose (Block G) — NEU.** Rich-Text-Editor (TipTap laut Milestone-Hinweis in Deps; verifizieren), To/CC/BCC mit Contact-Autocomplete, Mailbox-Auswahl, Anhang-Upload (≤25 MB), Send über User-Mailbox (nicht MailerSend), Save-as-Draft, Compose-Aufruf aus Kontakt-/Deal-/Projekt-/Inbox-Kontext mit Pre-Fill + Subject-Pattern. BCC-Logging-Adresse.
9. **OAuth-Token-Encryption (KMS) — NEU/zu klären.** Kein dediziertes Crypto-/KMS-Paket gefunden (nur `…Encrypted`-Spalten-Konvention + verschlüsselte `configJson` in marketing/appsEngine). Konkretes KMS-Setup (Scaleway-managed-Key) ist offener Detail-Punkt der Spec.
10. **Vorlagen + Variable-Resolution (M098 9.7) — NEU.** Quick-Reply-Templates + `{{first_name}}`-Resolver gegen Kontakt-Properties. React-Email/Render vorhanden, aber Variable-Resolver gegen CRM-Daten neu.
11. **Bounce-/Sperrliste (M099) — NEU (Teil-Bestand).** Hard-Bounce→Sperrliste-Auto-Add pro Tenant, Soft-Bounce 3×-Retry/24h. Bounce-Event-Mapping (hard/soft/rejected/spam) aus `email-sequences/provider-webhook-route.ts` wiederverwendbar; Sperrlisten-Modell + Kontakt-Detail-Hinweis neu.
12. **Activity-Stream-Integration (Block H) — Wiring NEU.** `email_received`/`email_sent`/`email_match_changed` via `logActivity` (Contracts §5, Service kommt aus M045). Permission-gegateter Activity-Inhalt (`email.read_own` vs. nur "Email-Aktivität (nicht einsehbar)").
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Fundament aus BP übernehmen (1:1), bevor M09-Logik beginnt:**
1. Datenmodell in `prisma/schema/app.prisma` anlegen (`EmailIntegrationMailbox/Message/SyncCursor/WebhookEvent`, Spec-`TenantSendingDomain`, erweitertes `Email`/`EmailAttachment`/`EmailRead`/`TenantInboundAddress`). Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD). **`user-fk-map.ts` zwingend ergänzen** (sonst CI-Bruch).
2. Permission-Keys + Bundle-Mapping (Block I) in `packages/entitlements` ergänzen; Sidebar-Eintrag (Gruppe KOMMUNIKATION) + Route + Breadcrumb + Feature-Flag verdrahten (Integration-Contracts §1-4, §10).
3. Outbox-Routing-Prefixes + neue typisierte Queue-Jobs + Worker-Gruppe `mail`/neue Gruppe registrieren (aus `packages/queue` + `apps/worker`-Mustern).
**Phase 1 — M096 (Connect-Fundament):**
4. OAuth-Connect-Flow aus `admin-sso/client.server.ts`-Skelett ableiten, aber Gmail-/Graph-Provider + Mail-Scopes + verschlüsseltes Token-Storage neu. Token-Refresh-Cron (Muster aus `apps/worker/src/jobs`).
5. `EmailProviderInterface` + `GmailAdapter`/`MicrosoftAdapter` nach `marketing-outbound`-Adapter-Pattern (Registry + `resolveAdapter` + `adapterFetch`-Härtung).
6. DKIM/SPF/DMARC-Sende-Domain komplett neu (Schlüsselgenerierung, DNS-Record-Bau, 5-Min-Verifikations-Cron, 7-Tage-Timeout).
**Phase 2 — M097 (Sync + Inbox):**
7. Push-Webhook-Routen (Gmail Pub/Sub, Microsoft Graph) nach `provider-webhook-route.ts`-Muster + Signatur-/Token-Verifikation; Initial-Sync-Job mit Cursor; Renewal-/Watchdog-Cron.
8. Auto-Match-Logik (neu) + Activity-Wiring (`logActivity`) + Outbox.
9. Inbox-UI (Liste+Detail) auf App-Shell/shadcn-Fundament; Volltext-Suche via `packages/search`-Pattern; Attachments via `packages/storage` (signed URLs, EU-Bucket); SSE-Badge via `packages/realtime`.
**Phase 3 — M098/M099 (Versand + Tracking):**
10. Outbound-Compose + Send über User-Mailbox (Adapter `sendMessage`), Spiegelung als `direction=outbound`-Message; Vorlagen + Variable-Resolver; transaktionaler Fallback-Versand über MailerSend/`packages/mail` für System-Mails.
11. Delivery-Status/Bounce: Bounce-Webhook + hard/soft-Mapping (aus `email-sequences` übernehmen), Sperrliste pro Tenant, Quotenschutz via `queue/priority.ts`-Plan-Prioritäten.
**Querschnitt durchgängig (DoD):** i18n-Keys (Namespace `mail` erweitern), Klartext-Diagnose (LP-10) aus M002-Catalog, View-Model-Pflicht (Contracts §11), Audit auto/manuell, Notifications via `notify()`, Smoke-Test + Hot-Swap-Drill + Visual-Snapshot, Customer-Portal-Sichtbarkeit explizit (Default: nicht sichtbar), Permission-Denied→404.
**Vor Bau zu validieren (Spec-Hinweis):** Microsoft-3-Tage-Renewal-Lifecycle und DKIM-DNS-Check mit echter Domain; konkretes KMS-Setup für Token-Verschlüsselung; ob TipTap tatsächlich in den Boilerplate-Deps liegt (Milestone-Annahme).
@@ -0,0 +1,147 @@
# Boilerplate-Abgleich: M10 — Email-Marketing
| Feld | Wert |
| --- | --- |
| **Modul-ID** | M10 (Modul 10) |
| **Name** | Email-Marketing |
| **Milestones** | M100 (Kampagnen-Editor / Block-Style + Personalisierung + Vorschau + Test-Mail), M101 (Empfänger-Segmente / CRM-Filter), M102 (Versand-Engine + DKIM/SPF + Daily-Cap + Frequenz-Schutz + Pflicht-Footer), M103 (A/B-Tests Phase 2 + Reporting/Stats), M104 (Unsubscribe + Bounce-Handling + Suppression) |
| **Pflichtenheft-Block** | Block 5, Modul 10 (`_bmad-output/pflichtenheft/blocks/block5.md` §10.1–10.12) |
| **Detail-Spec** | `_bmad-output/specs/M10-email-marketing.md` |
| **Reuse-Level** | **medium** |
## Reuse-Verdikt (Kurzfassung)
M10 ist das **best-vorbereitete Kommunikations-Modul** der Boilerplate. Es existiert ein **vollständiger Email-Marketing-Vertikalschnitt** im Web-App (`apps/web/app/modules/emailMarketing/**`) mit Tenant- UND Admin-Scope, hinter Feature-Flag `email-marketing` (`packages/entitlements`): Kampagnen-CRUD, Sender-Verwaltung, Outbound-Email-Liste, Summary-Dashboard, Test-Mail/Preview, Personalisierungs-Token-Replace, Versand über MailerSend mit Open/Click-Tracking-Settings. Die Datenmodelle `Campaign`, `OutboundEmail`, `OutboundEmailOpen`, `OutboundEmailClick`, `EmailSender` (`prisma/schema/email.prisma`) decken den Kern der Spec-Block-A-Entitäten **teilweise 1:1** ab.
**Aber** — und das drückt das Verdikt von `high` auf `medium`:
1. **Vier zentrale Spec-Modelle fehlen komplett:** `Unsubscribe`, `EmailSuppressionList`, `RecipientSegment`, `EmailTemplate`. Verifiziert per Grep über alle `*.prisma`: kein Treffer. Unsubscribe lebt heute nur als `OutboundEmail.unsubscribedAt`-Flag bzw. `EmailSequenceRun.status='unsubscribed'` — **keine tenant-weite, CRM-Lösch-persistente Sperrliste** (Spec Block H/G + 10.5.5).
2. **Zwei parallele, NICHT verbundene Email-Systeme:** (a) Tenant-`Campaign`/`OutboundEmail` (Broadcast) und (b) operator-seitige Drip-Funnel (`EmailSequence`/`EmailSequenceRun`/`EmailSequenceStepDelivery`, `packages/email-sequences`). **Die öffentlichen Tracking-/Unsubscribe-Routen (`/unsubscribe/$token`, `/email/track-open`, `/email/track-click`) operieren ausschließlich auf dem SEQUENCE-System, NICHT auf `OutboundEmail`.** Für M10 muss Tracking/Unsubscribe auf `Campaign`/`OutboundEmail` umverdrahtet bzw. neu gebaut werden (die HMAC-Token-Mechanik + Pixel-Route sind aber 1:1-Vorlagen).
3. **Anti-Spam-/Versand-Robustheit fehlt fast vollständig:** kein Daily-Cap pro Plan, kein Frequenz-Cap/Empfänger/Woche, kein Spam-Score-Check, kein Throttling pro Tenant/Empfänger-Domain, **kein geplanter Versand**, **kein BullMQ-Versand-Worker für Kampagnen** (Versand läuft heute synchron in-process via `mapWithConcurrency`, Konkurrenz 5 — Spec K + E verlangen Queue + Cron + Throttle).
4. **DSGVO-Opt-In-Dokumentation fehlt:** kein `marketing_opt_in_at/_source/_reference/_text_snapshot` (Spec Block H 10.7). Heute nur ein CRM-Boolean `marketingSubscriber` (Custom-Field via `CrmService`).
5. **Provider:** Boilerplate nutzt **MailerSend** (`packages/mail`) — Spec/LP-13 verlangt EU-SMTP (Scaleway TEM/Brevo EU/Mailjet EU). Provider-Adapter-Pattern existiert (`MailProvider`-Interface), aber MailerSend ist kein EU-Anbieter → Adapter-Austausch nötig (offener Spec-Punkt).
6. **Keine M9-Sending-Domain-Verknüpfung:** `EmailSender` hält `apiKey`/`fromEmail`/`provider` direkt, **kein FK auf `TenantSendingDomain`** (existiert in M9 noch nicht). DKIM-Verifikations-Gate vor Versand fehlt.
7. **Kein Segment/Filter-Tree:** Empfänger werden heute über `EntityViewsApi` (CRM-Entity-Views) als Quelle gezogen — solide Wiederverwendung als Basis für M101, aber das spezifizierte `RecipientSegment` mit verschachteltem AND/OR-JSONB-Filter-Tree + Static-Snapshot + Auto-Exclusion-Aufschlüsselung ist neu.
8. **Layer-Disziplin:** Bestehender Code folgt dem ToolCTRL-Muster (Service direkt aus Route, `db.server` in Modul-Code), NICHT der HiveGrid-DoD (View-Model-Layer `packages/view-models`, `packages/ui-hivegrid`, Subframe-Adapter, kein Prisma in UI). → **Übernahme erfordert Re-Layering** in die HiveGrid-Struktur.
Fazit: Solide Fachbasis (Campaign-Send + Tracking-Datenmodell + MailerSend-Adapter + UI-Bausteine + i18n) spart erheblich Arbeit, aber die DSGVO-/Anti-Spam-/Segment-/Suppression-/Scheduling-Hälfte ist Neubau. Daher `medium`.
---
## Übernehmbar aus Boilerplate
> Boilerplate-Wurzel (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/email.prisma` (`Campaign`, `OutboundEmail`, `OutboundEmailOpen`, `OutboundEmailClick`, `EmailSender`) | Kern-Datenmodell: Kampagne (name/subject/html/text/status/track/sentAt), Outbound-Email pro Empfänger (email, sentAt/deliveredAt/bouncedAt/spamComplainedAt/unsubscribedAt, FK auf `Row` als Kontakt), Open/Click-Tracking-Tabellen, Sender | **anpassen** — Felder fehlen massiv gegenüber Spec Block A (preheader, recipient_segment_id, recipient_list_snapshot, scheduled_at, *_count-Aggregate, tracking_token/unsubscribe_token unique, bounce_type, personalization_payload, delivery_status-Enum, Indizes). `tenantId` ist `String?` (operator-nullable) → für RLS auf NOT-NULL-Tenant-Scope härten |
| `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` | `getSummary` (Open/Click-Rate-Aggregation), `createCampaignDraft`, `sendCampaign` (mapWithConcurrency), `sendCampaignTest` (max 5), `sendPreview`/`sendContactPreview`, `replaceVariables` (`{{firstName}}`/`{{lastName}}`/`{{email}}`/`{{job_title}}`/`{{company_name}}`) | **als-vorlage** — Logik-Gerüst für Versand + Personalisierung übernehmbar; muss aber in `app/domain/**`-Layer + BullMQ-Worker (Spec E) statt synchron, Token-Format auf `{{first_name}}` (Spec C) angleichen, Custom-Field-Token `{{custom.x}}` ergänzen, Auto-Exclusion + Footer-Injection + Cap-Checks fehlen |
| `apps/web/app/modules/emailMarketing/services/EmailMarketingSenderService.server.ts` | `sendBroadcast()` Provider-Switch → `sendMailerSendBroadcast` (MailerSend-Send mit `settings.trackClicks/trackOpens`, replyTo, tags) | **als-vorlage** — Send-Adapter-Pattern; Provider muss auf EU-SMTP (LP-13) gewechselt/ergänzt werden; DKIM-/Domain-Gate fehlt |
| `apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts` | `getAllCampaigns`/`getCampaign` (mit recipients+opens+clicks+contactRow-Include), `createCampaign` (nested recipients), `updateCampaign` (recipient-replace), `deleteCampaign`, `groupCampaigns` (by status) | **anpassen** — tenant-scoped Queries direkt verwendbar als Basis; auf `withTenantScope()` (M004) + neue Felder/Snapshot anheben |
| `apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts` | `getAllOutboundEmails` (paginiert), `createOutboundEmail(Test)`, `updateOutboundEmail` (sentAt/deliveredAt/bouncedAt/spamComplainedAt/unsubscribedAt), `openedOutboundEmail`/`clickedOutboundEmail`, `unsubscribeCampaignRecipient`, `countOutboundEmails` | **anpassen** — Pro-Empfänger-Liste + Status-Updates (Spec F „Pro-Empfänger-Anzeige") fast vollständig; Bounce-Klassifikation (hard/soft), Suppression-Add, Activity-Wiring fehlen |
| `apps/web/app/modules/emailMarketing/db/emailSender.ts` + `services/EmailMarketingSenderService.server.ts` + `components/EmailSenderForm.tsx` + `routes/Senders_*.ts` + `components/senders/Senders{List,New,Edit}Route.tsx` | Sender-Verwaltung End-to-End (CRUD + Form + List/Edit/New) | **als-vorlage** — Sender-UI/-Flow direkt nachnutzbar; Validierung „from_email-Domain muss zu Sending-Domain passen" + M9-`sending_domain_id`-FK + DKIM-Status-Anzeige + is_default + archived_at ergänzen |
| `apps/web/app/modules/emailMarketing/components/campaigns/CampaignsNewRoute.tsx` + `CampaignsEditRoute.tsx` + `CampaignsListRoute.tsx` + `campaignDefaults.ts` | Kampagnen-Editor (Name/Sender/Empfänger-View/Subject/HTML-Body via `InputContent` WYSIWYG+Markdown), Test-Mail-Button, Default-HTML-Body, Liste | **als-vorlage** — Editor-Grundgerüst; der spezifizierte 6-Schritt-Wizard (Basis→Inhalt→Empfänger→Test→Zeitpunkt→Bestätigung mit Pflicht-Checks), Mobile/Desktop-Vorschau, Spam-Score, Auto-Exclusion-Anzeige fehlen. Re-Layering nach `ui-hivegrid`/Subframe-Adapter nötig |
| `apps/web/app/modules/emailMarketing/components/OutboundEmailsTable.tsx` + `outboundEmails/OutboundEmailsListRoute.tsx` + `EmailMarketingSummaryRoute.tsx` + `routes/EmailMarketing_Summary.ts` | Outbound-Tabelle (Status/Opens/Clicks/Kontakt), Summary-Dashboard (avg Open/Click-Rate, sent/delivered) | **als-vorlage** — deckt Spec F „Stats-Aggregation" + „Pro-Empfänger-Liste" teilweise; CTR, Bounce-Raten, Unsubscribe-Rate, Complaint-Rate, Click-Map, Filter nach Status ergänzen |
| `apps/web/app/routes/app.$tenant/email-marketing.tsx` + `email-marketing/{index,activity,senders,campaigns/*}.tsx` | Tenant-Route-Tree mit `SidebarIconsLayout` (Overview/Campaigns/Activity/Senders), `requireTenantProductAccess(featureKeys.emailMarketing)` | **als-vorlage** — Route-Struktur + Feature-Flag-Gate + Sub-Nav; an HiveGrid-Route-Pattern (`/{tenant}/email-marketing/...`, INTEGRATION-CONTRACTS §3) + `sidebar.config.ts`-Eintrag (Gruppe „Kommunikation") + Permission `email_marketing.*` (M004) angleichen |
| `apps/web/app/routes/unsubscribe.$token.tsx` + `app/utils/email/unsubscribeToken.server.ts` + `packages/email-sequences/src/unsubscribe-token.ts` (`signUnsubscribeToken`/`verifyUnsubscribeToken`/`buildUnsubscribeUrl`) | Öffentliche Unsubscribe-Route (GET+POST, kein Login, Token=Auth, idempotent) + HMAC-SHA256-Token-Mechanik (`MARKETING_TOKEN_SECRET`, timing-safe) | **als-vorlage** — exakte Blaupause für Spec Block H Unsubscribe-Page; **aber** Token zeigt heute auf `EmailSequenceRun`, muss auf `OutboundEmail.unsubscribe_token`/`Unsubscribe`-Modell + `EmailSuppressionList`-Add + Grund/Feedback-Formular + Activity-Eintrag umgebaut werden. List-Unsubscribe-One-Click-Flow (RFC-8058) ist bereits berücksichtigt |
| `apps/web/app/routes/email/track-open.$deliveryId[.gif].tsx` + `track-click.$deliveryId.tsx` | 1×1-GIF-Pixel-Route (Cache-Control no-store, idempotenter First-Open via `updateMany`), Click-Redirect-Route | **als-vorlage** — Pixel-/Redirect-Mechanik 1:1; Ziel-Modell von `EmailSequenceStepDelivery` auf `OutboundEmail`/`OutboundEmailOpen`/`OutboundEmailClick` umverdrahten; `link_url`/`link_label`/`reader_ip`(anonymisiert)/`reader_user_agent`/`is_first_open` ergänzen (Spec Block F) |
| `apps/api/src/webhooks/mailersend-signature.ts` (`verifyMailerSendWebhookSignature`) | Inbound-Webhook-HMAC-Verify (timing-safe, Timestamp-Toleranz, Header-Kandidaten) | **1:1** für Bounce-/Complaint-Webhook-Empfänger (Spec Block G `/api/v1/webhooks/email/bounce`); Provider-Wechsel ggf. anderer Verify |
| `apps/api/src/email-sequences/provider-webhook-route.ts` (`postMailerSendEmailSequenceWebhookRequest`, `parseMailerSendSequenceWebhookPayload`, `MAILERSEND_BOUNCE_EVENT_TYPES`) | Vollständiger Bounce-Webhook-Handler: Signatur→Parse Event-Type (bounced/hard/soft/rejected/spam_complaint)→`providerMessageId`-Lookup→`markDeliveryBounced` | **als-vorlage** — exaktes Pattern für Spec Block G Bounce-Verarbeitung; Ziel-Update muss auf `OutboundEmail` + Hard/Soft-Klassifikation + Suppression-Auto-Add + Soft-to-Hard-Conversion + Complaint→Auto-Unsubscribe + Activity gehen |
| `packages/mail/src/{index,types,mailersend,queue}.ts` (`MailProvider`-Interface, `SendMailInput` mit `listUnsubscribe`, `precedenceBulk`, `settings.trackOpens/Clicks`, `priorityOverride`, `sendAt`, `idempotencyKey`, `tenantId`, `tags`; `createQueuedMailProvider` = BullMQ-Versand mit Prioritäts-Resolver) | Provider-Abstraktion + Queue-Provider. `SendMailInput` deckt List-Unsubscribe-Header, Bulk-Precedence, Tracking-Settings, geplanten Versand (`sendAt`), Idempotenz, Tenant-Priorität bereits ab | **anpassen** — `MailProvider`-Interface 1:1 als LP-11-Adapter-Schicht; **EU-Provider-Adapter (LP-13) neu implementieren** (heute nur `mailersend` + `queue`); `QueuedMailProvider` ist Basis für den Spec-E-Versand-Worker mit Drossel |
| `packages/email-templates/src/{render,theme}.ts` + `components/{Layout,primitives}.tsx` + `sequences/*.tsx` | React-Email-Render (`renderEmail`→`{html,text}`, `htmlToPlainText` mit Anchor-URL-Erhaltung), Layout/Primitives, Sequenz-Templates (welcome/trial-reminder/re-activation/generic-step) | **als-vorlage** — Render-Pipeline + `htmlToPlainText` 1:1; SHK-Branchen-Templates („Wartungs-Erinnerung", „Newsletter Q4", „Service-Aktion", Spec Block I / 10.1.4) sind neu zu erstellen; das spezifizierte `EmailTemplate`-DB-Modell fehlt komplett |
| `packages/mail/src/templates-react/_layout/{Footer,BaseLayout,Button}.tsx` (`assertSafeUrl`, `InvalidActionUrlError`) | Mail-Footer-Layout + URL-Safety-Guard für Action-Links | **als-vorlage** — Basis für Pflicht-Footer (Spec G/10.7.5: Impressum-Adresse + Unsubscribe-Link auto-injiziert + Tracking-Pixel-Hinweis); Footer-Pflicht-Inhalt + Auto-Injection-Logik fehlen |
| `apps/web/app/utils/api/.server/EntityViewsApi` + `CrmService` (`getContactsInRowIds`, `getContact`, `marketingSubscriber`-Boolean, ContactDto firstName/lastName/email/jobTitle/company) | CRM-Entity-Views als Empfänger-Quelle (gefilterte Kontakt-Listen mit pageSize, Row-IDs) + Kontakt-Auflösung + Marketing-Subscriber-Flag | **als-vorlage** — Brücke CRM↔Marketing; Basis für M101-Segmente, aber das spezifizierte `RecipientSegment` (JSONB-Filter-Tree AND/OR, static/dynamic, Auto-Exclusion-Aufschlüsselung, 50-Sample-Vorschau) ist neu zu bauen |
| `packages/marketing-outbound/**` (Adapter-Registry slack/discord/mailchimp/hubspot/brevo/webhook, `resolveAdapter`, `adapterFetch` mit SSRF-Schutz/Timeout) + `apps/worker/src/jobs/marketing-outbound.ts` | Outbound-Integrations-Adapter + isolierter Dispatch-Worker (Outbox-getriggert, Idempotenz, per-Integration-Fehlerisolation) | **als-vorlage** für das LP-11-Adapter-Muster (SMTP-Provider als austauschbarer Adapter) + Worker-Job-Struktur. **Inhaltlich themenfremd** (CRM-Sync zu Drittanbietern, nicht Email-Versand) — nur Pattern/SSRF-Client nachnutzen |
| `packages/email-sequences/src/{engine,step-runner,conditions}.ts` + `apps/worker/src/jobs/email-sequence-{trigger,scheduler,runtime,prisma-store}.ts` | Drip-Sequence-Engine (start/advance Run, delayHours-Scheduling, Conditions-DSL, BullMQ-Step-Scheduler, Prisma-Store-Adapter, Idempotenz `@@unique([sequenceId,triggerEventId])`) | **als-vorlage** — relevant für Spec Block J Trigger-Mails über M17 + (Phase 2) Sequenzen; das injizierbare Store/Queue-Engine-Pattern (testbar) ist HiveGrid-DoD-kompatibel und als Architektur-Vorbild für den Kampagnen-Versand-Worker nutzbar |
| `packages/entitlements/src/features.ts` (`featureKeys.emailMarketing = "email-marketing"`) + `requireTenantProductAccess` | Produkt-/Feature-Gate für Email-Marketing | **anpassen** — Feature-Flag-fähig (DoD M006) vorhanden; um HiveGrid-Permissions `email_marketing.read/write/admin` (M004, Spec Block L) erweitern |
| `apps/web/public/locales/{de,en}/emailMarketing.json` | i18n-Keys für das gesamte Email-Marketing-UI (DE+EN) | **anpassen** — Basis-Wortschatz vorhanden; HiveGrid-i18n-Namespace + Klartext-Texte (Spec „Klartext-Hinweise"-Querschnitt, M002/M003) ergänzen |
| `apps/web/app/modules/emailMarketing/routes/emailMarketingAccess.server.ts` + `email-marketing-auth-boundary.test.ts` | Mutation-Access-Gate (`requireSuperUserOrAdmin` bei Tenant-Scope) + Auth-Boundary-Test | **anpassen** — auf HiveGrid-Permission-Bundles (`email_marketing.write`/`.admin`) umstellen; Test-Pattern für Permission-Denied→404 (DoD §25) nachnutzen |
---
## Vorhandene Daten-Modelle
> Pfad: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`
**Direkt M10-relevant (`email.prisma`):**
- `Campaign` — `email.prisma:72` — `tenantId?`, `emailSenderId`, `name`, `subject`, `htmlBody`, `textBody?`, `status` (default "draft", Freitext-String — nicht das Spec-Enum draft/scheduled/sending/sent/paused/failed/cancelled), `track`, `sentAt?`, Relation `recipients OutboundEmail[]`. **Fehlt:** preheader, template_id, recipient_segment_id, recipient_list_snapshot, scheduled_at, sending_started/finished_at, total_recipients, alle *_count-Aggregate, archived_at, created_by_user_id, Spec-Indizes.
- `OutboundEmail` — `email.prisma:88` — `tenantId?`, `campaignId?`, `contactRowId?` (FK auf `Row`), `email`, `fromSenderId`, `isPreview?`, `error?`, `sentAt?`/`deliveredAt?`/`bouncedAt?`/`spamComplainedAt?`/`unsubscribedAt?`, Relations `opens`/`clicks`. **Fehlt:** recipient_email-Snapshot-Semantik (vorhanden als `email`), recipient_first/last_name-Snapshot, personalization_payload (JSONB), delivery_status-Enum, provider_message_id, bounce_type/bounce_reason_text, tracking_token + unsubscribe_token (unique), Spec-Indizes.
- `OutboundEmailOpen` — `email.prisma:111` — `outboundEmailId`, `firstOpen`, `createdAt`. **Fehlt:** reader_ip (anonymisiert), reader_user_agent, tenantId, `opened_at`-Semantik (= createdAt).
- `OutboundEmailClick` — `email.prisma:119` — `outboundEmailId`, `link`, `createdAt`. **Fehlt:** link_label, reader_ip/user_agent, tenantId.
- `EmailSender` — `email.prisma:58` — `tenantId?`, `provider`, `stream`, `apiKey`, `fromEmail`, `fromName?`, `replyToEmail?`, Relations `campaigns`/`outboundEmails`. **Fehlt:** sending_domain_id (M9-FK), is_default, archived_at, created_at. Hält `apiKey` direkt am Sender (→ DKIM/Domain-Gate fehlt).
**Verwandt, aber paralleles operator-seitiges System (`emailSequences.prisma` / `marketingLeads.prisma`):**
- `EmailSequence`, `EmailSequenceRun`, `EmailSequenceStepDelivery` — `emailSequences.prisma` — Drip-Funnel mit `triggerEvent`, `stepsJson` (linear), Run-State, Step-Delivery mit sentAt/openedAt/clickedAt/bouncedAt/providerMessageId. **Wichtig:** Die öffentlichen Tracking-/Unsubscribe-Routen hängen an DIESEN Modellen, nicht an `OutboundEmail`. Status-Enum kennt `unsubscribed` (terminal).
- `Lead`, `LeadEvent`, `TenantAcquisition`, `MarketingIntegration` — `marketingLeads.prisma` — Marketing-Lead-Funnel (operator-org, nicht tenant-scoped) + Outbound-Integrations-Config. **Themenfremd für M10** (CRM-Lead-Akquise / Drittanbieter-Sync), nicht der Tenant-Newsletter-Versand.
**Inbound-Email (themenfremd, M9):** `Email`, `EmailRead`, `EmailCc`, `EmailAttachment`, `TenantInboundAddress` — `email.prisma:1–56`.
---
## Lücken / komplett neu zu bauen
**Datenmodelle (4 Spec-Modelle existieren NICHT — per Grep verifiziert):**
1. `Unsubscribe` (Spec Block H) — Pro Contact+Tenant dauerhaft, scope-Enum (all_marketing/specific/global), unsubscribed_via, email_address-Snapshot, reason. Heute nur Flag `OutboundEmail.unsubscribedAt`.
2. `EmailSuppressionList` (Spec Block G/H) — Tenant-weite Sperrliste (hard_bounce/complaint/manual/invalid_format), CRM-Lösch-persistent (10.5.5), `(tenant_id, email_address)` unique. **Existiert nicht.**
3. `RecipientSegment` (Spec Block A/D) — JSONB-Filter-Tree (verschachteltes AND/OR), entity_type, is_static_snapshot + static_recipient_ids[], archived_at. **Existiert nicht** (heute nur CRM-Entity-Views als Ad-hoc-Quelle).
4. `EmailTemplate` (Spec Block A/I) — Wiederverwendbare Vorlagen mit subject/preheader-Default, body_html/text, is_template_origin, archived_at. **Existiert nicht** (nur hardcodierte React-Sequenz-Templates).
**Opt-In-Dokumentation (Spec Block H 10.7):** `marketing_opt_in_at/_source/_reference/_text_snapshot` am Contact + Double-Opt-In-Flow (Bestätigungs-Mail + 7-Tage-Token). Heute nur CRM-Boolean `marketingSubscriber`. **Neu.**
**Versand-Engine-Robustheit (Spec Block E/K):**
- Geplanter Versand (`scheduled` + Cron `WHERE status=scheduled AND scheduled_at<=NOW()` jede Minute) — **fehlt**.
- BullMQ-Versand-Worker für Kampagnen mit Batch (1.000) + Retry (3× exp. Backoff) — **fehlt** (heute synchron `mapWithConcurrency(5)`).
- Throttling: 100 Mails/Min/Tenant, 30 Mails/Min/Empfänger-Domain — **fehlt**.
- Daily-Cap pro Plan (Cloud 10K / Cloud+ 50K / Trial 200, via SubscriptionFeature) + Auto-Pause + Resume 00:00 Tenant-Zeit — **fehlt**.
- Frequenz-Cap (max 5 Mails/Empfänger/Woche, tenant-konfigurierbar) + Auto-Exclusion-Reason — **fehlt**.
- Pause/Cancel-Lebenszyklus (paused re-aktivierbar, cancelled final) — **fehlt** (Status ist Freitext-String).
**Anti-Spam (Spec Block K):** Spam-Score-Check 0–10 (Großschrift/Ausrufezeichen/Phrasen/Bild-Text-Verhältnis) mit Block-Option ab >7 — **fehlt komplett**.
**Auto-Exclusion-Engine (Spec Block D):** beim Segment-Auflösen Ausschluss von Unsubscribe/Suppression/ohne-Email/archiviert/ohne-Opt-In + Aufschlüsselung „X aus Y ausgeschlossen (pro Grund)" — **fehlt**.
**Pflicht-Validierungen vor Versand (Spec Block C/L):** Sending-Domain-DKIM-grün-Gate (M9), Unsubscribe-Link-Auto-Injection, Impressum-Adress-Erkennung, Empfänger>0-nach-Exclusion, Daily-Cap-Check, Bestätigungs-Modal mit Pflicht-Check-Anzeige — **fehlt**.
**6-Schritt-Kampagnen-Wizard + Mobile/Desktop-Vorschau + Custom-Field-Token (`{{custom.x}}`)** — Editor existiert nur als einstufiges Formular; Wizard/Vorschau/Custom-Token **neu**.
**Bounce-Klassifikation + Auto-Folgeaktionen (Spec Block G):** Hard/Soft-Klassifikation (5.x.x/4.x.x), Soft-to-Hard nach 3 Versuchen, Hard→Suppression-Add + `Contact.email_invalid_at` + Activity, Complaint→Auto-Unsubscribe — Webhook-Empfang-Pattern existiert, **Domain-Folgeaktionen fehlen**.
**Stats-Vollausbau (Spec Block F):** CTR (Klick/Öffnung), Hard/Soft-Bounce-Raten, Unsubscribe-/Complaint-Raten, Click-Map (URL→Anzahl), Status-Filter, Aktivitäts-Detail pro Empfänger (Opens/Clicks chronologisch) — Summary/Tabelle existieren teilweise, Rest **neu**.
**Trigger-Mail-Action `send-marketing-email` (Spec Block J, M17):** Mini-Kampagne (1 Empfänger, sofort) aus Automation-Engine + Template/Sender/Empfänger-Resolution + Auto-Exclusion + System-Actor — **neu** (Sequence-Engine ist Vorbild).
**Querschnitt-Wiring (HiveGrid-DoD):** Activity-Stream-Typen (`marketing_email_sent/opened/clicked/bounced/unsubscribed/complained` via `logActivity`), Aggregat „Marketing-Engagement" am Contact, `notify()`-Integration, View-Model-Layer (`packages/view-models`), `ui-hivegrid`/Subframe-Adapter-Re-Layering, `sidebar.config.ts`-Eintrag (Gruppe „Kommunikation"), HiveGrid-Permissions (`email_marketing.*`), Search-Index — **alles neu zu verdrahten** (bestehender Code folgt ToolCTRL-, nicht HiveGrid-Layer-Konvention).
**EU-SMTP-Provider (LP-13):** MailerSend ist kein EU-Anbieter → Scaleway-TEM-/Brevo-EU-/Mailjet-EU-Adapter über das vorhandene `MailProvider`-Interface **neu implementieren** (offener Spec-Punkt).
**M9-Sending-Domain-Verknüpfung:** `EmailSender.sending_domain_id` FK auf `TenantSendingDomain` + DKIM-Status-Anzeige + Sender-Auto-Deaktivierung bei Domain-Widerruf — **fehlt** (M9 existiert noch nicht).
---
## Empfohlenes Vorgehen
**Phase 0 — Re-Layering-Entscheidung + Schema-Erweiterung (Fundament):**
1. Bestehende `email.prisma`-Modelle in eine HiveGrid-Migration übernehmen und **härten**: `Campaign.status`→Spec-Enum, `tenantId` NOT-NULL/RLS, Spec-Felder (preheader, scheduled_at, *_count, recipient_list_snapshot, archived_at, created_by_user_id, tracking_token/unsubscribe_token unique) + Indizes ergänzen. Forward-Only-Migration mit Inverse-SQL (DoD §28).
2. **Vier fehlende Modelle neu anlegen:** `Unsubscribe`, `EmailSuppressionList`, `RecipientSegment`, `EmailTemplate` (Spec Block A). Opt-In-Felder am Contact ergänzen.
3. Provider-Schicht: `MailProvider`-Interface aus `packages/mail` 1:1 übernehmen, EU-SMTP-Adapter (LP-13) als neuen Adapter daneben (Scaleway TEM evaluieren — offener Spec-Punkt vor Bau klären).
**Phase 1 — M100 Editor (höchster 1:1-Reuse):**
4. `EmailMarketingService` + `campaigns.db.server` + `EmailSenderForm`/Sender-Routes + i18n + Feature-Flag **als Vorlage** in HiveGrid-Layer (`app/domain` + `packages/view-models` + `ui-hivegrid`/Subframe-Adapter) re-layern. Permissions `email_marketing.*` + Sidebar-Eintrag „Kommunikation" verdrahten.
5. `replaceVariables` übernehmen, Token auf `{{first_name}}` + `{{custom.x}}` angleichen; `EmailTemplate`-CRUD + SHK-Branchen-Templates (aus `email-templates`-Render-Pipeline) neu.
6. 6-Schritt-Wizard + Mobile/Desktop-Vorschau + Test-Mail (vorhandenes `sendCampaignTest` als Basis) + Spam-Score-Check neu.
**Phase 2 — M101 Segmente:**
7. `RecipientSegment` mit JSONB-Filter-Tree neu bauen; `EntityViewsApi`/`CrmService` als CRM-Auflösungs-Brücke nachnutzen; Static/Dynamic + Auto-Exclusion-Engine + 50-Sample-Vorschau + Aufschlüsselung neu.
**Phase 3 — M102 Versand-Engine (Architektur-Kern):**
8. `QueuedMailProvider` + `email-sequences`-Engine-Pattern (injizierbarer Store/Queue) als Vorbild für einen **BullMQ-Kampagnen-Versand-Worker** mit Batch/Retry/Throttle (M007-Idempotenz). Cron für geplanten Versand. Daily-Cap (SubscriptionFeature) + Frequenz-Cap + Pause/Cancel-Lebenszyklus + Pflicht-Footer-Auto-Injection (`Footer.tsx`-Basis) + Pflicht-Validierungen + DKIM-Gate (M9) neu.
**Phase 4 — M104 Unsubscribe + Bounce (starke Vorlagen):**
9. Token-Mechanik (`unsubscribe-token.ts`) + Pixel-/Click-Routen + `unsubscribe.$token.tsx` + `mailersend-signature.ts` + `provider-webhook-route.ts` **als Vorlagen** auf `OutboundEmail`/`Unsubscribe`/`EmailSuppressionList` umverdrahten. Bounce-Klassifikation + Suppression-Auto-Add + Complaint→Auto-Unsubscribe + Activity-Wiring + Grund/Feedback-Formular neu.
**Phase 5 — M103 Reporting (+ A/B Phase 2):**
10. `getSummary`/`OutboundEmailsTable`/`EmailMarketingSummaryRoute` ausbauen: CTR, Bounce/Unsub/Complaint-Raten, Click-Map, Pro-Empfänger-Aktivitäts-Detail, Status-Filter. A/B-Tests sind Phase 2 (Spec 10.3/10.11.1).
**Querschnitt (durchgängig):** Activity-Stream (`logActivity` + Marketing-Engagement-Aggregat am Contact), `notify()`, Audit (auto M001), Klartext-Catalog (M002), View-Model-Unit-Tests + Smoke-Tests + Hot-Swap-Drill + Visual-Regression (DoD D).
**Trigger-Mails (Spec J):** koordiniert mit M17 — `send-marketing-email`-Action auf Mini-Kampagnen-Pfad (1 Empfänger, sofort) aufsetzen; Sequence-Engine als Architektur-Vorbild.
@@ -0,0 +1,110 @@
# Boilerplate-Abgleich: M12 — Telefonie (AirCall + HalloPetra)
| Feld | Wert |
|---|---|
| **Modul-ID** | M12 |
| **Name** | Telefonie (AirCall + HalloPetra) |
| **Milestones** | M105 (HalloPetra-Adapter), M106 (AirCall-Adapter), M107 (Anruf-Eingang + Auto-Match), M108 (Anruf-Ausgang / Click-to-Call), M109 (Voicemail + Notizen + Automation-Trigger) |
| **Block** | Block 5 — Kommunikation (Pflichtenheft Modul 12, [N16, 09.05.2026]) |
| **Sidebar-Gruppe** | KOMMUNIKATION → Telefonie (INTEGRATION-CONTRACTS §1) |
| **Reuse-Level** | **medium** |
> **Verifikations-Hinweis:** Alle Befunde wurden per Grep/Read direkt in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` geprüft, nicht nur aus der Inventur übernommen. Das Kern-Ergebnis: **Es gibt KEINE Telefonie-, Call-, Phone-, VoIP-, AirCall- oder HalloPetra-Artefakte** in der Boilerplate (weder Prisma-Modell, noch Service, noch Route, noch UI). Die gesamte Telefonie-Domäne ist neu zu bauen. Was die Boilerplate liefert, sind **starke Querschnitts-Fundamente und ein direkt passendes Adapter-Registry-Pattern** (`marketing-outbound`), das als Vorlage für den `TelephonyProviderInterface` dient.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `packages/marketing-outbound/src/types.ts` (`MarketingOutboundAdapter`, `parseConfig`/`send`, `AdapterContext`, `AdapterResult`, `MarketingAdapterConfigError`) + `packages/marketing-outbound/src/index.ts` (`adapterRegistry`, `resolveAdapter(type)`, `ADAPTER_TYPES`) | Adapter-Interface + Registry + Resolver — strukturell exakt das, was der Spec-Block H `TelephonyProviderInterface` (connect/disconnect/listProviderUsers/triggerOutboundCall/subscribeToWebhooks/verifyWebhookSignature/parseWebhookEvent/getRecordingUrl) braucht | **als-vorlage** (Form 1:1 übernehmbar, AirCall-/HalloPetra-spezifische Methoden/Configs ergänzen) |
| `packages/foundation/src/adapters.ts` (`defineAdapter()`, `getAdapter()`, `AdapterStatus`) | Globales Adapter-Register-Primitiv (von AGENTS.md M008-M010 als Apps-Engine-Seam referenziert); `AdapterStatus` = `not_configured/configured/healthy/degraded/unavailable` deckt `connection_status` + Health-Check ab | **1:1** (Status-Enum auf Telephony-Connection mappen) |
| `apps/web/app/utils/api/.server/CryptoApi.ts` (`encrypt`/`decrypt`, AES-256-GCM, versioniert, `CRYPTO_SECRET`) | Verschlüsselung der OAuth-Tokens + Webhook-Secret (`oauth_access_token_encrypted`, `oauth_refresh_token_encrypted`, `webhook_secret_encrypted`) | **1:1** |
| `packages/api-client-ts/src/webhooks.ts` (`verifyWebhookSignature`, `signWebhookPayload`, HMAC-SHA256 über `${timestamp}.${payload}`, 5-Min-Replay-Fenster, `timingSafeEqual`) | Webhook-Signatur-Verifikation für eingehende AirCall/HalloPetra-Webhooks (Spec Block D, `signature_valid`) | **anpassen** (AirCall nutzt eigenes Signatur-Schema/Header — Logik als Vorlage, Provider-Format einsetzen) |
| `apps/web/app/routes/oauth/github/start.server.ts` (`createGitHubOAuthPkceChallenge`, state/verifier/PKCE) + `apps/web/app/routes/oauth/github/callback.tsx` (state-Validierung, code→token-Exchange, Session-Roundtrip) | OAuth-Authorization-Code-Flow-Template für AirCall-Connect (Spec Block B, Schritt 1) | **als-vorlage** (GitHub-spezifisch; AirCall-OAuth-Endpunkte/Scopes `public_api`, Token-Storage encrypted ersetzen) |
| `apps/worker/src/jobs/push-notification.ts` (provider-pluggable FCM/APNs/WebPush-Fan-out, `revokedAt`-Invalidierung) + `prisma/schema/notifications.prisma` (`DeviceToken`, `NotificationDelivery`, `UserNotificationPreference`) + `packages/foundation/src/notifications.ts` (`NotificationInput`-Typen) | Push-Benachrichtigung bei eingehendem Anruf (`call.ringing_on_agent`, Spec Block D + 12.5.7) + verpasster-Anruf-Notification — **kein Direkt-Push, sondern über M011-Pipeline** | **1:1** (Notify-Aufruf gemäß INTEGRATION-CONTRACTS §7; Telephony liefert nur `notify({...})`) |
| `apps/worker/src/jobs/workflow-trigger.ts` + `workflow-trigger-store.ts` + `workflow-trigger-native-executor.ts` (`WorkflowTriggerJobData`, `findLiveEventWorkflows`, Outbox-Queue `outbox.workflow`, Filter/Condition-Auswertung) + `prisma/schema/workflows.prisma` (`Workflow`, `WorkflowBlock`, `WorkflowBlockCondition`) | Automation-Engine-Trigger-Auslösung für `call.received/answered/completed/missed` (Spec Block F) — M12 publiziert nur Outbox-Events, der Trigger-Apparat existiert | **1:1** (Trigger-Event-Typen + Payload aus M12 in bestehende Workflow-Trigger-Pipeline einspeisen) |
| `packages/db/src/outbox.ts` (`publishOutboxEvent(tx, args)`, `OUTBOX_EVENT_TYPE_PATTERN` `<domain>.<entity>.<verb>`) + `prisma/schema/outbox.prisma` (`OutboxEvent`, `dispatchKey @unique`) | Transaktionale Event-Auslieferung für Webhook-Verarbeitung → Activity / Notification / Automation-Trigger (atomarer Side-Effect) | **1:1** |
| `packages/queue/*` (`queueNames`, `enqueueJob`, `buildIdempotentJobId`, `createWorker`, Prioritäten) | Async-Verarbeitung: Webhook-Event-Processing, Token-Refresh-Worker (24h-Cron, Spec Block B Reconnect), Health-Check | **1:1** (neue Queue-Namen + Job-Payloads ergänzen) |
| `apps/web/app/utils/leads/marketingIntegrations.db.server.ts` + `apps/web/app/routes/admin/marketing-integrations.tsx` (verschlüsselte `configJson`-Integration + Setup-/Verbindungs-UI) | Vorlage für Integration-Setup-Route `/settings/integrations/telephony/` (Connect, Test, Disconnect, encrypted Config) | **als-vorlage** |
| `prisma/schema/appsEngine.prisma` (`App` mit `@@unique([tenantId, type])`, `DataConnection` mit encrypted `config`, `AppSyncRun`/`AppSyncRunLog`/`AppSyncItem`) | Datenmodell-Muster für „1 Connection pro Tenant" + verschlüsselte Credentials + Sync-Lauf-Log. **Achtung:** nur Schema, KEIN Service/Worker — siehe Lücken | **als-vorlage** (Muster für `TelephonyConnection` `@@unique([tenant_id, provider])`; nicht direkt verwendbar) |
| `apps/web/app/application/sidebar/AppSidebar.tsx` + `SidebarGroupDto.ts` + `SidebarItem.ts` + `packages/ui/src/navigation.ts` (`AppSidebar`-Adapter, shadcn/radix `SidebarPrimitives`) | Sidebar-Wiring (KOMMUNIKATION → Telefonie) mit Permission-Gate (DoD §B-6/7) | **anpassen** (HiveGrid nutzt eigene `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` gemäß AGENTS.md — Boilerplate-Sidebar ist Referenz, nicht Ziel-Ort) |
| `prisma/schema/accounts.prisma` (`TenantUser`, `User`, `Tenant`) | FK-Anker für `TelephonyUserBinding.tenant_user_id`, `TelephonyCallSession.tenant_user_id`, `connected_by_user_id` | **1:1** (existierende Identity-Modelle referenzieren) |
| `prisma/schema/core.prisma` (`AuditEvent` Hash-Kette) + `packages/db/src/audit-hash.ts` + `packages/foundation/src/audit.ts` | Audit-Trail für Connection-Setup, User-Bindings, Notiz-Edits (Spec AV #6, DoD §C-13) — automatisch via M001-Prisma-Middleware | **1:1** |
| `packages/db/src/dsgvo/user-fk-map.ts` | Pflicht-Eintrag für jeden neuen User-FK der Telephony-Modelle (`tenant_user_id`, `manual_override_user_id`, `note_updated_by_user_id`, `connected_by_user_id`) — CI bricht sonst | **1:1** (Wartung beim Modellbau) |
| `packages/foundation/src/idempotency.ts` + `apps/worker/src/jobs/legacy-event-receiver.ts` (`withOutboxIdempotency`) | Idempotenz für Webhook-Events (`TelephonyWebhookEvent.provider_event_id`, Spec Block A) | **1:1** |
| `apps/web/app/routes/api.embed.forms.$formKey.submit.tsx` (public inbound-POST-Endpoint mit Origin/Anti-Spam-Verarbeitung) | Strukturvorlage für Webhook-Endpoint `/api/v1/webhooks/telephony/aircall/{tenant_slug}` (Spec Block D) | **als-vorlage** |
---
## Vorhandene Daten-Modelle (konkret)
**Direkt referenzierbar (existieren):**
- `prisma/schema/accounts.prisma` — `Tenant`, `TenantUser`, `User` → FK-Ziele für alle Telephony-Modelle. (Hinweis: `Tenant.country` existiert **nicht** — Default-Country für E.164-Normalisierung muss neu modelliert/aus Tenant-Setting kommen.)
- `prisma/schema/notifications.prisma` — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` (APNs/FCM/WebPush) → Push bei Inbound/Missed.
- `prisma/schema/workflows.prisma` — `Workflow`, `WorkflowBlock`, `WorkflowBlockCondition*` → Automation-Trigger-Konsum.
- `prisma/schema/outbox.prisma` — `OutboxEvent` → transaktionale Event-Auslieferung.
- `prisma/schema/core.prisma` — `AuditEvent`, `IdempotencyKey`, `Credential` (globaler Secret-Store) → Audit + Idempotenz.
- `prisma/schema/appsEngine.prisma` — `App`/`DataConnection`/`AppSyncRun*` → **nur als Schema-Muster** (kein Service-/Worker-Layer dahinter).
**Telephony-spezifische Modelle — KOMPLETT NEU (existieren nicht in der Boilerplate):**
- `TelephonyConnection` — neu (Spec Block A). Muster aus `App`/`DataConnection` übernehmbar (`@@unique([tenant_id, provider])`, encrypted config).
- `TelephonyUserBinding` — neu (AirCall/HalloPetra-User ↔ TenantUser).
- `TelephonyCallSession` — neu (zentrales Anruf-Modell, inkl. `matched_contact_id/lead_id/deal_id/project_id`).
- `TelephonyWebhookEvent` — neu (append-only Webhook-Roh-Log, Retention 30/90 Tage).
- Enums (`provider`, `direction`, `call status`, `match_confidence`, `event_type`, `processing_status`) — neu.
- Alle neuen Telephony-Modelle gehören in `prisma/schema/app.prisma` (HiveGrid-Platzhalter) oder ein neues `prisma/schema/telephony.prisma`.
---
## Lücken / komplett neu zu bauen
1. **Gesamte Telefonie-Domäne** — Verifiziert: 0 Treffer für `telephon|aircall|hallopetra|sipgate|voicemail|click-to-call|call-session` in `prisma/schema/`, `apps/web/app`, `packages/ui*`, `packages/view-models`. Datenmodelle, Domain-Logik, Routes, View-Models, UI: alles neu.
2. **AirCall-Adapter** (M106) — AirCall-OAuth (`public_api`-Scope), `POST /users/{id}/calls`, `GET /users`, Webhook-Subscription-Anlage, Recording-URL-Abruf, AirCall-Signatur-Verifikation. Kein AirCall-SDK/Code vorhanden.
3. **HalloPetra-Adapter** (M105) — kein Code, keine Referenz. Eigene Implementierung des `TelephonyProviderInterface`; Click-to-Call-Detection mit `tel:`-Fallback; Vorqualifikations-Tag → Lead/Activity.
4. **Telefonnummer-Normalisierung (E.164)** — `libphonenumber`/`awesome-phonenumber` ist **keine** Dependency (verifiziert: leer in allen package.json). Library + Normalisierungs-Helfer komplett neu; Default-Country-Quelle ebenfalls neu (kein `Tenant.country`).
5. **Activity-Stream** — Kein `Activity`-Modell, kein `logActivity`-Service in der Boilerplate (M045 ist HiveGrid-eigener Querschnitt, noch nicht gebaut). Anruf-Activities (`call_inbound/outbound/missed/note_added/note_edited`) hängen an M045. **Vorbedingung, nicht aus BP übernehmbar.**
6. **CRM-Entitäten zum Matchen fehlen** — `Contact`, `ContactPhone`, `Deal`, `Project` existieren **nicht** in der Boilerplate (nur operator-scoped `Lead` aus `marketingLeads.prisma`, ohne `phone`-Feld). Auto-Match (Spec Block D) hängt vollständig an HiveGrid-CRM (M042-M046 Kontakte, M059-M064 Sales, M065-M070 Aufträge, Lead-Inbox M047-M051). **Harte Vorbedingung.**
7. **appsEngine ist Schema-only** — Verifiziert: kein Worker-Job/Service konsumiert `AppSyncRun`/`DataConnection`. Die „Apps-Engine" mit Code ist das `marketing-outbound`-Pattern + WASM-`plugin-runtime` (in Prod nur `log`/`audit`-Capabilities aktiv, `http.outbound` ist `productionAvailable: false`). → Provider-Adapter müssen als regulärer Server-/Worker-Code laufen (Pattern: `marketing-outbound`), **nicht** im WASM-Sandbox.
8. **Outbound HTTP zu Provider-APIs** — `adapterFetch()` (SSRF-Guard, Timeout) existiert in `marketing-outbound`, ist aber auf das interne Adapter-Set gemünzt. AirCall/HalloPetra-API-Clients (Auth-Header, Rate-Limit-/Quota-Handling, Klartext-Diagnose pro HTTP-Code laut Spec Block H) neu.
9. **Token-Refresh-Worker** (24h-Cron, <72h-Restlaufzeit → erneuern; Refresh-Fehler → `revoked` + Notify) — Cron-Worker-Muster vorhanden (`*-cron.ts`), Logik neu.
10. **Notiz-Editor + Markdown** (M109, Spec Block E) — UI + `note_text`-Persistenz + Audit-on-Edit; kein vorgefertigter Anruf-Notiz-Baustein.
11. **Permissions** — `telephony.*`-Keys (`click_to_call`, `read_own/all`, `write_notes_own/all`, `admin`) + Bundle-Mapping neu in `packages/entitlements/src/permissions.ts`; RBAC-Fundament (`permissions.prisma`, `withTenantScope`/`withPermission`) existiert.
12. **i18n-Keys** — Keine `telephony`-Locale-Datei; i18n-Runtime (`packages/i18n`) vorhanden, aber `packages/i18n/src/locales/de/telephony.json` neu (DoD §B-10).
13. **View-Models** — `packages/view-models/src/` ist Skelett (nur `index.ts`). Alle Telephony-VMs (Connection-Status, Call-Liste, Call-Detail, User-Binding-Liste) neu.
14. **Subframe-UI** — Spec nennt Designs explizit als offen; UI komplett zu entwerfen + via Adapter integrieren (DoD §A-4, Subframe-Pflicht laut User-Memory).
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Vorbedingungen prüfen (nicht aus BP, hängt an anderen HiveGrid-Modulen):**
- CRM-Kontakt/`ContactPhone`/Lead/Deal/Project (M042-M070) müssen existieren, bevor Auto-Match (M107) sinnvoll ist.
- Activity-Stream-Querschnitt M045 (`logActivity`) muss stehen (M107/M109 schreiben darauf).
- Notification-Service M011 (`notify`) + Permission-Querschnitt M004 + i18n M003 sind harte Querschnitt-Voraussetzungen (laut AGENTS.md vorhanden bzw. zu bauen).
**Phase 1 — Fundament aus BP übernehmen (zuerst):**
1. `TelephonyProviderInterface` definieren — Form aus `packages/marketing-outbound/src/types.ts` + `foundation/adapters.ts` (`defineAdapter`) übernehmen, Telephony-Methoden ergänzen (Spec Block H).
2. Datenmodelle (`TelephonyConnection/UserBinding/CallSession/WebhookEvent` + Enums) in `prisma/schema/` anlegen, Muster `@@unique([tenant_id, provider])`/encrypted-config aus `appsEngine.prisma`; FK auf `TenantUser`; `user-fk-map.ts` ergänzen; Forward-Only-Migration mit Inverse-SQL (DoD §F-28).
3. Token-Verschlüsselung 1:1 aus `CryptoApi.ts`; Webhook-HMAC-Verify-Logik aus `api-client-ts/src/webhooks.ts` als Vorlage.
4. Permissions (`telephony.*`) + Bundles in `packages/entitlements`; i18n-Keys; Sidebar-Eintrag (KOMMUNIKATION → Telefonie) mit Gate.
**Phase 2 — Adapter + Connect-Flow (M106 AirCall, dann M105 HalloPetra):**
5. AirCall-Adapter implementieren; OAuth-Flow nach Vorlage `oauth/github/start.server.ts`/`callback.tsx` (PKCE/state/Session); Setup-Route nach Vorlage `routes/admin/marketing-integrations.tsx`; Token-Refresh-Cron nach `*-cron.ts`-Muster.
6. HalloPetra-Adapter (gleiches Interface), Click-to-Call-Detection + `tel:`-Fallback.
**Phase 3 — Anruf-Verarbeitung:**
7. Webhook-Endpoint (Vorlage `api.embed.forms.$formKey.submit.tsx`) → `TelephonyWebhookEvent` (idempotent via `withOutboxIdempotency`) → `publishOutboxEvent` → Worker (Queue-Pattern).
8. E.164-Normalisierung (neue `libphonenumber`-Dependency) + Auto-Match (M107) gegen CRM; Push via `notify()` (M011); verpasste Anrufe + Rückruf-Aufgabe.
9. Click-to-Call (M108) aus Kontakt/Deal/Lead über Adapter `triggerOutboundCall`; ausgehender Anruf auto-protokolliert.
**Phase 4 — Notizen, Voicemail, Automation (M109):**
10. Notiz-Editor + Audit-on-Edit; Recording-Link (kein Re-Hosting); Automation-Trigger als Outbox-Events in die bestehende `workflow-trigger`-Pipeline einspeisen.
**Querschnitt durchgehend:** View-Models (M013), Klartext-Fehler (M002), Empty/Loading-States, Smoke- + Hot-Swap-Tests, Visual-Regression, Feature-Flag (M006) — alle gemäß DoD.
---
## Reuse-Level-Begründung: medium
Die **Telefonie-Domäne selbst existiert zu 0%** (kein Modell, kein Service, kein UI). Aber die Boilerplate liefert **mehr als nur Fundament**: ein strukturell direkt passendes Adapter-Registry-Pattern (`marketing-outbound`), einen verwendbaren OAuth-Flow, fertige Verschlüsselung, HMAC-Webhook-Verify, eine komplette Push-/Notification-Pipeline, die Automation-Trigger-Pipeline und das Outbox/Queue/Audit/Idempotenz-Querschnitt-Set. Das hebt M12 über „low" (nur Querschnitt) — die nennenswerten Lücken (Provider-Adapter, CRM-Match-Abhängigkeit, E.164-Normalisierung, Activity-Stream-Abhängigkeit, gesamtes UI) verhindern „high". → **medium**.
@@ -0,0 +1,129 @@
# Boilerplate-Abgleich — M13 Team-Chat (intern)
- **Modul-ID:** M13 (Modul 13)
- **Name:** Team-Chat (intern) — Quiply-Ablösung, drei Ebenen (Projekt-Channel / Gruppen-Channel / DM)
- **Milestones:** M110 (Channel-Modell + Permissions), M111 (Nachrichten + Threads + Pinned + Reactions), M112 (Datei/Foto-Anhänge), M113 (Modul-Verknüpfungen / Auto-Lifecycle / Mark-as-Task), M114 (Mentions + Push + Lese-Bestätigungen)
- **Block:** Block 5 (`_bmad-output/pflichtenheft/blocks/block5.md`), Abschnitte 13.1–13.3
- **Reuse-Level:** **low** — kein einziges Chat-Datenmodell in der Boilerplate; das Modul ist im Datenkern komplett neu zu bauen. Wiederverwendbar sind ausschließlich **Querschnitts-Bausteine** (Notifications, Push/DeviceToken, Storage+AV, Audit, Permissions, i18n, Feature-Flags, Search, View-Model-Konvention, App-Shell) und **konzeptionelle Vorlagen** (`RowComment`/`RowCommentReaction` als Message/Reaction-Muster, `realtime`-SSE-Paket als Streaming-Vorlage, `apps/hocuspocus` als Standalone-Realtime-Service-Muster).
> **Wichtigster Befund:** Die im Auftrag erwähnten „packages/realtime + apps/hocuspocus + collabDocs" lösen **nicht** die Chat-Echtzeit-Anforderung aus Block H. `@toolctrl/realtime` ist ein **SSE-only Notification-Stream** (4 Event-Namen, alle notification-bezogen), kein generischer WebSocket-Room-/Pub-Sub-Layer mit `message.new`/`typing.*`/`presence.*`/`reaction.*` (Block H.2). `apps/hocuspocus` ist ein **Y.js/CRDT-Collab-Doc-Server** (für Live-Editing geteilter Dokumente), kein Chat-Channel-Broadcast. `CollabDoc` (collabDocs.prisma) speichert CRDT-Binärzustand pro Resource, **kein** Message-/Thread-/Reaction-Modell. Beide sind als *Architektur-Vorlage und Infrastruktur-Bauteil* nützlich, decken die Chat-Domäne fachlich aber nicht ab.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/notifications.prisma` (`NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` + Enums `NotificationDeliveryStatus`, `NotificationPreferenceChannel`) | In-App- + E-Mail-Notification-Delivery, per-Channel/Category-Preference, Push-Device-Token (APNs/FCM/WebPush, `revokedAt`) | **1:1** — deckt Block I.2 (Notification-Trigger/Status), Block J.2 (Push-Token-Registry) und Quiet-Hours-Speicherort-Vorbild ab. `category`/`messageKey`/`sourceKey` direkt für Chat-Notification-Bündelung nutzbar |
| `packages/foundation/src/notifications.ts` (`notify`, `notifyMany`, `bundleNotifications`, `isNotificationEnabled`, `assertI18nKey`) | Tenant-pflichtige Notifications mit Preference-Check, Upsert per `sourceKey`, Metadata-Redaction, **Bündelung pro Tenant/User/Channel/Category** | **1:1** — entspricht DoD-Pflicht „Notifications via `notify()` (M011), nicht direkt"; `bundleNotifications` deckt Block I.2 Anti-Spam-Bündelung (>5 Msg/Min) direkt ab |
| `apps/worker/src/jobs/push-notification.ts` | Worker-Job für Push-Versand (DeviceToken-basiert) | **1:1 / anpassen** — Push-Pipeline für Block J.2 wiederverwenden; Chat-Payload-Datenschutz (nur Channel-Name + Sender-Vorname + Snippet 100 Zeichen, Block J.2) als Payload-Builder ergänzen |
| `apps/mobile/src/pushRegistration.ts` + `apps/mobile/capacitor.config.ts` (Plugin `push-notifications`, `local-notifications`) | Capacitor-Push-Registration gegen Backend + native Shell (WebView um Web-Build) | **als-vorlage** — PWA-Web-Push (Phase 1) + späteres Native (Phase 2). Block J Mobile-First-Hülle |
| `packages/storage/src/scan/*` (`createMagicBytesScanAdapter`, `clamav-scanner`, `DEFAULT_ALLOW_LIST`/`resolveAllowList`, `s3-quarantine`, `ScanVerdict`) + `apps/worker/src/scanService.ts` | Pre-Upload Magic-Bytes-Check, ClamAV-Scan, S3-Quarantäne, Datei-Typ-Allowlist | **1:1** — Block G.1 Anti-Virus-Scan + Datei-Typ-Whitelist (überlappt mit M23) |
| `packages/storage/src/index.ts` + `./signed` + `./access` | S3-Adapter, Signed-Upload/Download-URLs, Access-Helper | **1:1** — Block G.1 Chat-File-Upload-Pipeline (`tenants/{tenantId}/chat/{chatId}/...`) |
| `prisma/schema/core.prisma` `FileObject` (+ `FileUploadProgress`, `FileChunk`) | Storage-Metadaten-Modell (provider/bucket/key/contentType/byteSize/checksum) | **anpassen** — Datei-Records für Chat-Attachments. **Caveat:** `FileObject` ist **nicht** tenant-scoped (kein `tenantId`/`userId`-Feld) — für Chat-Attachment-Backlinks (`TeamChatMessage.attachments[]` → File-Record mit Backlink auf Source-Message, Block A/G) braucht es ein tenant-scoped Join-/Attachment-Modell (M23-Abhängigkeit) |
| `prisma/schema/entityBuilder.prisma` `RowComment` + `RowCommentReaction` (+ `RowTag`/`EntityTag`, `RowTask`) | Comment-mit-Reactions-Muster: `value`, `createdByUserId`, `isDeleted`, `reactions[]` (emoji als `reaction String`); `RowTask` als „Aufgabe aus Eintrag"-Muster | **als-vorlage** — direktes konzeptionelles Vorbild für `TeamChatMessage` + `TeamChatReaction` (Soft-Delete-Flag, Reaction als String, Author-FK). NICHT 1:1 übernehmbar: es fehlen Thread/`parent_message_id`, `mentions[]`, `attachments[]`, `link_previews[]`, System-Events, Read-Receipts, Channel-Membership |
| `packages/realtime/src/{events,server,client}.ts` (`REALTIME_EVENT_NAMES`, `validateRealtimeEvent`, `serializeRealtimeEvent`, `subscribeToRealtime` mit Reconnect-Backoff + Diagnostics) | SSE-Event-Contract + deterministische Frame-Serialisierung + Browser-Subscriber **mit Exponential-Backoff-Reconnect, Cursor-Resume, Status-Transitions, Redaction** | **als-vorlage** — das **Reconnect-/Cursor-/Diagnostics-Muster** (`client.ts`) ist direkte Vorlage für Block H.3 (Reconnect-Strategie, Cursor-Resume) und Block M (Verbindungs-Banner). Die Event-Union ist chat-fremd und muss um `message.*`/`typing.*`/`presence.*`/`reaction.*`/`thread.reply`/`read.receipt`/`link_preview.ready` (Block H.2) erweitert oder ersetzt werden. Für viele Channels + bidirektionales Typing/Presence ist SSE allein unzureichend → echter WebSocket-Layer nötig |
| `apps/hocuspocus/` (`Server`-Bootstrap, `createAuthExtension` mit JWT HS256 + Tenant-Parity-Check, eigenes `Dockerfile`, Standalone-Container-Pattern) | Standalone-Node-Realtime-Service: JWT-Handshake-Auth, Tenant-Isolation pro Connection, eigener Container | **als-vorlage** — Architektur-Blueprint für den **`/ws/chat`-WebSocket-Server** (Block H.1): separater EU-gehosteter Container (LP-13), Connection-Auth bei Handshake, Tenant-Scope. JWT-Auth-Extension + Tenant-Parity-Logik wiederverwendbar. Yjs/CRDT-Teil ist NICHT relevant |
| `packages/shared-store/src` (`createSharedStore`, `RedisAdapter`, Pub/Sub-Channel, `createSlidingWindowRateLimiter`, `createFixedWindowRateLimiter`, `createIdempotencyStore`) | Redis-KV mit Pub/Sub-Channel + Rate-Limiter + Idempotenz; DB-Index-Allokation (2 = Pub/Sub) | **1:1 / anpassen** — Block H.1 Redis-Pub/Sub als Message-Broker zwischen WS-Server-Instanzen (Multi-Pod); Rate-Limiter für Anti-Spam (Reactions/Messages); Presence-State (`online/away/offline`, Block H.5) und Typing-Throttle (Block H.4) als KV mit TTL |
| `packages/foundation/src/permissions.ts` (`requirePermission`, `withTenantScope`, `withPermission`, `withOwnerCheck`) | Tenant-Scoping + Permission-/Owner-Gating, Fail = `CatalogError(notFound)` (404 statt 403) | **1:1** — Block L (alle Chat-Permissions), DoD „Permission-Filter via `withTenantScope()` + `withPermission()`"; `withOwnerCheck` für Membership-/Author-Checks (Block L.6); 404-statt-403 deckt Block M („Du bist kein Mitglied dieses Channels") |
| `packages/foundation/src/audit.ts` (`auditEvent`, `withAuditMiddleware`) + `prisma/schema/core.prisma` `AuditEvent` (Hash-Chain `previousHash`/`eventHash`, `dataSensitivity`, `regulatoryScope[]`) | Audit-Middleware für mutierende Aktionen, manipulationssichere Event-Kette | **1:1** — Block L.7 (Tenant-Admin-DM-Audit mit Begründungs-Pflicht), Block H.6 (audit-relevante Events: member_added, channel_archived), AV #6 (Audit-Default für schreibende Aktionen) |
| `packages/foundation/src/errors.ts` (`CatalogError`, `catalogRegistry`, `foundationErrors`) | Klartext-Fehler mit `code`/`status`/`i18nKey`/`details` | **1:1** — Block M (alle Klartext-Hinweise/-Fehler), DoD „Fehler-Texte aus M002-Catalog" |
| `packages/foundation/src/flags.ts` + `packages/feature-flags/src` (`evaluateFlag`, `FeatureFlagProvider`, `useFeatureFlagEnabled`) + `prisma/schema/featureFlags.prisma` | Feature-Flag-Engine (Targeting, Cache, React-Hooks, Audit-Trail) | **1:1** — DoD „Feature-Flag-fähig (M006) — Modul ohne Deploy abschaltbar"; Chat-Modul als gegateter Block |
| `packages/i18n/src` (`useTranslate`, Namespaces, `defaultLocale="de"`) + `assertI18nKey`/`assertI18nLabel` | Locale-Config, ICU-MessageFormat, i18n-Key-Disziplin (verify:i18n-Gate) | **1:1** — DoD „Alle UI-Texte als i18n-Keys"; neuer Namespace `chat` analog zu `crm`/`billing` |
| `packages/view-models/src/index.ts` (`VMState`/`VMStatus`, `SidebarRegistryItem`, `MobileRegistryItem`, `RegistryGate`, `assertI18nLabel`) | VM-State-Maschine (idle/loading/ready/empty/error mit i18n-Key) + Shell-Navigations-Registry-Typen (permission+flag-gegated) | **1:1** — DoD „Loader baut View-Model; UI-Component empfängt nur VM"; Sidebar-/Mobile-Tab-Eintrag „Chat" mit Unread-Badge (Block B) via `SidebarRegistryItem` + `RegistryGate` (Permission `chat.read_own_channels`) |
| `packages/ui-app/src/index.ts` (`AppShell`, `createSidebarRegistry`, `createMobileRegistry`, `createShellRegistries`, `EmptyPage`) | App-Shell + Sidebar-/Mobile-Registry-Factories + Empty-Page-Pattern | **1:1** — Erreichbarkeits-DoD (Sidebar §1, Mobile-Tab-Bar §13); Empty-State-Pattern für Block M („Du bist noch in keinem Channel") |
| `packages/search/src` (`createSearchClient`, `createSearchIndex`, Tenant-Filter-Zwang, Meilisearch-Wrapper) + Worker `search-indexer*` + Outbox-Prefix `search.index.` | Tenant-scoped Volltext-Suche (Meilisearch), Index-Registrierung via Outbox | **1:1 / anpassen** — Block B/D Cross-Channel-Suche (`/{tenant}/chat/search`), DoD „Search-Index registriert in `indexed-entities.ts`". Trigram-In-Channel-Suche (Block A Indizes) ist DB-seitig (Postgres) separat |
| `apps/worker/src/outbox/{dispatcher,event-router}.ts` (`resolveOutboxQueueName`, Prefixe `notification.`/`audit.`/`search.index.`/`workflow.`) + `prisma/schema/outbox.prisma` | Transactional-Outbox (FOR UPDATE SKIP LOCKED) + Event-Routing nach Prefix | **1:1 / anpassen** — zuverlässige Event-Auslieferung für Chat→Notification/Audit/Activity/Search; neuer Prefix `chat.` für Activity-Stream-Integration (Block K) |
| `apps/worker/src/handlers.ts` (`buildHandlerRegistry`, `HandlerDependencies`, `createRegisteredProcessor`) + `apps/worker/src/queues.ts` (Cron-Muster) | Worker-Handler-Registry + Cron-/Queue-Muster (DI-Seams) | **als-vorlage** — Block C.1 Auto-Archive-Cron (Projekt-Chat 7d nach Abschluss), Block G.2 Link-Preview-Async-Job, Read-Receipt-Batch |
---
## Vorhandene Daten-Modelle (konkret)
**Direkt nutzbare Querschnitts-Modelle:**
- `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` — `prisma/schema/notifications.prisma` (Block I.2 + J.2)
- `AuditEvent` — `prisma/schema/core.prisma:213`-Umfeld bzw. core (Hash-Chain) (Block L.7, H.6)
- `FileObject`, `FileUploadProgress`, `FileChunk` — `prisma/schema/core.prisma:213` ff. (Block G.1, **nicht tenant-scoped** → Caveat)
- `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit` — `prisma/schema/featureFlags.prisma` (DoD Feature-Flag)
- `Outbox` — `prisma/schema/outbox.prisma` (Event-Auslieferung)
**Als konzeptionelle Vorlage (Muster, nicht 1:1):**
- `RowComment` (`value`, `createdByUserId`, `isDeleted`, `reactions[]`) + `RowCommentReaction` (`reaction String`, `createdByUserId`) — `prisma/schema/entityBuilder.prisma:409`/`:424` → Vorbild für `TeamChatMessage` + `TeamChatReaction`
- `RowTask` (`title`, `description`, `assignedToUserId`, `deadline`, `completed`) — `prisma/schema/entityBuilder.prisma` → Vorbild für „Mark as Task" (Block G.3), aber Ziel-Modell ist M26-Task
- `CollabDoc` (`ydocState Bytes`, `version`, `@@unique([tenantId, resourceType, resourceId])`) — `prisma/schema/collabDocs.prisma` → **nicht** für Chat verwendbar (CRDT-Binär, kein Message-Modell)
- `Chat`/`ChatMessage`/`ChatMessagePart` — `prisma/schema/ai.prisma:1`/`:31`/`:44` → **AI-Assistent-Chat** (LLM-Konversation), namentlich kollidierend aber fachlich irrelevant für Team-Chat. **Vorsicht:** Modell-Namen `Chat`/`ChatMessage` sind in der Boilerplate bereits belegt → HiveGrid-Chat-Modelle brauchen anderen Namespace (z.B. `TeamChat`/`TeamChatMessage` gemäß Spec Block A)
---
## Lücken / komplett neu zu bauen
**Datenmodell (Block A) — komplett neu, 7 Modelle (kein Boilerplate-Äquivalent):**
- `TeamChat` (Channel mit `kind` project/group/dm, `project_id`, `is_private`, `archived_at`/`archived_reason`, `last_message_at`, `notification_default`, Partial-Unique-Index pro Projekt)
- `TeamChatMember` (M:N, `role_in_chat`, `notification_pref`, `last_read_message_id`, `is_pinned`, `left_at`, Last-Admin-Logik)
- `TeamChatMessage` (`body` Markdown, `body_format` markdown/system, `parent_message_id` für Threads, `mentions[]` JSON, `attachments[]`, `link_previews[]`, `edited_at`/`deleted_at`, `system_event_kind`, GIN-Index auf mentions, Trigram-Index auf body)
- `TeamChatPinnedMessage` (max 50/Channel, `note`)
- `TeamChatReaction` (Unique `(message_id, user_id, emoji)`, Anti-Spam-Limits) — Muster aus `RowCommentReaction`, aber eigenes Modell
- `TeamChatThread` (denormalisiert `reply_count`/`last_reply_at`/`participant_user_ids[]`)
- `TeamChatRead` (Read-Receipt pro User/Message, Aggregat „X von Y gelesen")
**Echtzeit (Block H) — größte Lücke:**
- Generischer **WebSocket-Server `/ws/chat`** mit Rooms-pro-Channel-Modell, bidirektionalem Typing/Presence — existiert NICHT. `realtime` (SSE-Notification) + `hocuspocus` (CRDT) sind nur Vorlagen.
- Chat-Event-Union (`message.new/edited/deleted`, `reaction.added/removed`, `thread.reply`, `read.receipt`, `typing.start/stop`, `channel.*`, `presence.*`, `link_preview.ready`) — komplett neu (Block H.2)
- Typing-Indikator (Block H.4), Presence online/away/offline (Block H.5) — neu (shared-store als KV-Fundament)
- Per-Event-Auth-Revalidation (Block H.6, AV) — neu
- Optimistic-UI + Initial-50 + Cursor-Infinite-Scroll (Block E) — neu
**Mentions mit Auto-Verknüpfung (Block F.4) — neu:**
- Mention-Resolver über User/Project(M4)/Deal(M3)/Contact/Company(M1) mit Permission-Filter, Auto-Complete-Lookup, `@channel`/`@here` Spezial-Trigger, Mass-Mention-Confirm, Mention-Markdown-Syntax-Rendering. Kein Boilerplate-Baustein.
**Modul-Verknüpfungen (Block C/K, M113) — neu (Cross-Modul-Wiring zu noch zu bauenden HiveGrid-Modulen):**
- Auto-Projekt-Channel-Anlage bei Project-Anlage (M4), Member-Sync, Auto-Archive-Cron (7d, pipeline-konfigurierbar), Reaktivierung
- Activity-Stream-Erzeugung `chat.message`/`chat.mention`/… (Block K) — Ziel-Activity-Modul (M045) noch nicht in Boilerplate (kein `Activity`-Modell gefunden)
- „Mark as Task" → M26-Task mit Backlink (Block G.3)
**Link-Previews (Block G.2) — neu:**
- EU-self-hosted OG-Tag/oEmbed-Microservice (LP-13), Async-Job, `link_previews[]`-Speicherung. Kein Boilerplate-Baustein (api-client-ts ist nur SDK-Wrapper).
**Quiet-Hours / Override-Hierarchie (Block I) — teils neu:**
- `UserNotificationPreference` deckt per-Category-Enable; Quiet-Hours-Zeitfenster + 4-stufige Override-Hierarchie (Channel-Mute > Quiet-Hours > User-Default > Channel-Default) ist neu (gehört zu M116 User-Settings).
**UI (Block D/E/F/J) — komplett neu:**
- Kein Chat-UI-Component-Set in `packages/ui`/`ui-app`/`ui-subframe` (nur generische Primitive: Avatar, Toast, Textarea, EmptyState). Channel-Index, Chat-Verlauf mit Date-Buckets, Compose-Editor mit @-Mention/Emoji-Picker/Drag-Drop, Thread-Panel, Reactions-Badges, Read-Receipt-Anzeige, Mobile-First-Foto/Voice-Note — alles neu zu designen (Subframe, separat).
**HiveGrid-Repo-Status:** `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud` hat aktuell **kein** `packages/` oder `apps/` (nur `docs`, `_bmad-output`, `prisma`). Die Boilerplate-Pakete sind Quelle/Vorlage; das Chat-Modul wird gegen die noch zu portierende HiveGrid-Code-Basis gebaut.
---
## Empfohlenes Vorgehen
**Phase 0 — Querschnitt aus Boilerplate übernehmen (vor Chat-Logik):**
1. `@toolctrl/foundation` 1:1 nutzen: `permissions` (Block L), `audit` (L.7/H.6), `notifications` (`notify`/`bundleNotifications` für I.2), `errors`/`CatalogError` (Block M), `flags`. Diese sind DoD-Pflicht.
2. `@toolctrl/i18n` + Namespace `chat` anlegen; `@toolctrl/view-models` (`VMState`, `SidebarRegistryItem`, `RegistryGate`) als Loader-/Registry-Fundament. `@toolctrl/feature-flags` für Modul-Gate.
3. `notifications.prisma` (NotificationDelivery/UserNotificationPreference/DeviceToken) 1:1 ins HiveGrid-Schema übernehmen — deckt Block I.2 + J.2.
**Phase 1 — M110 Datenmodell + Permissions (neu, mit Mustern):**
4. 7 `TeamChat*`-Prisma-Modelle neu schreiben (Block A) — `RowComment`/`RowCommentReaction` als strukturelles Vorbild für Message/Reaction; **eigener Namespace** (`Chat`/`ChatMessage` sind in ai.prisma belegt). Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD).
5. Channel-Lifecycle + Membership + Last-Admin-Block über `withTenantScope`/`withPermission`/`withOwnerCheck`. Sidebar-Eintrag „Chat" via `createSidebarRegistry` + `RegistryGate` (Permission `chat.read_own_channels`).
**Phase 2 — M111 Echtzeit (größter Eigenbau):**
6. Redis-Pub/Sub-Broker via `@toolctrl/shared-store` aufsetzen (DB-Index 2). Presence/Typing als KV mit TTL.
7. WebSocket-Server `/ws/chat` neu bauen — **`apps/hocuspocus` als Container-/Auth-Blueprint** (JWT-Handshake + Tenant-Parity), aber eigene Room-/Event-Logik (Chat-Event-Union). EU-Hosting (LP-13).
8. Browser-Subscriber: Reconnect-/Cursor-/Diagnostics-Muster aus `packages/realtime/src/client.ts` übernehmen (Exponential-Backoff, Status-Banner Block M).
9. Messages/Threads/Reactions/Pinned mit Optimistic-UI.
**Phase 3 — M112 Anhänge:**
10. `@toolctrl/storage` (`signed`-URLs) + `scan/*` (ClamAV + Magic-Bytes + Allowlist + Quarantäne) 1:1 für Upload-Pipeline. `FileObject` als Metadaten-Basis, **tenant-scoped Attachment-Join neu** (FileObject hat kein tenantId). Image-Compression client-seitig (browser-image-compression, Block J.3).
**Phase 4 — M114 Mentions + Push + Read-Receipts:**
11. Mention-Resolver neu (Block F.4) — permission-aware Lookup über CRM-Module.
12. Push via vorhandenem `apps/worker/src/jobs/push-notification.ts` + `DeviceToken`; Chat-Payload-Builder mit Datenschutz-Snippet (Block J.2) ergänzen.
13. `notify`/`bundleNotifications` für Notification-Trigger + Anti-Spam-Bündelung; Quiet-Hours-Override-Hierarchie neu (mit M116).
**Phase 5 — M113 Modul-Verknüpfungen (zuletzt, da Cross-Modul-abhängig):**
14. Auto-Projekt-Channel + Member-Sync + Auto-Archive-Cron (Worker-Handler-Registry-Muster) — abhängig von M4-Projekt-Modul.
15. Activity-Stream-Integration (Block K) via Outbox-Prefix `chat.` — abhängig von Activity-Modul (M045, in Boilerplate noch nicht vorhanden).
16. „Mark as Task" → M26.
**Link-Previews (Block G.2):** EU-Microservice separat (Phase-2-nah), Async-Job über Worker-Muster.
> **Reihenfolge-Kernaussage:** Zuerst alle Foundation-Querschnitte 1:1 ziehen (sofortiger DoD-Gewinn), dann das Datenmodell + die Echtzeit-Schicht als Hauptaufwand neu bauen (mit hocuspocus/realtime/shared-store als Infrastruktur-Vorlagen, nicht als fertige Lösung), zuletzt die Cross-Modul-Verzahnung (abhängig von M4/M3/M1/M26/M45).
@@ -0,0 +1,177 @@
# Boilerplate-Mapping: M14 — HR-Hub / Mitarbeiterplattform
> Abgleich-Report. Stellt fest, was fuer M14 aus der Boilerplate
> (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`) uebernommen werden kann,
> was angepasst werden muss und was komplett fehlt.
> Boilerplate wurde NUR gelesen. Alle Pfade absolut.
## Kopf
| Feld | Wert |
| --- | --- |
| Modul-ID | M14 |
| Name | HR-Hub / Mitarbeiterplattform |
| Spec | `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M14-hr-hub.md` |
| Milestones | M133 (Stammdaten+Standorte), M134 (Dokumente), M135 (Urlaub), M136 (Krankmeldungen), M137 (Kommunikation/Announcements/Quick-Links/Resources/Password-Safe), M138 (Onboarding-Drittanbieter), M139 (Anträge+Surveys+Lohn-Export+DSGVO), M140 (MA-Selbstbedienung/Hub) |
| Pflichtenheft-Block | Block 6, Modul 14 (`_bmad-output/pflichtenheft/blocks/block6.md` Abschnitte 14.1–14.17) |
| Size | XL |
| **Reuse-Level** | **low** (kein einziges HR-Domänen-Modell vorhanden; aber sehr starke Querschnitt-/Infrastruktur-Basis) |
### Begründung Reuse-Level = low
Die HR-Fachdomäne ist in der Boilerplate **vollständig abwesend**: es gibt **keine** der 21 in der Spec genannten Entitäten als Prisma-Modell und **kein** HR-Modul in `apps/web`. Verifiziert per Grep gegen `prisma/schema/*.prisma` (keine Treffer auf `Hr*`, `Employee*`, `Vacation*`, `Sick*`, `Payslip*`, `PasswordSafe*`, `Announcement*`, `Survey*`, `Leave*`) und gegen `apps/web/app/**` (kein `hr/`, `employee/`, `payslip/`, `vacation/`, `announcement/`, `directory/`-Verzeichnis).
Trotzdem ist der Wiederverwendungs-Hebel auf der **Querschnitt-/Infrastruktur-Ebene hoch**: Verschlüsselung (AES-256-GCM-Helper), Storage+Signed-URLs, Audit-Hash-Kette, Notifications (In-App/E-Mail/Push), Permissions/Owner-Check, Export (CSV/DSGVO/Audit-PDF), Import (Bulk/Dedupe — für Payslip-Bulk-Upload), Form-Widget, Worker/Cron (Reminder-Engine), Feature-Flags und das View-Model-/Sidebar-Registry-Fundament sind alle vorhanden. M14 baut sein Datenmodell + Service-Layer + UI neu, klinkt sich aber durchgängig in fertige Querschnitte ein.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/api/.server/CryptoApi.ts` | AES-256-GCM Encrypt/Decrypt (`aes-256-gcm`, 12-Byte-IV, AuthTag, versioniertes `v1:iv:tag:ct`-Format, Key = SHA-256 von `CRYPTO_SECRET`) | **als-vorlage** — direkt für Password-Safe-Werte (`username`/`password`/`notes_encrypted`) und Sick-Cert-Encryption. ACHTUNG: nutzt **einen** Env-Key, **nicht** Per-Tenant-KMS/per-Eintrag-DEK wie die Spec (Block J) fordert → Architektur-Lücke (s.u.) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/leads/marketingIntegrations.db.server.ts` | Muster „selektive Feld-Verschlüsselung at-rest in JSON + nie Re-Display im UI" (`encryptSensitive`/`decryptSensitive` mit `CRYPTO_TAG`-Prefix, Merge+Re-Encrypt bei Patch) | **als-vorlage** — exakt das Reveal/Edit-Verhalten für Password-Safe-Einträge (UI zeigt entschlüsselten Wert nie automatisch) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/index.ts` + `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/signed/` | `putObject`, Signed-Upload/-Download, S3/Scaleway-Provider | **1:1** — für alle Datei-Anhänge (Payslips, Employee-Docs, Sick-Certs, Announcement-/Request-Attachments). Tenant-isolierte Pfade (`tenants/{tenantId}/payslips/{userId}/…`) als Key-Konvention selbst setzen |
| `prisma/schema/core.prisma` → `model FileObject` (`/Users/raffaelsheikh/.../boilerplate/prisma/schema/core.prisma`) | Storage-Metadaten-Modell (`provider`/`bucket`/`key`/`contentType`/`byteSize`/`checksumSha256`, signed-Timestamps) | **1:1** — File-Referenzen aller HR-Dokumente (Spec verweist auf „File M23"; M23 = dieses FileObject) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/notifications.ts` | `notify`/`notifyMany`/`bundleNotifications`, Preference-Check, `sourceKey`-Upsert, `assertI18nKey` | **1:1** — alle M14-Notifications (Approver/Antragsteller/HR-Admin/Reminder/Announcement-Push). INTEGRATION-CONTRACTS §6 verlangt `notify()` statt Direkt-Versand |
| `prisma/schema/notifications.prisma` → `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` | In-App + E-Mail + Push-Token-Modelle (APNs/FCM/WebPush) | **1:1** — Push für Krankmeldung/Urlaub/Payslip/Reminder (Spec Block N M22); Mobile-Push bereits modelliert |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/permissions.ts` | `withTenantScope`, `withPermission`, `withOwnerCheck`, `requirePermission`; Fehlschlag = `CatalogError(notFound)` (404, nicht 403) | **1:1** — deckt Block O exakt: Owner-Check (`read_own`), 404-statt-403 (LP-9 Information-Hiding), Tenant-Scope. HR-Permission-IDs selbst registrieren |
| `prisma/schema/permissions.prisma` → `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` | RBAC-Fundament; `Group`/`GroupUser` für Audience-Auflösung (`audience_group_ids`) | **1:1** — HR-Permission-Bundles (`hr.employee`…`hr.admin`) als `Permission`-Sätze + Default-Rollen-Zuweisung. Audience „groups" nutzt `Group` |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/audit.ts` + `/Users/raffaelsheikh/.../packages/db/src/audit-hash.ts` | `auditEvent`/`withAuditMiddleware`; tamper-evidente Hash-Kette (`previousHash`/`eventHash`), `dataSensitivity`, `regulatoryScope[]` | **1:1** — Block P „Audit": Pflicht-Audit für sensible Reads (Payslip-Download, Sick-Cert-Einsicht, **Password-Safe-Reveal**), `regulatoryScope=gdpr`, `dataSensitivity=pii` |
| `prisma/schema/core.prisma` → `AuditEvent` | Audit-Trail-Tabelle (actor, target, outcome, Hash-Chain) | **1:1** — alle schreibenden HR-Aktionen + sensible Reads |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/idempotency.ts` + `core.prisma:IdempotencyKey` | `withIdempotency` (scope+key, In-Process-Lock, 409 bei Konflikt) | **1:1** — Antrags-Submit, Payslip-Bulk-Upload, Reveal-Endpoint (Replay-Schutz) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/exports/` (`./csv`, `./json`, `./pdf`, `./audit-pdf`, `./s3-multipart`, `./limits`) | Streaming-Export CSV/JSON/PDF + Audit-Compliance-PDF + Plan-Row-Caps | **1:1** — M139 Lohn-Export-CSV (Steuerberater), Survey-CSV-Export, DSGVO-MA-Datenexport, Audit-Reports |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/jobs/dsgvo-export.ts` + `/Users/raffaelsheikh/.../packages/db/src/dsgvo/user-fk-map.ts` | DSGVO-Personal-Data-Export-Job (aggregiert alle User-FK-Rows, JSON-Bundle → S3 → Signed-URL → AuditEvent) | **anpassen** — neue HR-Modelle in `USER_FK_MAP` eintragen (Pflicht, sonst CI-Bruch), dann deckt der Job M14 Block P „DSGVO-Auskunftsrecht" + M139 14.16.5 ab |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/imports/` (`createImportDryRunPreview`, `dedupe`, Diagnose-Redaction) | Bulk-Import-Framework mit Dry-Run-Preview + Dedupe + PII-Redaction | **als-vorlage** — Payslip-Bulk-Upload (Block F): Match-Vorschau (Hard/Soft/No-Match), Doppel-Upload-Erkennung. Dateiname-Pattern-Match (`{personal_number}-{yyyy-mm}.pdf`) ist HR-spezifisch und neu |
| `prisma/schema/imports.prisma` → `ImportJob` | Job-Tracking (accepted/rejected rows, error-report) | **anpassen** — Bulk-Upload-Status + Aktivitäts-Bericht (Block F Schritt 7) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/form-widget/` + `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) + `apps/web/app/modules/formWidget/builder/` | Form-Definition (Zod), Submission-Routing, Field-Mapping, Form-Builder-UI | **anpassen** — Urlaubsantrag/Krankmeldung/Request laufen laut Spec (Block E/H, Block N M5) als M5-Forms; `form_submission_id`-FKs zeigen darauf. Neue Form-Action-Typen (`create_hr_vacation_request`…) sind HR-spezifisch zu ergänzen |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/outbox.ts` + `apps/worker/src/outbox/event-router.ts` | Transaktionaler Outbox-Publisher + Event-Routing (Prefix→Queue) | **1:1** — alle HR-Side-Effects (Activity, Notification, Automation-Trigger `hr.*`) atomar mit DB-Write. Block M Activity-Typen als Outbox-Events |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/` (Cron-Scheduler, BullMQ-Gruppen, `HandlerDependencies`) | Worker-Runtime mit single-instance Cron + Queue-Consumer | **anpassen** — Reminder-Engine (Block G: täglicher Cron `once`/`yearly`/`every_n_months`/`on_expiry`), Überfälligkeits-Eskalation, Aufbewahrungs-Hard-Delete-Cron (Block P) als neue Jobs nach Muster von `dsgvo-grace-cron.ts`/`audit-retention.ts` |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/feature-flags/` + `packages/foundation/src/flags.ts` | Feature-Flag-Engine v2 (Targeting) + leichtgewichtige Gates | **1:1** — AV #7 „Feature-Flag-Hülle" (`hr.feature_resturlaub_tracking`), Modul ohne Deploy abschaltbar (DoD) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models/src/index.ts` | `VMState`, `ActionCallbacks`, `RegistryGate`, `I18nLabel`, `SidebarRegistryItem`, `assertI18nLabel` | **1:1** — Loader-baut-VM-Disziplin (DoD „Code-Layer-Disziplin"), Sidebar-Gating per Permission/Flag |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/layouts/sidebars/shadcn/` + `app/application/sidebar/AppSidebar.tsx`, `SidebarItem.ts` | App-Shell (App/Admin/Docs), datengetriebene Sidebar mit Permission-/Feature-Gate, Breadcrumb-Header, Mobile-Sidebar | **als-vorlage** — HR-Hub-Hauptpunkt + kontextabhängige Sub-Punkte (Block B); HiveGrid registriert real in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (INTEGRATION-CONTRACTS §1) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/ui/` (table, tabs, dialog, sheet, form, calendar, chart, multi-select, pagination, command, badge, card, drawer, stepper, modals, emptyState, loaders, pdf-viewer, editors) | shadcn/Radix-Primitives + Tabellen/Forms/Modale/Empty-/Loading-States/PDF-Viewer/Markdown-Editoren | **als-vorlage** — Feed-Listen, Detail-Views, Reveal-Dialoge, Payslip-PDF-Viewer, Leave-Kalendersicht (`calendar.tsx`/`chart.tsx`), Survey-Auswertung (`chart.tsx` für Bar/NPS) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/i18n/` + `apps/web/app/locale/` | i18n (de/en), Intl-Formatter (Datum/Zahl), ICU-Plurale, `useTranslate` | **1:1** — alle Klartext-Hinweise (Block Q) als i18n-Keys (DoD + INTEGRATION-CONTRACTS §10). Locale-File neu: `packages/i18n/src/locales/de/hr.json` |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/entities/` (Entity-Builder: Properties, Views, RowComment/RowCommentReaction, RowTask, RowTag) | No-Code-Entity-Engine inkl. Kommentare+Reaktionen+Tags-Muster | **als-vorlage** — Announcement-Comments/-Reactions und Request-Comments können das `RowComment`/`RowCommentReaction`-Muster adaptieren; Phase-2-Custom-Felder pro `HrEmployeeProfile` (Block R) per Entity-Builder |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`) + `apps/web/app/modules/onboarding/` | Integrations-/Sync-Engine (verschlüsselte Credentials, Rollback-fähige Sync-Runs) + Onboarding-Flow-Modelle | **anpassen** — M138 Onboarding-Drittanbieter (Memberspot/Boobora) via Apps-Engine: Read-Sync Modul-Abschlüsse/Zertifikate/Quiz/Fortschritt = `AppSyncRun`/`AppSyncItem`-Muster |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/client.server.ts` + `transactions.server.ts` | `getDbClient`/`getReadDbClient`/`getExtendedDbClient`, `runDbTransaction` | **1:1** — DB-Boundary für alle HR-Repositories; Read-Replica für Hub-/Verzeichnis-Dashboards |
| `prisma/schema/app.prisma` (`// custom database models`) | Leerer Platzhalter für projekt-eigene Modelle | **1:1** — vorgesehener Ort für ALLE 21 HR-Modelle (alternativ HiveGrid-eigene Schema-Datei `hr.prisma`) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/search/indexed-entities.ts` (per INTEGRATION-CONTRACTS §7) | Such-Index-Registry | **anpassen** — MA-Verzeichnis-Suche, Announcement-Volltextsuche registrieren |
---
## Vorhandene Daten-Modelle (konkrete Prisma-Modelle, die M14 nutzt/erweitert)
**Wichtig: KEIN HR-Domänen-Modell existiert. Folgende Boilerplate-Modelle sind Anbindungs-/Querschnitt-Modelle, auf die M14 verweist:**
| Modell | Pfad | M14-Bezug |
| --- | --- | --- |
| `TenantUser`, `User`, `Tenant` | `prisma/schema/accounts.prisma` | `HrEmployeeProfile.user_id` (1:1 mit TenantUser), `manager_user_id`; Auto-Seed leeres Profil bei Tenant-User-Anlage (Spec A „Sonderfall", 14.1.5). `User.totpSecretEncrypted` zeigt das Encrypted-Suffix-Muster für 2FA (Block P 2FA-Empfehlung) |
| `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` | `prisma/schema/permissions.prisma` | Permission-Bundles Block O; Audience-Auflösung `groups` |
| `FileObject` | `prisma/schema/core.prisma` | Datei-Backing für `file_id`/`attached_file_ids[]`/`certificate_file_id`/`avatar_file_id` |
| `AuditEvent`, `IdempotencyKey`, `Event` | `prisma/schema/core.prisma` | Audit-Trail; Idempotenz; generischer `Event` (kein Calendar-Event!) |
| `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` | `prisma/schema/notifications.prisma` | Notifications/Push |
| `OutboxEvent` | `prisma/schema/outbox.prisma` | Activity-/Automation-/Notification-Fanout (`hr.*`-Events) |
| `Form`, `FormSubmission` | `prisma/schema/formWidget.prisma` | `form_submission_id` für Urlaub/Krank/Request |
| `ImportJob` | `prisma/schema/imports.prisma` | Payslip-Bulk-Upload-Tracking |
| `ExportJob` | `prisma/schema/queue.prisma` | Lohn-/Survey-/DSGVO-Export |
| `App`, `DataConnection`, `AppSyncRun`, `AppSyncItem` | `prisma/schema/appsEngine.prisma` | M138 Drittanbieter-Onboarding-Sync |
| `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit` | `prisma/schema/featureFlags.prisma` | AV #7 Feature-Flags |
| `Onboarding*` (7 Modelle) | `prisma/schema/onboarding.prisma` | Produkt-Onboarding-Tour (NICHT MA-Onboarding) — nur als Muster für M138 |
---
## Lücken / komplett neu zu bauen
### A. Alle 21 HR-Domänen-Modelle (komplett neu, in `app.prisma` / `hr.prisma`)
`HrEmployeeProfile`, `HrAnnouncement`, `HrAnnouncementRead`, `HrAnnouncementReaction`, `HrAnnouncementComment`, `HrLocation`, `HrEmployeeDocument`, `HrResource`, `HrQuickLink`, `HrSurvey`, `HrSurveyItem`, `HrSurveySubmission`, `HrSurveySubmissionAnswer`, `HrRequest`, `HrRequestTemplate`, `HrRequestComment`, `EmployeePayslip`, `EmployeeUploadReminder`, `EmployeeUploadReminderDispatch`, `EmployeeVacationRequest`, `EmployeeSickLeaveReport`, `EmployeePasswordSafeVault`, `EmployeePasswordSafeEntry`, `EmployeePasswordSafeAccess` — **kein einziges existiert**. Inkl. aller Indizes (Spec A „Indizes") und der zusätzlichen App-Code-Permission-Layer über RLS hinaus (Spec A „RLS / Datenisolation").
> Pflicht beim Bau: jedes Modell mit User-FK in `packages/db/src/dsgvo/user-fk-map.ts` eintragen (Cascade-Strategie `hard-delete`/`pseudonymize`/`retain-tombstone` + `includeInExport`) — der CI-Test bricht sonst. HR hat gesetzliche Aufbewahrungsfristen (Block P: 10/4 Jahre) → meist `retain-tombstone`/anonymisieren statt hard-delete.
### B. Per-Tenant-KMS / Per-Eintrag-DEK für Password-Safe (Architektur-Lücke)
Die Spec (Block J „Verschlüsselung") fordert **Per-Tenant-Master-Key im KMS (Scaleway-KMS) + Per-Eintrag-DEK gewrappt mit Master-Key**. Die Boilerplate liefert nur `CryptoApi.ts` mit **einem** Env-abgeleiteten Key (`CRYPTO_SECRET`) und **keine** KMS-Integration, **kein** DEK-Wrapping, **keine** Key-Rotation. → Das KMS-/DEK-Wrapping-Layer ist komplett neu zu bauen (Master-Key-Rotation explizit Phase 2). CryptoApi taugt nur als AES-256-GCM-Primitive darunter.
### C. Leave-/Approval-Workflow-Engine (komplett neu)
Genehmigungs-Workflow (submitted→approved/rejected/withdrawn), Default-Approver-Auflösung (`manager`/`fixed_user`/`role`/`group`), Approver-Rückfrage, `working_days_count`-Berechnung. Es gibt KEINE generische Approval-Engine in der Boilerplate. Der `workflows.prisma`-Builder ist node-basierte Automation, kein menschlicher Genehmigungs-Workflow.
### D. DE-Feiertagskalender / Bundesland-genaue Arbeitstage-Berechnung (komplett neu)
`working_days_count` netto ohne Wochenende + Bundesland-Feiertage (aus `HrLocation`). Keine Feiertags-Library/-Logik in der Boilerplate (offener Detail-Punkt in der Spec).
### E. Calendar-Integration (Modell fehlt)
Spec Block N M25: genehmigter Urlaub → Calendar-Event. Es gibt **kein** Calendar-/CalendarEvent-Modell in der Boilerplate (nur generischer `Event` in `core.prisma` = Webhook-Event, kein Kalendereintrag). `calendar_event_id`-FK zeigt auf ein erst zu bauendes M25.
### F. Plantafel-Konflikt-Detection (Modul-übergreifend, neu)
Spec Block N M4: genehmigte Urlaube + aktive Krankmeldungen als Konflikt-Indikatoren in Plantafel/ScheduleEntries. Kein ScheduleEntry-Modell vorhanden — gehört zu M4, ist hier nur Integrationspunkt.
### G. Automation-Trigger/-Actions `hr.*` (neu)
Spec Block N M17: `hr.vacation_requested`, `hr.sick_leave_reported`, Actions `hr.send_announcement` etc. Die Outbox/Workflow-Infra existiert, aber die HR-spezifischen Trigger/Action-Definitionen + Block-Verträge sind neu.
### H. Reminder-Engine-Cron-Logik (neu, Muster vorhanden)
Block G: Dispatch-Erzeugung pro Cadence, Überfälligkeits-Eskalation, `reminder_count`-Wiederholung. Worker-Cron-Muster vorhanden (s.o.), aber die konkrete Reminder-Logik + `on_expiry`-Lookahead auf `valid_until` ist neu.
### I. SHK-Default-Seeding (neu)
Block H/LP-3: Default Request-Templates (Spesen/Hardware/Schulung/Zeugnis/Sonstiges), Default-Reminder, Default-Announcements. Seeding-Infra vorhanden (`packages/db/src/seed`), HR-Inhalte neu.
### J. HR-spezifische UI-Surfaces (neu, in `packages/ui-hivegrid`)
Announcement-Feed + Detail (Reaction-Picker, Read-Receipt-Tabelle), Leave-Übersicht (Tabs + Kalendersicht), Password-Safe Reveal-UI (Copy-mit-Auto-Clear-30s), Survey-Editor + Auswertung, MA-Verzeichnis (Karten/Liste + Click-to-Call/Mail/Chat), Bulk-Upload-Match-Vorschau, Hub-Startseite mit Widgets. Primitives vorhanden (Tabelle/Tabs/Chart/Calendar/Dialog), HR-Komposition neu. Subframe-Adapter-Layer ist Boilerplate-seitig leer (`@toolctrl/ui-subframe` = Stub) — HiveGrid muss diese Grenze selbst füllen (MEMORY: Subframe für alle Routes Pflicht).
### K. Permission-IDs `hr.*` (neu registrieren)
Alle 18 atomaren Permissions + 5 Bundles (Block O) als TypeScript-Konst in `packages/entitlements/src/permissions.ts` (INTEGRATION-CONTRACTS §8) + Default-Rollen-Zuweisung (SHK-Template).
### L. `@hivegrid/activity` `logActivity` (HiveGrid-Querschnitt, kein BP-1:1)
INTEGRATION-CONTRACTS §5 verlangt `logActivity` aus `@hivegrid/activity` (M045) — das ist ein HiveGrid-eigenes Paket, nicht die Boilerplate-Foundation. Block M Activity-Typen `hr.*` dort registrieren.
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 1 — Fundament aus BP einklinken (vor jedem Feature):**
1. HR-Permission-IDs + Bundles in `packages/entitlements/src/permissions.ts` registrieren (Block O). Voraussetzung für jede Route.
2. Datenmodelle in `prisma/schema/app.prisma` (oder neue `hr.prisma`) anlegen — **gestaffelt pro Milestone**, nicht alle 21 auf einmal. M133 zuerst: `HrEmployeeProfile`, `HrLocation`. Jeweils sofort `USER_FK_MAP` ergänzen (CI-Gate).
3. DB-Repositories über `@toolctrl/db/client.server` + `runDbTransaction`; Side-Effects ausschließlich via `publishOutboxEvent` (INTEGRATION-CONTRACTS §6/Outbox).
4. Sidebar-Eintrag in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` + Routes unter `app.$tenant/hr/*` und `admin/hr/*` (Block B), gegated via `withTenantScope`+`withPermission` (404-statt-403).
**Phase 2 — Stammdaten/Verzeichnis/Dokumente (M133, M134):**
5. `HrEmployeeProfile`/`HrLocation` + Verzeichnis-UI (Click-to-Call M12/Mail/Chat M13). i18n-Keys `hr.*`.
6. `HrEmployeeDocument` + Upload über `@toolctrl/storage` (`putObject`+signed-download) auf `FileObject`; tenant-isolierte Key-Konvention. Visibility-Gating + Audit auf sensible Reads (`withAuditMiddleware`).
**Phase 3 — Leave + Payslips (M135, M136, M139-Teil):**
7. Form-Templates Urlaub/Krank über `@toolctrl/form-widget` + `FormSubmission`; neue Form-Actions `create_hr_vacation_request`/`create_hr_sick_leave`.
8. **Neu bauen:** Approval-Workflow-Engine, `working_days_count`+DE-Feiertage, Calendar-Event-Hook (sobald M25 da).
9. Payslip-Bulk-Upload: `@toolctrl/imports` Dry-Run/Dedupe als Vorlage + HR-Dateiname-Pattern-Match; `ImportJob`-Tracking; Lohn-Export-CSV via `@toolctrl/exports/csv`.
**Phase 4 — Kommunikation + Password-Safe (M137):**
10. Announcements (Feed/Detail/Reactions/Comments) — `RowComment`/`RowCommentReaction`-Muster adaptieren; Read-Receipts neu. Push via `notify()`.
11. **Password-Safe: KMS/DEK-Layer komplett neu** (Scaleway-KMS + per-Eintrag-DEK über AES-256-GCM-Primitive aus `CryptoApi.ts`); Reveal-Endpoint mit Audit + Idempotenz; Copy-Auto-Clear-UI. Quick-Links/Resources (Audience-Gating).
**Phase 5 — Reminder-Engine + Surveys + Onboarding-Drittanbieter (M138, M139, M140):**
12. Reminder-Cron als neuer Worker-Job nach Muster `dsgvo-grace-cron.ts`/`audit-retention.ts`.
13. Surveys (Items als Form-Renderer-Wiederverwendung) + Auswertung (`chart.tsx`) + CSV-Export.
14. M138 Drittanbieter-Onboarding via `App`/`AppSyncRun`/`AppSyncItem` (Apps-Engine).
15. Hub-Startseite (M140) — aggregiert vorhandene Widgets; DSGVO-Export via `dsgvo-export.ts` (USER_FK_MAP muss vollständig sein).
16. AV #7 Feature-Flag-Hülle + SHK-Default-Seeding.
**Querschnitt durchgängig (DoD/INTEGRATION-CONTRACTS):** Loader-baut-VM (`@toolctrl/view-models`), keine Prisma-Imports in `packages/ui-hivegrid/**`, i18n-Keys (`hr.json`), `logActivity` (M045) + auto-Audit (M001), Smoke-Test + Hot-Swap-Drill + Visual-Snapshot.
---
## Anti-Erfindungs-Hinweise (faktische Grenzen)
- **Es gibt KEIN HR-Datenmodell und KEIN HR-Modul in der Boilerplate.** Verifiziert per Grep gegen `prisma/schema/*.prisma` und `apps/web/app/**`.
- **CryptoApi nutzt EINEN Env-Key, KEIN KMS/DEK.** Die Per-Tenant-KMS-Architektur der Spec ist neu.
- **Kein Calendar-/CalendarEvent-Modell.** `Event` in `core.prisma` ist ein Webhook-/Domain-Event, kein Kalendereintrag.
- **`@toolctrl/ui-subframe` ist ein leerer Stub** — kein gebauter Subframe-Adapter-Layer.
- **Keine generische Human-Approval-Workflow-Engine** (nur node-basierte `workflows.prisma`-Automation).
- **`packages/ui-hivegrid`, `@hivegrid/activity`, `packages/entitlements/src/permissions.ts` (HiveGrid-Variante)** sind HiveGrid-Repo-Konventionen aus INTEGRATION-CONTRACTS — in der Boilerplate so nicht vorhanden (Boilerplate hat `@toolctrl/*`).
@@ -0,0 +1,137 @@
# Boilerplate-Abgleich: M15 — Customer-Portal (Endkunden-Login)
| Feld | Wert |
| --- | --- |
| **Modul-ID** | M15 |
| **Name** | Customer-Portal (Endkunden-Login) |
| **Milestones** | M141 (Auth), M142 (Projekt-Sicht + Status-Mails), M143 (Datei-Upload + Reklamations-Forms), M144 (Subunternehmer-Zugang), M145 (Skalierung / Service-Inbox), M146 (Lebensdauer + DSGVO + Konfig) |
| **Block** | Block 6 — Spezial-Module (Pflichtenheft `block6.md` §15) |
| **Reuse-Level** | **low** |
| **Stand** | Boilerplate read-only verifiziert (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`) |
## Verdict in einem Satz
Der namensgleiche Boilerplate-Baustein (`prisma/schema/portals.prisma` + `apps/web/app/modules/portals` + `apps/web/app/routes/app.$tenant/__portals`) ist ein **White-Label-SaaS-Marketing-Portal** (Subdomain-Hosting, öffentliche Signup-Seiten, Stripe-Connect-Abos, SEO, Analytics) und deckt das HiveGrid-Customer-Portal (Endkunden-Sicht auf eigene Projekte/Dokumente/Status) fachlich **nicht** ab. Nutzbar ist fast ausschließlich die Querschnitt-Hülle (Auth-Primitiven, Storage, Mail, Notifications, Audit, DSGVO-Export, i18n, Outbox, Cron) — die fachliche Datenebene und alle Endkunden-Views sind **neu zu bauen**.
---
## WICHTIG: Eignung von `portals.prisma` (vom Task explizit zu prüfen)
**Befund: nicht geeignet für 1:1-Übernahme, allenfalls als Namens-/Struktur-Vorlage.**
Verifiziert in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/portals.prisma` (12 Modelle):
- `Portal` ist Subdomain-gehostet (`subdomain @unique`, optional `domain`), trägt SEO-Felder (`seoTitle`/`seoDescription`/`seoImage`/`seoKeywords`...), Analytics-Toggles (Simple/Plausible/Google), eigenen `stripeAccountId` (Stripe Connect) und White-Label-Branding. Es gibt **kein** `tenantId @unique` (P1 verlangt ein Default-Portal pro Tenant), **kein** `enabled`/`archived_at`/`is_default`/`slug=portal`.
- `PortalUser` hat `passwordHash` als **Pflichtfeld** (HiveGrid: nullable für Magic-Link-Only), OAuth-Felder `githubId`/`googleId` (gegen EU-Stack AGENTS.md — Apple/Google/Microsoft-Login in P1 verboten), **kein** `status`-Enum (`pending_setup|active|disabled|deleted`), **kein** `linked_contact_id`/`linked_company_id`, **kein** `last_login_at`, **kein** `language`-Konzept passend zu Auto-Mails.
- `PortalUserRegistration` existiert (Token + Email + Name + Company), kommt der HiveGrid-`PortalUserRegistration` strukturell am nächsten — aber an die SaaS-Signup-Logik (`selectedSubscriptionPriceId`) gekoppelt.
- **Komplett fehlend** in `portals.prisma`: `CustomerPortalAccount`, `CustomerPortalMagicLinkToken` (mit `purpose`-Enum), `CustomerPortalSession` (server-side Postgres-Session für PortalUser), `CustomerPortalProjectAccess`, `CustomerPortalProjectDocument`, `PortalConfiguration` (Phasen-Sichtbarkeit/Doc-Auto-Freigabe/Pflicht-Links), `PortalEmailTemplate`. Es gibt **kein** `Session`-Prisma-Modell für PortalUser im gesamten Schema (`grep "model Session" prisma/schema/` ist leer).
- 6 der 12 Modelle sind reines Portal-**Abo-Subsystem** (`PortalSubscriptionProduct/Price/Feature`, `PortalUserSubscription(Product)(Price)`, `PortalCheckoutSessionStatus`) — entspricht direkt dem Anti-Listen-Punkt 15.8.6 (keine Wartungs-Abos/Service-Pakete im Portal in P1) und ist für M15-P1 **nicht** zu verwenden.
Service-Layer `apps/web/app/modules/portals/services/` enthält ausschließlich `Portal.server.ts`, `PortalPricing.server.ts`, `PortalStripe.server.ts`, `PortalSubscription.server.ts`, `StripeConnect.server.ts` — **keinen** PortalUser-Login-/Magic-Link-/Session-Flow. Die Routen `apps/web/app/routes/app.$tenant/__portals/**` sind Tenant-Admin-CRUD über das Portal (Pages, Pricing, Domains, Users-Verwaltung), **kein** Endkunden-Frontend mit eigener Auth.
**Empfehlung:** `portals.prisma` und das `portals`-Web-Modul NICHT erweitern. HiveGrid-Portal-Modelle neu in `prisma/schema/app.prisma` (vorgesehener Platzhalter) als `CustomerPortal*`-Familie anlegen, um Namenskollision mit dem bestehenden `Portal`/`PortalUser` zu vermeiden. Das bestehende Schema bleibt als Struktur-/Feld-Vorlage für `PortalConfiguration` (Branding/Auth-Flags) und `PortalUserRegistration` (Token-Einladung) nutzbar.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/portals.prisma` (Modelle `Portal`, `PortalUser`, `PortalUserRegistration`) | Feld-/Struktur-Vorlage für `CustomerPortalConfiguration` (Branding/Auth-Flags) + Registration-Token-Muster | **als-vorlage** (NICHT 1:1 — siehe Abschnitt oben) |
| `prisma/schema/accounts.prisma` → `MagicLinkToken` (Z.98) | Magic-Link-Token-Pattern (`tokenHash @unique`, `expiresAt`, `consumedAt`, Index `(userId, expiresAt)` + `(expiresAt, consumedAt)`) | **als-vorlage** — neue `CustomerPortalMagicLinkToken` braucht zusätzlich `purpose`-Enum (login/setup/password_reset/email_verification) + FK auf `PortalUser` statt `User` |
| `apps/web/app/routes/auth.magic-link.tsx` (+ `.test.tsx`), `login.tsx`/`login.server.ts`, `forgot-password.tsx`, `reset.tsx`, `verify.$id.tsx` | Bestehende TenantUser-Auth-Flows (Magic-Link, Login, Pwd-Reset, Email-Verify) als Referenz-Implementierung | **als-vorlage** — analog für PortalUser nachbauen mit getrenntem Cookie (`hg_portal_session`) und getrennter Middleware (`requirePortalUser`); KEIN Code-Reuse 1:1 (andere User-Klasse, andere Routes) |
| `apps/web/app/utils/auth/passwordHasher.server.ts` | Passwort-Hashing (für optionales PortalUser-Pwd, ≥12 Zeichen, C.2) | **1:1** (Hasher) — HIBP-Check ist zusätzlich zu verdrahten |
| `apps/api/src/auth/login-rate-limit.ts`, `apps/api/src/auth/cookie/session-cookie.ts`, `packages/config/src/session-cookie.ts` (`resolveSessionCookiePolicy`) | Login-Rate-Limit + sichere Cookie-Policy (HTTP-only/Secure/SameSite=Lax) | **1:1** für Policy-Helper; Rate-Limit-Pattern **anpassen** für Portal-Email/IP-Limits (C.1: 3/15min pro Email, 10/h pro IP) |
| `packages/shared-store` (`createSlidingWindowRateLimiter`, `createFixedWindowRateLimiter`, `createSessionStore`, `createIdempotencyStore`) | Redis-KV für Rate-Limit (Magic-Link-Anfragen), Session-Cache, Idempotenz | **1:1** als Infrastruktur |
| `packages/storage/src` (`signed/`, `access/`, `scan/` mit ClamAV + `magic-bytes-adapter` + `allow-list`, `s3-quarantine`) | Datei-Upload-Pipeline für D.5: signierte URLs, Mime-Type-Allowlist, Virus-Scan, Quarantäne | **1:1** als Infrastruktur — Upload-Pfad `tenants/{tenantId}/projects/{projectId}/portal-uploads/...` + erlaubte Mime-Types (Bilder/PDF/Office/Audio) konfigurieren |
| `prisma/schema/core.prisma` → `FileObject`/`FileUploadProgress`/`FileChunk` | Storage-Metadaten-Modelle | **anpassen** — HiveGrid M23-Files (M052-M055) liefert die eigentliche File-Entität; `CustomerPortalProjectDocument` referenziert diese, nicht direkt `FileObject` |
| `packages/mail/src` (`mailersend.ts`, `queue.ts`, `templates-react`, `types.ts`) | Transaktionaler Mail-Versand (Setup-/Login-/Status-/Doc-Released-/Upload-Received-Mails, Block G) | **1:1** als Versand-Layer; Sending-Domain kommt aus HiveGrid M9 (Tenant-Default) |
| `packages/foundation/src/notifications.ts` (`notify`, `notifyMany`, `bundleNotifications`, `isNotificationEnabled`) + `prisma/schema/notifications.prisma` (`NotificationDelivery`, `UserNotificationPreference`, `DeviceToken`) | Notification-Querschnitt für Push/Email-Digest an PL bei Upload/Form (M22) + Anti-Spam-Bündelung (M145 / 15.13.2.5) | **1:1** — `bundleNotifications` deckt die 30-Min-Bündelung (15.13.2.5) direkt ab |
| `packages/foundation/src/audit.ts` (`auditEvent`, `withAuditMiddleware`) + `prisma/schema/core.prisma` → `AuditEvent` (Hash-Kette) | Portal-Audit (Logins, Downloads, Uploads, Access-Änderungen, Status-Mails — Block A E.6, AV #6) | **1:1** — S3-Upload/Download manuell auditieren (INTEGRATION-CONTRACTS §6 Ausnahme) |
| `packages/foundation/src/permissions.ts` (`withTenantScope`, `withPermission`, `requirePermission`, `withOwnerCheck`) | Tenant-seitige Portal-Permissions (`portal.read/manage_users/manage_access/delete_user/admin`, Block I.1) + 404-statt-403-Pattern (I.3) | **1:1** als Pattern; Permission-Keys neu in `packages/entitlements/src/permissions.ts` definieren |
| `packages/foundation/src/errors.ts` (`CatalogError`, `foundationErrors.notFound` 404) | Klartext-Fehler + Existenz-Versteckung (404 bei fehlendem Project-Access, I.3 / D.3) | **1:1** |
| `packages/foundation/src/flags.ts` / `packages/feature-flags` + `prisma/schema/featureFlags.prisma` | Feature-Flag „Modul ohne Deploy abschaltbar" (DoD), Portal aktivieren/deaktivieren | **1:1** |
| `packages/view-models/src/index.ts` (`VMState`, `ActionCallbacks`, `RegistryGate`, `PortalRegistryItem`, `ShellRegistries`) | View-Model-Vertrag + Portal-Navigations-Registry-Typ (passt zu INTEGRATION-CONTRACTS §14 `portal-shell.config.ts`) | **1:1** als Vertrag |
| `packages/i18n` (`defaultLocale="de"`, `supportedLocales=["de","en"]`, ICU, `formatDate/Currency`) | i18n für alle Portal-Texte (DE/EN je PortalUser.language) + Klartext-Diagnostik (Block K) | **1:1** — neuer Namespace `customerPortal` o.ä. |
| `packages/db/src/dsgvo/user-fk-map.ts` + `packages/db/src/dsgvo/pseudonymize.ts` + Worker `apps/worker/src/jobs/dsgvo-export.ts`, `dsgvo-deletion.ts`, `dsgvo-grace-cron.ts` (24h) | DSGVO-Lösch-Workflow (24h-Reverse-Window, Anonymisierung) + JSON-Daten-Export (Block J / 15.11) | **anpassen** — DSGVO-Infra ist auf `User`-FK ausgelegt; PortalUser-FKs müssen in `user-fk-map.ts` (bzw. analogem Portal-FK-Map) ergänzt werden; Export-Job-Muster (`@toolctrl/exports` JSON) wiederverwenden |
| `packages/exports` (`./json`, `./s3-multipart`) | DSGVO-JSON-Export-Bundle für PortalUser (J.4) | **1:1** als Serializer + S3-Sink |
| `prisma/schema/outbox.prisma` (`OutboxEvent`) + `packages/db/src/outbox.ts` (`publishOutboxEvent`) + Worker `apps/worker/src/outbox/event-router.ts` | Transaktionale Side-Effects (Status-Mail-Trigger bei `project.stage_changed`, M17-Trigger `portal.*`, Mail-Debounce) | **1:1** als Event-Backbone; neue `portal.*` Event-Prefixe im `DEFAULT_OUTBOX_ROUTING` ergänzen |
| `apps/worker/src` (Cron-Scheduler-Muster, `group-runtime.ts`, `handlers.ts`, single-instance Cron wie `dsgvo-grace-cron`) | Lifecycle-Cron-Jobs (M146): Auto-Deaktivierung nach 24 Monaten Inaktivität, Pro-Projekt-Auto-Schließung nach 12 Monaten, Status-Mail-Debounce (5-Min-Window) | **als-vorlage** — neue Portal-Lifecycle-Jobs nach demselben Muster |
| `apps/api/src/route-access-inventory.ts` (Auth-Klassen, u.a. `public-*`) + `apps/api/src/middleware/error-envelope.ts` | Öffentlich erreichbare Portal-Routen (Login/Setup/Reset sind ohne Session erreichbar) als Auth-Klassen-Muster | **als-vorlage** |
| `apps/web` App-Shell (`AppLayout`, `ShadcnSidebarLayout`, `components/ui/*` shadcn/Radix: Tabellen/Forms/Modale/Empty/Loading) + Theme (`Tenant.themeConfig`, `parseThemeConfig`) | Branding-Vererbung P1 (Tenant-Logo + Farbe, 15.8.10) + UI-Primitiven für Tenant-Admin-Konfig-Seiten (E.1–E.6) | **anpassen** — Tenant-Admin-Seiten reuse die App-Shell; Endkunden-Portal-Shell ist eine **eigene, minimale** Shell (INTEGRATION-CONTRACTS §1: „Customer-Portal hat eigene minimale Navigation"), mobile-first (LP-2) |
| `packages/marketing-outbound` (Bündelungs-/Routing-Adapter-Muster) + Lead-Routing-Pattern (M048-Referenz) | Routing-Regeln für Endkunden-Aktivitäten (M145 / 15.13.2.4, „analog Lead-Routing") | **als-vorlage** für die Service-Inbox-Routing-Logik |
| CI-Gates: `verify:phase-c-boundaries`, `verify:i18n`, `verify:tenant-isolation-report`, `verify:sidebar-routes`, `test:hot-swap`, `verify:ui-visual`, Storybook + lost-pixel | Erfüllung der DoD-Checkliste (Layer-Trennung, i18n, Visual-Regression, Hot-Swap-Drill) | **1:1** erben/erweitern |
---
## Vorhandene Daten-Modelle (Boilerplate, konkrete Prisma-Pfade)
| Modell | Pfad | Relevanz für M15 |
| --- | --- | --- |
| `Portal`, `PortalUser`, `PortalUserRegistration`, `PortalPage` | `prisma/schema/portals.prisma` | **Nur als Struktur-Vorlage** — fachlich SaaS-White-Label-Portal, nicht Endkunden-Projekt-Portal (siehe Eignungs-Abschnitt) |
| `PortalSubscription*` (6 Modelle) | `prisma/schema/portals.prisma` | **Nicht verwenden** in P1 (Anti-Liste 15.8.6) |
| `MagicLinkToken` (FK auf `User`) | `prisma/schema/accounts.prisma:98` | Token-Pattern-Vorlage; neuer `CustomerPortalMagicLinkToken` mit `purpose`-Enum + FK auf PortalUser |
| `User`, `Tenant`, `TenantUser`, `Registration`, `TenantUserInvitation` | `prisma/schema/accounts.prisma` | TenantUser-Seite (strikt getrennt von PortalUser, LP-1 AV#2); `Tenant.status`/`Tenant.themeConfig` für Tenant-Lifecycle-Wirkung + Branding |
| `AuditEvent` (Hash-Kette), `IdempotencyKey`, `FileObject`/`FileUploadProgress`/`FileChunk` | `prisma/schema/core.prisma` | Audit, Idempotenz, Storage-Metadaten — Querschnitt |
| `Role`, `Permission`, `RolePermission`, `UserRole`, `Group` | `prisma/schema/permissions.prisma` | RBAC-Fundament für Tenant-seitige `portal.*`-Permissions (Block I.1) |
| `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` | `prisma/schema/notifications.prisma` | Notifications/Push an PL (M22) + Anti-Spam-Bündelung |
| `OutboxEvent` | `prisma/schema/outbox.prisma` | Event-Backbone (Status-Mail-Trigger, M17-Trigger) |
| `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit` | `prisma/schema/featureFlags.prisma` | Feature-Flag-Abschaltbarkeit (DoD) |
| `ExportJob`, `ImportJob` | `prisma/schema/queue.prisma`, `imports.prisma` | DSGVO-Export-Job-Tracking |
| `app.prisma` (leerer Platzhalter `// custom database models`) | `prisma/schema/app.prisma` | **Ziel-Ort für alle neuen `CustomerPortal*`-Modelle** |
**NICHT vorhanden (HiveGrid-Domäne, von vorgelagerten Modulen geliefert, nicht von der Boilerplate):**
`Project`/`Auftrag`, `Contact`, `Company`, `Deal`, `Pipeline`, `Stage`, HiveGrid-`File` — `grep "model (Project|Contact|Company|Deal|Pipeline|Stage)"` in `prisma/schema/` ist **leer**. Diese kommen aus M042-M046 (CRM), M059-M064 (Sales), M065-M070 (Auftrag), M052-M055 (Dateien) und sind harte Vorbedingungen (M142-Abhängigkeiten: M066, M052-M055, M092).
---
## Lücken / komplett neu zu bauen
### Daten-Layer (neu in `app.prisma`, alle als `CustomerPortal*`-Familie)
- `CustomerPortal` (ein Default-Portal pro Tenant: `tenantId @unique`, `slug=portal`, `is_default`, `enabled`, `archived_at`)
- `PortalUser` als **eigene Endkunden-User-Klasse** mit `status`-Enum (`pending_setup|active|disabled|deleted`), `linked_contact_id`/`linked_company_id`, `language`, `last_login_at`, optionalem Subunternehmer-Discriminator (M144 / 15.13.2.2)
- `CustomerPortalAccount` (nullable `password_hash`, `terms_accepted_at`, `marketing_opt_in`, `failed_login_attempts`/`locked_until`)
- `CustomerPortalMagicLinkToken` (`purpose`-Enum, Lebenszeiten login=15min/setup=7d/reset=1h/verify=24h, `requested_ip`/`user_agent`)
- `CustomerPortalSession` (**server-side Postgres-Session** für PortalUser — existiert für keine User-Klasse in der Boilerplate; eigener Cookie `hg_portal_session`, 30-Tage-Sliding-Window, 7-Tage-Inaktivität)
- `PortalUserRegistration` (Setup-Token + `welcome_message`)
- `CustomerPortalProjectAccess` (`access_level`-Enum `read_status_only|read_full`, `granted_by`, Soft-Revoke; Indizes `(tenant_id, portal_user_id)`, `(tenant_id, project_id)`)
- `CustomerPortalProjectDocument` (FK auf HiveGrid-File, `release_kind`-Enum, `customer_visible_filename`)
- `PortalConfiguration` (`visible_pipeline_stages` JSON, `stage_display_labels` JSON, `auto_release_doc_types`, `auto_status_mail_enabled`, Pflicht-Links `imprint_url`/`privacy_url`, `support_email/phone`, `welcome_message_default`)
- `PortalEmailTemplate` (`template_kind`-Enum, `subject`/`body` mit Platzhaltern, `from_email_address_id` → M9)
- Subunternehmer-Strukturen (M144): Projekt-Subunternehmer-Liste (Firma/Rolle/Zeitraum), per-Projekt-Sichtbarkeits-JSON
- Service-Inbox / Aktivitäts-Aggregation + Routing-Regeln (M145)
### Auth-Layer (M141) — größte Einzel-Lücke
- Komplette **PortalUser-Auth-Schicht parallel zu M27**: `requirePortalUser`-Middleware, getrennte Cookie-Domäne, Magic-Link-Flow (Anfrage → Token → Validierung → Session), Setup-Flow, Pwd-Reset, Email-Verification — in der Boilerplate existiert NUR die TenantUser-Auth (als Referenz, nicht 1:1 nutzbar). Cross-Permission-Test (Endkunde auf Tenant-Route → 404) ist Erfolgskriterium.
- HIBP-Check für PortalUser-Passwörter (Boilerplate hat Hasher, aber HIBP separat zu verdrahten — vgl. M020)
- hCaptcha ab 3. Magic-Link-Anfrage (C.1)
### UI / Views — komplett neu
- **Endkunden-Portal-Shell** (eigene minimale, mobile-first Navigation; NICHT die Tenant-App-Shell) + `packages/ui-hivegrid/src/customer-portal/portal-shell.config.ts` (INTEGRATION-CONTRACTS §14)
- Alle Endkunden-Views: Dashboard (D.1), Projekte-Liste (D.2), Project-Detail mit Phasen-Fortschritt (D.3), Dokumente-Cross-View (D.4), Upload (D.5), Forms (D.6 — über HiveGrid M5, NICHT `@toolctrl/form-widget`, das nur text/email/number/select kann — kein File/Foto/Signatur), Settings (D.7)
- Alle Tenant-Admin-Konfig-Seiten (E.1–E.6: Portal-Konfig, PortalUser-Verwaltung/-Detail, Access-Matrix, Email-Templates, Portal-Audit) — reuse App-Shell + shadcn-Primitiven, Inhalte neu
- Querschnitt-Erweiterungen in bestehenden HiveGrid-Modulen: Project-Detail-Portal-Sektion (M4), Contact-Detail-Portal-Zugang (M1), Deal-Detail-Sales-Phase-Toggle (M3) — abhängig von M042-M070
### Domänen-Logik / Integration
- Auto-Status-Mail-Engine bei `project.stage_changed` mit Debounce (5-Min-Window), Mehrfach-Empfänger, Reverse-Stage-Stumm-Logik (Block G) — Outbox + Mail vorhanden, Logik neu
- Doc-Auto-Freigabe-Regeln pro Doc-Typ + manuelle Freigabe/Sperre (15.5)
- M17-Automation-Trigger/-Actions (`portal.*` — Block H), M22-Notifications-Wiring
- Service-Inbox + Routing-Regeln + Stille-Modi + Service-Team-Rolle (M145)
- Pro-Kunden- vs. Pro-Projekt-Lebensdauer-Logik + Lifecycle-Cron (M146)
- DSGVO-Lösch-Workflow für PortalUser inkl. Portal-FK-Map (Export-/Deletion-Infra vorhanden, PortalUser-Verdrahtung neu)
---
## Empfohlenes Vorgehen (Reihenfolge)
1. **Querschnitt zuerst sicherstellen (1:1 aus Boilerplate):** foundation (`auditEvent`, `withTenantScope`/`withPermission`, `notify`, `CatalogError`, flags), `packages/mail`, `packages/storage` (signed/scan/access), `packages/shared-store` (Rate-Limit/Session/Idempotenz), Outbox + Worker-Cron-Muster, i18n, view-models. Diese sind nutzbar wie sie sind.
2. **Daten-Layer neu in `prisma/schema/app.prisma`** als `CustomerPortal*`-Familie — `portals.prisma` als Feld-Vorlage heranziehen, aber NICHT erweitern (Namenskollision + falsche Fachlichkeit). `MagicLinkToken` (accounts.prisma:98) als Token-Pattern, ergänzt um `purpose`-Enum. Forward-Only-Migration mit Inverse-SQL (DoD).
3. **M141 Auth-Schicht neu bauen** (kritischster Block) — TenantUser-Auth-Routen (`auth.magic-link.tsx`, `login.server.ts`, `forgot-password.tsx`, `reset.tsx`, `verify.$id.tsx`) als Referenz, aber als eigene PortalUser-Klasse mit getrenntem Cookie/Middleware. passwordHasher 1:1, HIBP + hCaptcha + Rate-Limits ergänzen. Cross-Permission-404-Test als Gate.
4. **M142 Projekt-Sicht** auf bereits gebauten HiveGrid-Modulen (M042-M070, M052-M055, M092 sind Vorbedingungen) — Endkunden-Views + Permission-aware Filter (`CustomerPortalProjectAccess`) + Status-Mail-Engine (Outbox + Mail 1:1, Debounce-Logik neu).
5. **M143 Upload + Forms** — `packages/storage`-Pipeline 1:1 (signed/scan/mime-allowlist/quarantine), Upload-Pfad-Konvention, Notification an PL via `notify` 1:1; Portal-Forms über HiveGrid M5 (M121-M125), nicht über `@toolctrl/form-widget`.
6. **M144 Subunternehmer** — als Discriminator/Untergruppe der PortalUser-Klasse + per-Projekt-Sichtbarkeits-JSON; Datenleck-Schutz (Subunternehmer sehen Endkunden nicht).
7. **M145 Skalierung** — Service-Inbox + Routing (Lead-Routing-Muster M048 als Vorlage) + `bundleNotifications` 1:1 für 30-Min-Bündelung.
8. **M146 Lebensdauer + DSGVO + Konfig** — Lifecycle-Cron nach `dsgvo-grace-cron`-Muster; DSGVO-Export/Deletion-Infra (`@toolctrl/exports` JSON + `dsgvo-*`-Jobs) wiederverwenden, PortalUser-FK-Map ergänzen; Tenant-Admin-Konfig-Seiten mit App-Shell + shadcn.
9. **Reachability/DoD verdrahten:** `portal-shell.config.ts` (§14, Default unsichtbar), Permission-Keys in `entitlements/src/permissions.ts`, i18n-Namespace, Smoke-/Hot-Swap-/Visual-Tests, Feature-Flag. CI-Gates erben.
**Anti-Listen-Wächter (nicht bauen in P1):** Portal-eigenes Branding (15.8.10), Chat/bidirektionale Kommunikation (15.8.1/15.8.4), In-App-Notifications im Portal (15.8.3), Wartungs-Abos/`PortalSubscription*` (15.8.6 — das gesamte Abo-Subsystem aus `portals.prisma` bewusst ignorieren), Bulk-ZIP-Download (15.8.9), 2FA-Pflicht (15.8.8), Blog/CMS (15.8.7), eigene Domain (15.14.2), Mehrfach-Portale (15.14.3).
@@ -0,0 +1,106 @@
# Boilerplate-Abgleich — M17 Automation Engine
| Feld | Wert |
| --- | --- |
| Modul-ID | M17 |
| Name | Automation Engine (USP-Säule) |
| Milestones | M075 (Schema + Auslöser-Registry), M076 (Aktion-Registry + Steuerung), M077 (Bedingungen), M078 (Visueller Editor), M079 (Test-Lauf/Schwellenwert-Vorschau), M080 (24h-Undo/Reversibilität), M081 (Schleifen-/Webhook-/Anomalie-Schutz + Resume), M082 (Klartext-Logs + Re-Run + Trigger-Volumen-Metering) |
| Pflichtenheft-Block | Block 4 (USP-Säulen), Modul 17, Abschnitte 17.1–17.9 + Anhang H.1.1 (Metering) |
| Spec | `_bmad-output/specs/M17-automation-engine.md` (USP-Säule, „größte und wichtigste") |
| **Reuse-Level** | **high** |
## Reuse-Zusammenfassung
Die Boilerplate enthält eine **vollständige, produktionsreife, graph-basierte Workflow-Engine** — exakt die in der Spec geforderte Architektur (Knoten + Edges, parallele Branches, If/Switch). Sie umfasst:
- **Datenmodell** (`prisma/schema/workflows.prisma`, 10 Modelle): `Workflow`, `WorkflowBlock`, `WorkflowBlockToBlock` (Edges), `WorkflowBlockConditionGroup`/`WorkflowBlockCondition` (AND/OR), `WorkflowExecution`, `WorkflowBlockExecution`, `WorkflowInputExample`, `WorkflowVariable`, `WorkflowCredential` — tenant-scoped + `appliesToAllTenants` (Plattform-Templates), Execution-Tracking pro Block, alle nötigen Performance-Indizes vorhanden.
- **Visueller Editor** (`apps/web/app/modules/workflowEngine/`, ~120 Dateien): `@xyflow/react`-Canvas mit Mini-Map/Zoom/Pan, `dagre`-Auto-Layout, Knoten-Catalog, pro-Knoten-Config-Panel, Custom-Edges, Pre-Save-Validierung mit Klartext-Fehlern, Block-Errors-Anzeige, Execution-Visualisierung, Streaming-Progress.
- **Engine + Worker** (`apps/worker/src/jobs/workflow-*.ts`, ~16 Dateien): Outbox-getriebener `event`-Trigger-Fanout, Block-Executor-Factory (native + HTTP), Stalled-Execution-Reconciler-Cron, Preflight-Check, Resume-from-block (`fromBlockId`), Continuation/`waitForInput`, BullMQ-Backoff.
- **Bedingungs-Engine** (`WorkflowsConditionsService.ts` + `WorkflowConditionUtils.ts`): Operatoren `=`, `!=`, `>`, `<`, `>=`, `<=`, `startsWith`, `endsWith`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`, AND/OR-Gruppen, `{{$vars}}`/`{{$params}}`-Variablen-Auflösung.
- **Querschnitt**: AES-Credential-Verschlüsselung (`CryptoApi.decrypt`) + Credential-Redaction in Logs, AJV-JSON-Schema-Validierung für Trigger-Payloads, Plugin-Hooks (`workflow.executed`/`workflow.failed`), Idempotenz (`@toolctrl/foundation` + Outbox-Receiver-Idempotency), Default-Templates-Registry (code-basiert, i18n).
Damit ist das **gesamte Architektur-Skelett** von M075–M082 abgedeckt: Graph-Datenmodell, Editor-Library, Execution-Engine, Conditions, Resume-Mode, Trigger-Fanout, Templates-Registry. Was **fehlt**, sind durchweg **HiveGrid-fachliche Inhalte und USP-Mechaniken**: die ~60 domänen-spezifischen Trigger/Actions (Deal/Project/Lead/CRM/Booking/Telefonie/KWP/Portal …), das 24h-Undo/Reverse-Window, Anomalie-Detection + Loop-Guard mit Klartext, KI-Erstellung per Sprache, Dry-Run-mit-Empfänger-Sample + >100-Schwelle, Trigger-Volumen-Metering, sowie die HiveGrid-Permission-Bundles.
**Wichtiger Architektur-Vorbehalt:** Der gesamte Editor- und Service-Code liegt in `apps/web/app/modules/workflowEngine/` als RR7-Route-Module mit `.db.server.ts`/`.api.server.ts`-Dateien — das **kollidiert mit der HiveGrid-Layer-Disziplin** (AGENTS §A: View-Models in `packages/view-models`, UI in `packages/ui-hivegrid`, Subframe via Adapter, keine `useLoaderData` in UI-Components). Plus User-Memory-Blocker: **`.server.ts`-Re-Export ist verboten — nur Component-Extraktion**. Der Code ist daher als **Vorlage** zu behandeln (Logik 1:1 übernehmen, Layer-Struktur umbauen), nicht als 1:1-Import. Datenmodell, Engine/Worker und reine Helper/Services sind dagegen sehr nah an 1:1.
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/workflows.prisma` | Komplettes graph-basiertes Datenmodell: `Workflow`, `WorkflowBlock`, `WorkflowBlockToBlock` (Edges + `condition`), `WorkflowBlockConditionGroup`/`Condition`, `WorkflowExecution`, `WorkflowBlockExecution`, `WorkflowInputExample`, `WorkflowVariable`, `WorkflowCredential`; tenant-scoped + `appliesToAllTenants`, Status/Duration/Error/`waitingBlockId` pro Execution, Indizes | **als-vorlage** — Struktur deckt `AutomationRule`/`RuleStep`/`Execution`/`StepExecution`/`Credential`/`Template` der Spec (Block A). Ergänzen: `created_via` (manual/template/ki_natural_language), `last_executed_at`, `executions_count_30d`, `archived_at`, `dry_run`, `idempotency_key`, `reverse_window_expires_at`, `summary_text`, `parent_step_ids[]`/`position`, sowie ein dediziertes `AutomationTemplate`-Modell (Boilerplate-Templates sind code-only, kein DB-Modell) |
| `apps/web/app/modules/workflowEngine/components/workflows/WorkflowBuilder.tsx` + `LazyWorkflowBuilder.tsx`, `WorkflowBlockEditor.tsx`, `WorkflowEditorSidebar.tsx`, `WorkflowExecutionsSidebar.tsx`, `components/nodes/*`, `components/edges/CustomEdge.tsx` | Vollständiger `@xyflow/react`-Editor: Canvas, Knoten-Catalog-Sidebar, pro-Knoten-Config, Custom-Edges, Trigger-/If-/Switch-Nodes, Lazy-Load | **als-vorlage** — Editor-Grundgerüst + Drag/Connect/Config-Muster 1:1 übernehmbar (deckt M078, Block D). MUSS in `packages/ui-hivegrid` + Adapter-Layer umziehen (AGENTS §A, M015); UI darf kein `useLoaderData` nutzen |
| `apps/web/app/modules/workflowEngine/helpers/WorkflowLayoutUtils.ts` | `dagre`-basiertes Auto-Layout (`getLayoutedElements`, rankdir) | **1:1** — deckt „Auto-Layout"-Toolbar (Block D) |
| `apps/web/app/modules/workflowEngine/helpers/WorkflowUtils.ts` | `buildExecutionOrder` mit `visited`-Set (DFS-Traversal über `true/false/default/case/loopNext/loopEnd`-Branches), Block-Graph-Helfer | **anpassen** — Traversal-Basis; für Loop-Guard/Cycle-Pre-Save-Validation (Block G) als Cycle-Detektor erweitern (vorhandenes `visited` ist Traversal-Schutz, KEINE explizite Cycle-Warnung) |
| `apps/web/app/modules/workflowEngine/services/WorkflowPreflightService.ts` + `helpers/WorkflowReferenceUtils.ts` | Pre-Save/Pre-Run-Validierung: fehlende Variablen/Credentials, fehlende Pflicht-Inputs pro Block, native-Capability-Errors, alles als i18n-Klartext; `throwIfFailed` mit `status:400` + `preflight`-Detail | **als-vorlage** — deckt 17.5.6 „Validator listet alle Probleme" (Block D) sehr gut; ergänzen: „Knoten nicht verbunden / wird nie ausgeführt" + Cycle-Warnung (Klartext aus Spec Block D) |
| `apps/web/app/modules/workflowEngine/services/WorkflowsValidationService.ts` | AJV-JSON-Schema-Compile + `validate`/`parseJsonSchema` für Trigger-Payload-Validierung | **1:1** — Schema-Validation für Trigger-Payloads/manuelle Trigger |
| `apps/web/app/modules/workflowEngine/services/WorkflowsConditionsService.ts` + `helpers/WorkflowConditionUtils.ts` + `dtos/WorkflowConditionDtos.ts` | Bedingungs-Auswertung: 12 Operatoren, AND/OR-Gruppen, `parseVariable`-Auflösung, i18n-Labels, Operator-Validierung | **anpassen** — deckt M077/Block C Conditions (Field-Equals/Contains/Greater/Less, Tag-Set via contains). Ergänzen: `Time-Of-Day`/`Day-Of-Week`, `User-In-Group`, type-safe Feld-Picker, der Trigger-Felder kennt (Spec 17.4 / M077-Hinweis) |
| `apps/web/app/modules/workflowEngine/services/WorkflowsExecutionsService.ts` | Execution-Orchestrierung: Live-Check, Preflight, Execution-Record, Trigger-Block-Suche, **Resume ab `fromBlockId`**, Continuation-Sourcing, Outbox-Publish (`workflow.execution.requested`), Plugin-Hook-Emission, Credential-Redaction | **als-vorlage** — Kern der Engine; Resume-Mode (Block H) bereits angelegt. `.server`-Logik in HiveGrid-Service-Layer (`app/domain/**` / loader-pfad) extrahieren |
| `apps/web/app/modules/workflowEngine/services/blocks/WorkflowBlockService.ts` + `WorkflowBlockProService.ts` + `dtos/WorkflowBlockTypes.ts` | Block-Type-Registry + Executor: `trigger(manual/event)`, `if`/`switch` (flow), `httpRequest`, `log`, `alertUser`, `doNothing`, `waitForInput`, `gpt` (ai), `rowGet/Create/Update/Delete` (entities) — als deklarative `WorkflowBlockTypeDto[]` mit Inputs/Outputs/Conditions | **als-vorlage** — die Registry-Architektur (deklarative Node-Typen + Executor) ist genau das M075/M076-Muster. Inhalte sind aber generisch (`row*`/`httpRequest`/`gpt`) — die ~60 HiveGrid-Trigger/Actions (deal/project/lead/contact/booking/call/kwp/portal/…) müssen NEU als Plug-Registry-Einträge ergänzt werden |
| `apps/web/app/modules/workflowEngine/utils/DefaultWorkflowTemplates.ts` + `WorkflowsTemplatesService.ts` + `workflowTemplateI18n.ts` | Code-basierte Template-Registry mit i18n-Keys, Import-in-Tenant, `adminOnly`/`appliesToAllTenants` | **als-vorlage** — deckt Template-Mechanik (Block I, M082-Templates). Inhalte sind Demo (`sampleHttpRequests`); die SHK-Templates („Lead-Begrüßung", „Won-Handoff", „Stuck-Deal-Eskalation", „Mängel-Tasks-Generator" …) neu schreiben |
| `apps/worker/src/jobs/workflow-trigger.ts` + `workflow-trigger-store.ts` + `workflow-trigger-executor-factory.ts` + `workflow-trigger-native-executor.ts` + `workflow-trigger-http-executor.ts` + `workflow-trigger-bootstrap.ts` | Outbox-getriebener Event→Workflow-Fanout: `findLiveEventWorkflows` (matcht `event`-Trigger gegen `eventName` + Condition-Filter), Idempotenz via Outbox-Receiver, Executor-Factory (native/HTTP), Rejected-Execution-Recording | **anpassen** — exakt die „Auslöser-Registry als Plug-Architektur"-Mechanik (M075-Hinweis). HiveGrid-Module müssen ihre Domain-Events in den Outbox-Bus emittieren (`workflow.*`-Prefix); Event-Liste erweitern |
| `apps/worker/src/jobs/workflow-execution-stalled-reconciler.ts` + `-cron.ts` | Cron: findet hängende Executions (>30 min, `waiting`/`waitingBlock`), gleicht gegen Failed-Outbox/Queue-Failed-Jobs ab, repariert/re-published | **1:1** — Resilienz-Baustein für Resume-Mode (Block H, M081); zusätzlich als Muster für den Stage-Stuck-Daily-Cron (Block K) nutzbar |
| `packages/queue/src/producers.ts` (`retryJobOptionsByQueueAndJobName`, `buildRetryJobOptions`) + `types.ts` (Default `attempts:3`, exponential backoff) | BullMQ-Retry/Backoff-Konfiguration pro Queue/Job, exponential | **anpassen** — Basis für die Auto-Retry-Strategie 1m/5m/15m/1h/6h/24h (Block H, M081); konkrete Backoff-Stufen + „nach 6 Retries failed + Admin-Mail" ergänzen |
| `packages/foundation/src/idempotency.ts` (`withIdempotency`, `IdempotencyClient`) + `prisma/schema/core.prisma` (`IdempotencyKey @@unique([scope,key])`) | Idempotenz-Helper + DB-Modell | **1:1** — `idempotency_key` pro Action-Step (Block H / AV#8); deckt „skip mit Status skipped, wenn schon erledigt" |
| `apps/worker/src/outbox/event-router.ts` (`DEFAULT_OUTBOX_ROUTING`, inkl. `{ prefix: "workflow.", queue: "outbox.workflow" }`) + `outbox/dispatcher.ts` | Outbox→Queue-Routing (longest-prefix-wins), Dead-Letter | **1:1** — der `workflow.`-Pfad ist bereits verdrahtet; HiveGrid-Domain-Events nur emittieren |
| `apps/web/app/modules/workflowEngine/services/WorkflowVariablesAndCredentialsService.ts` + `WorkflowsVariablesService.ts` (`CryptoApi.decrypt`, `redactWorkflowCredentials`, `REDACTED_WORKFLOW_CREDENTIAL`) | AES-verschlüsselte Tenant-Credentials at-rest + Credential-Redaction in Outputs/Logs | **1:1** — deckt `AutomationCredential` (Block A) + Klartext-Logs-Sicherheit (Block J). App-Credentials aus M33a separat anbinden |
| `apps/web/app/modules/workflowEngine/components/workflows/stream/WorkflowStreamProgress.tsx` + Routes `workflows.$id.run.stream.*` + `apps/web/app/modules/workflowEngine/routes/.../run.manual.*` | SSE-Streaming der laufenden Execution + manueller Run-Trigger | **als-vorlage** — Live-Streaming-Antwort (Block E) + Test-Run-UX (Block F/M079); Layer-Umbau nötig |
| `apps/web/app/modules/workflowEngine/utils/workflowExecutionErrorText.ts` + `components/workflows/misc/WorkflowBlockErrors.tsx` + `WorkflowResultBadge.tsx` | Klartext-Fehler-Mapping + Block-Error-/Status-Badges | **anpassen** — Basis für Klartext-Diagnostik (Block J/LP-10); Spec-Klartext-Beispiele (17.9.3) ergänzen |
| `packages/ai` (`@toolctrl/ai`): `src/index.ts`, `prompts/index.ts` (versionierte Prompt-Registry), `tools/index.ts` (scoped Tool-Registry), `streaming/index.ts`, `guards/index.ts` (`assertAICostBudget`, `createFixedWindowAIRateLimiter`, `createReviewRequiredResult`, PII-Redaction), `fallback.ts` (Multi-Provider EU: Mistral/Scaleway/Aleph-Alpha), `cost/*` | KI-Provider-Layer + Guards + Streaming + Cost-Tracking | **anpassen** — Fundament für KI-Erstellung-per-Sprache (Block E/LP-5). `createReviewRequiredResult` deckt Action-Boundary (EC-5); Rate-Limiter/Cost-Guards für KI-Aufrufe. NEU: Intent-Klassifikation + Entity-Extraction + Flow-Graph-Generierung-Prompts |
| `packages/ai/src/promptfoo-provider.ts` + `packages/ai/test/evals/` + Repo-Root `promptfoo.config.yaml` | Promptfoo-Eval-Harness (Baseline-Test) als CI-Gate | **als-vorlage** — deckt AV#14 / EC-5 „Promptfoo-Eval-Suite als CI-Pflicht" für die KI-Flow-Generierung (Block E); eigene Eval-Cases neu |
| `packages/plugin-runtime/src/hooks/registry.ts` (Hooks `workflow.created/updated/deleted/executed/failed`) | zod-validierte Workflow-Lifecycle-Hooks | **1:1** — Audit-Trail-/Activity-Hooks für Rule-Änderungen (AV#6) + Notification-Trigger |
| `prisma/schema/core.prisma` (`AuditEvent` Hash-Kette, `Event`/`EventWebhookAttempt`) + `packages/db` (`publishOutboxEvent`, `runDbTransaction`, `audit-hash.ts`, DSGVO-FK-Map) | Audit-Trail, transaktionale Outbox, signierte Webhooks | **1:1** — Querschnitt für AV#6 (Rule-Change-Audit), `webhook.send (signiert)` (Block C), Reverse-Audit-Eintrag (Block F) |
| `prisma/schema/notifications.prisma` + `apps/web/app/modules/notifications/.../NotificationService.ts` | In-App/Email/Push-Delivery + Preferences + DeviceToken | **1:1** — `notification.send_push`/`send_in_app` Actions (Block C) + Anomalie-/Loop-Guard-Notifications (Block G) via `notify()` (M011) |
| `prisma/schema/featureFlags.prisma` + `evaluateFlagForContext` | Feature-Flag-Engine | **1:1** — DoD-Pflicht „Feature-Flag-fähig" (M006) für das gesamte Modul |
| `packages/view-models` (`VMState`, `ActionCallbacks`, `I18nLabel`, `assertI18nLabel`) | View-Model-Statusmodell + i18n-Key-Zwang | **1:1** — Konvention M013; Loader baut VM, UI empfängt nur VM+Actions (DoD Layer-Disziplin) |
| `package.json` Root-Dep `@xyflow/react ^12.10.0` + `dagre` | Graph-Editor-Library bereits installiert | **1:1** — beantwortet die offene Spec-Frage „Flow-Editor-Library-Wahl"; **xyflow ist gesetzt** |
## Vorhandene Daten-Modelle (konkret)
`prisma/schema/workflows.prisma` — Mapping zur Spec (Block A):
| Spec-Entität | Boilerplate-Modell | Lücke |
| --- | --- | --- |
| `AutomationRule` | `Workflow` (`name`, `description`, `status`, `tenantId?`, `createdByUserId`, `appliesToAllTenants`) | fehlt: `flow_data`-JSON (BP nutzt normalisierte `WorkflowBlock`-Tabellen statt eines JSON-Blobs — beides valide; Spec nennt JSON, BP-Ansatz ist sauberer), `created_via`, `last_executed_at`, `executions_count_30d`, `archived_at` |
| `AutomationRuleStep` | `WorkflowBlock` (`type`, `description`, `isTrigger`, `input`, `conditionsGroups`) + `WorkflowBlockToBlock` (Edges) | fehlt: explizites `step_kind`-Enum, `parent_step_ids[]` (BP modelliert Edges als eigene Tabelle — funktional äquivalent für Multi-Parent), `position` für Editor-Layout |
| `AutomationExecution` | `WorkflowExecution` (`type`, `status`, `input`, `output`, `duration`, `endedAt`, `error`, `waitingBlockId`, `createdByUserId`) | fehlt: `summary_text`, `dry_run`, `idempotency_key`, `reverse_window_expires_at`, `trigger_payload` (steckt in `input`) |
| `AutomationStepExecution` | `WorkflowBlockExecution` (`status`, `startedAt`, `endedAt`, `input`, `output`, `duration`, `error`) | fehlt: `summary_text`, `error_text` (Klartext getrennt vom techn. `error`), `idempotency_key` pro Step |
| `AutomationCredential` | `WorkflowCredential` (`name`, `value`, `@@unique([tenantId,name])`, AES-verschlüsselt) | weitgehend vollständig; `description`-Feld + App-Credential-Bridge zu M33a ergänzen |
| `AutomationTemplate` | (kein DB-Modell) — Templates sind code-basiert in `DefaultWorkflowTemplates.ts` | **komplett neu**: DB-Modell für Tenant-eigene Templates (`is_published`, `category`, `branchen_template_origin`) |
Zusätzlich nutzbar: `WorkflowVariable` (tenant-scoped Vars), `WorkflowInputExample` (Sample-Payloads für Dry-Run-Quelle, Block F offener Punkt), `IdempotencyKey` (core.prisma).
## Lücken / komplett neu zu bauen
1. **Domänen-Trigger-Library (~45 Trigger, Block B / M075):** Boilerplate kennt nur generische Trigger (`manual`, `event` mit `row.created/updated/deleted` + Account/Member/Subscription/Email-Events). Alle HiveGrid-Trigger fehlen: `deal.*` (created/stage_changed/won/lost/stuck/assignee_changed/volume_changed), `project.*`, `lead.*`, `contact.*`, `booking.*`, `call.*` (Telefonie), `task.*`, `form.submitted`, `email.received_inbox`/`subject_pattern_matched`, `kwp.*`, `app.*`, `hr.*`, `portal.*`, `schedule.cron`/`delay`. → Als Plug-Registry-Einträge + Domain-Event-Emission in den jeweiligen Modulen.
2. **Domänen-Action-Library (~40 Actions, Block C / M076):** BP hat nur `httpRequest`, `log`, `alertUser`, `gpt`, `rowGet/Create/Update/Delete`. Fehlen alle CRM/Lead/Sales/Project/Communication/Task/KWP/Calendar/File-Actions inkl. **Pipeline-Targeting** (`deal.create` mit Ziel-Pipeline+Start-Stage), `project.create_from_won_deal` (Won-Handoff mit Default-Mapping), `email.send` (Template+Vars), `notification.send_push/in_app`, `webhook.send (signiert)`, `ai.summarize/classify`. Flow-Control `if`/`switch` vorhanden; `delay`/`parallel`/`merge` ergänzen; **`loop` bewusst NICHT** (Anti-Liste). KI-Actions auf `packages/ai` mappen.
3. **24h-Undo / Reverse-Window (Block F / M080):** Komplett neu. Kein Reverse-Mechanismus in BP. Benötigt: `reverse_window_expires_at`, Snapshot der reversiblen Wirkungen pro Run, Reverse-Handler (Hard-Delete angelegter Entitäten / Status-Reset / Tag-Rückgängig / Empfänger-Liste bei Mails), BullMQ-delayed Cleanup-Job nach 24h, Multi-Step-Confirm + Audit-Eintrag pro Reverse.
4. **Anomalie-Detection + Loop-Guard mit Klartext (Block G / M081):** Komplett neu. Hard-Limit 1.000/h pro Trigger (tenant-konfigurierbar), 10×-Rate-Anomalie→Pause+Notification, Loop-Guard max. 5 Auto-Trigger/Datensatz/60s, Pre-Save-Cycle-Detection mit Klartext-Visualisierung. (BP `createFixedWindowAIRateLimiter` ist NUR für AI-Calls pro userId — nicht für Trigger-Volumen.)
5. **KI-Erstellung per natürlicher Sprache (Block E / wird in M086 referenziert):** Engine-Bausteine (`packages/ai`, Prompt-/Tool-Registry, Streaming, Promptfoo, `createReviewRequiredResult`) vorhanden, aber die **KI-Pipeline selbst neu**: Intent-Klassifikation, Entity-Extraction (Trigger/Filter/Actions), Schema-Validation gegen existierende Pipelines/User/Forms (EC-4), Rückfrage-bei-Mehrdeutigkeit, Flow-Graph-Generierung als JSON, Risiko-Hinweise, Edit-Mode-Diff, Voice via Whisper-EU (M18). Hinweis Spec: M078 listet M086 (KI-Sprache) als „benötigt von" — KI-Erstellung ist eigener Milestone-Strang.
6. **Dry-Run mit Empfänger-Sample + >100-Schwelle (Block F / M079):** BP hat Test-Run/manual-Run + SSE-Streaming, aber **keinen** Side-Effect-freien Dry-Run mit „würde X Personen treffen, erste 5: …", keine konfigurierbare Schwellenwert-Bestätigung (Default 100), kein Mock-Adapter-Layer für Actions.
7. **Trigger-Volumen-Metering (Block L / M082):** Komplett neu. Counter `AutomationExecution` pro Tenant/Monat, Soft-Limit-Warnung bei 80%, Hard-Limit→Queue+Klartext, Visualisierung in `/{tenant}/admin/usage/`. (BP hat `MetricLog`/AI-Cost-Aggregate als Muster, aber kein Trigger-Volumen.)
8. **Stage-Stuck-Eskalation als Daily-Cron (Block K):** Neu — Cron checkt `stage.auto_archive_after_days`, emittiert `deal.stuck.in_stage`/`project.stuck.in_stage`. Reconciler-Cron-Muster (`workflow-execution-stalled-reconciler-cron.ts`) als Vorlage.
9. **HiveGrid-Permissions + Bundles (Block M):** Neu — `automation.read/test/write/activate/delete/reverse/use_ki/admin` + Bundles `basic/builder/publisher/admin` + SHK-Default-Rollen. BP-Workflow-Routes nutzen generische Auth-Boundary (`workflowAccess.server.ts`), nicht diese Permissions. Über M004 `withPermission()` verdrahten.
10. **Klartext-Step-Diagnostik nach Spec (Block J / M082):** BP hat Execution-Detail-Views + Error-Text-Mapping, aber die konkreten Spec-Klartext-Texte (17.9.3: „Email an X gesendet, Dauer 0.8s", Halb-Erfolg, Skipped-mit-Grund) + „Detail-Logs für Plattform-Admin (`tech_details`)" + Re-Run-aus-Log neu formulieren.
11. **Layer-Umbau (querschnittlich, PR-Block-relevant):** Der gesamte `apps/web/app/modules/workflowEngine/`-Editor-/Service-Stack muss in die HiveGrid-Drei-Schichten überführt werden: View-Models → `packages/view-models/src/automation/*.vm.ts`, UI → `packages/ui-hivegrid/src/...` (kein `useLoaderData`, kein Prisma-Import), Subframe-Output via Adapter. **`.server.ts`-Re-Export verboten (User-Memory) → Component-Extraktion.** Sidebar-Eintrag „Automation-Studio" in Gruppe `automation-ki` (INTEGRATION-CONTRACTS §1), Routen unter `/{tenant}/automations/...` (Spec-Pfade) statt BP-`__workflows/workflow-engine`.
## Empfohlenes Vorgehen
**Phase 1 — Fundament aus Boilerplate übernehmen (M075):**
1. `prisma/schema/workflows.prisma` als Basis nach HiveGrid übernehmen, um Spec-Felder erweitern (`created_via`, `archived_at`, `dry_run`, `idempotency_key`, `reverse_window_expires_at`, `summary_text`/`error_text`, `position`) + neues `AutomationTemplate`-DB-Modell. Forward-Only-Migration.
2. Outbox→Workflow-Fanout-Worker (`workflow-trigger*.ts`) + `event-router.ts` (`workflow.`-Prefix ist schon verdrahtet) 1:1 übernehmen.
3. Block-Type-Registry-Architektur (`WorkflowBlockTypes.ts` + `WorkflowBlockService.ts`) als Plug-Registry übernehmen; HiveGrid-Domain-Trigger als erste Einträge ergänzen + Domain-Events in CRM/Lead/Sales/Project emittieren.
**Phase 2 — Actions + Conditions (M076/M077):**
4. Action-Registry mit Idempotency-Key (`foundation/idempotency.ts`) ausbauen; Domänen-Actions inkl. Pipeline-Targeting + Won-Handoff neu; Flow-Control `delay/parallel/merge` ergänzen (kein `loop`).
5. `WorkflowsConditionsService`/`WorkflowConditionUtils` übernehmen, um `Time-Of-Day`/`Day-Of-Week`/`User-In-Group` + type-safe Feld-Picker erweitern.
**Phase 3 — Editor (M078):**
6. `WorkflowBuilder`-Editor (xyflow + dagre) als Vorlage in `packages/ui-hivegrid` + Adapter überführen (Layer-Disziplin, Component-Extraktion statt `.server`-Re-Export). `WorkflowPreflightService` übernehmen + Cycle-/„nicht-verbunden"-Klartext-Validierung ergänzen. Pflicht-Aktivierung als separater Schritt.
**Phase 4 — USP-Mechaniken neu (M079–M082):**
7. M079: Dry-Run-Mode mit Mock-Action-Adapter + Empfänger-Sample + >100-Schwelle (BP Test-Run/Streaming als UX-Vorlage).
8. M080: 24h-Undo/Reverse-Window komplett neu (Snapshot + Reverse-Handler + delayed Cleanup-Job + Audit).
9. M081: Anomalie-Detection + Loop-Guard + Resume/Backoff — Resume ist in `WorkflowsExecutionsService` (`fromBlockId`) + Stalled-Reconciler vorhanden; Rate-Limit/Anomalie/Loop-Guard neu; Backoff-Stufen 1m/5m/15m/1h/6h/24h via `queue/producers.ts` konfigurieren.
10. M082: Klartext-Logs (BP Error-Text-Mapping + Execution-Detail als Vorlage) + Re-Run + Trigger-Volumen-Metering (neu, `MetricLog`/AI-Cost-Aggregate als Muster).
**Querschnitt parallel:** Permissions/Bundles (M004), Feature-Flag (M006), Audit-Hooks (`plugin-runtime` workflow-Hooks + `AuditEvent`), `notify()` (M011), Sidebar/Routes (INTEGRATION-CONTRACTS), Promptfoo-Eval-Gate für die spätere KI-Erstellung (`packages/ai/test/evals` als Vorlage). Templates-Registry (`DefaultWorkflowTemplates.ts`-Muster) mit SHK-Templates befüllen.
@@ -0,0 +1,193 @@
# Boilerplate-Abgleich: M18 — KI-Layer / LLM-Gateway
> Faktischer Abgleich der HiveGrid-Detail-Spec (M18) gegen die Boilerplate.
> Boilerplate-Wurzel (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
> Spec-Quelle: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M18-ki-layer.md`
> Alle Pfade absolut. Nichts erfunden — jeder Eintrag verweist auf konkrete Datei(en); fehlt etwas, ist es klar als Lücke markiert.
## Kopf
| Feld | Wert |
| --- | --- |
| Modul-ID | M18 |
| Name | KI-Layer / LLM-Gateway |
| Milestones | M083 (EU-Provider-Layer), M084 (Multi-Provider-Fallback), M085 (Promptfoo-Eval-Suite), M086 (Sprach-zu-Automation), M087 (RAG + Aktions-Grenze), M088 (Token-Limits + Pay-as-you-go) |
| Block | Block 4 — Integrationen, Automation & KI (`_bmad-output/pflichtenheft/blocks/block4.md`, Modul 18) |
| Reuse-Level | **HIGH** |
**Kernaussage:** Das ist die USP-Säule mit dem höchsten Wiederverwendungs-Grad im KI-Bereich. Die Boilerplate liefert den kompletten **EU-Provider-Layer** (Mistral/Scaleway/Aleph Alpha — exakt der von der Spec geforderte Stack, KEIN OpenAI/Anthropic im aktiven Pfad), den **30-Min-Multi-Provider-Fallback** (M084 quasi fertig), die **RAG/Embeddings-Pipeline + pgvector-Store** (M087-Retrieval), die **Promptfoo-Eval-Suite mit OWASP-Injection-Vektoren + Gitea-CI-Workflow** (M085 quasi fertig), das **Cost-/Quota-Tracking inkl. Pay-as-you-go-Overage-Logik** (M088-Engine fertig) und die **Guards/Action-Boundary-Bausteine** (M087-Aktions-Grenze). Die Hauptlücken liegen bei: **HiveGrid-spezifische Daten-Modelle** (LlmGatewayProvider/Model, AiSettings, Conversation als HiveGrid-Variante, TenantEmbedding-Tabelle), **Whisper-EU-Transkription** (komplett nicht vorhanden), die **Use-Case-Orchestrierung** (Lead-Zusammenfassung, Sprach→Automation, Stuck-Deal, Email-Klassifizierung) und das **gesamte UI** (Chat, Usage-Dashboard, Settings, Voice-Assistant).
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/ai/src/index.ts` | Provider-Adapter-Interface + Registry: `AIProviderName = "mistral"\|"scaleway"\|"aleph-alpha"`, `getAIProviderAdapter()`, `getAIProviderAdapterForModel()`, `getPrimaryProvider()`, `getAIProviderDiagnostics()`, Modell-Katalog `aiModels` (mit Preisen pro Mio Tokens), `defaultAIModel = "mistral-large-latest"` | **1:1** — exakt der von Spec Block B geforderte EU-Stack. Deckt M083 Erfolgskriterium (Mistral-Aufruf, Switch via Env-Var, keine US-Endpunkte) |
| `packages/ai/src/providers/mistral.ts` | Mistral-Provider via `@ai-sdk/mistral`, `resolveMistralModel(env)`, `MISTRAL_API_KEY`/`MISTRAL_MODEL` | **1:1** — Primary-Provider (Spec: Mistral Large Chat / Mistral Small) |
| `packages/ai/src/providers/scaleway.ts` | Scaleway-Provider (OpenAI-kompatibel), Default `mistral-small-3.2-24b-instruct-2506`, `SCALEWAY_*`-Env | **1:1** — Secondary-Provider (France-EU) |
| `packages/ai/src/providers/aleph-alpha.ts` | Aleph-Alpha-Provider (OpenAI-kompatibel), Default `pharia-1-llm-7b-control`, `ALEPH_ALPHA_*`-Env | **1:1** — Tertiary-Provider (Germany-EU) |
| `packages/ai/src/providers/compatible.ts` | `createCompatibleLanguageModel()` (gemeinsame OpenAI-kompatible Basis für Scaleway + Aleph Alpha) | **1:1** |
| `packages/ai/src/fallback.ts` | `AIProviderHealthTracker` (30-Min-Failure-Window = `fallbackWindowMs`), `getFallbackProviderSelection()`, `fallbackProviderOrder = ["mistral","scaleway","aleph-alpha"]` | **1:1 / anpassen** — deckt M084 (Auto-Fallback + 30-Min-Window) fast vollständig. Spec verlangt zusätzlich 1-Min-Health-Ping + 5-Min-Sperre (Block H / 18.6.3) — der Health-Tracker ist reaktiv (failure-on-call), nicht aktiv-pingend → **kleine Erweiterung nötig** |
| `packages/ai/src/cost/executeLLMCall.ts` | LLM-Wrapper: wrappt jeden Provider-Call, leitet Token/Kosten ab, emittiert Outbox-Event `ai.cost.event.persist`, Quota-Pre-Check + Soft-Degradation + Concurrency-Slot; Killswitch `AI_COST_TRACKING_ENABLED=false`; Capabilities `chat`/`chat-stream`/`embedding`/`completion`/`rerank`/`tool-call` | **1:1** — zentraler Gateway-Aufruf-Wrapper (Spec Block B Interface + Block F Token-Tracking) |
| `packages/ai/src/cost/assertCredit.ts` | `assertTenantAICreditAccess()` — Pre-Call-Quota-Assertion (3 Outcomes: allow / allow+degradeTo / throw `AIQuotaExceededError`), Concurrency-Counter, Soft-Degradation (90%-Threshold), per-Capability-Caps, Killswitch `AI_QUOTA_ENFORCEMENT_ENABLED=false` | **1:1 / anpassen** — M088-Kern. **WICHTIG:** Default-Verhalten ist Hard-Deny (HTTP 402) bei Limit. HiveGrid [N13] verlangt **Pay-as-you-go statt Pause** → die Hard-Deny-Pfade durch Overage-Pfad ersetzen (Overage-Logik existiert separat, s.u.) |
| `packages/entitlements/src/ai-overage.ts` | Pay-as-you-go-Overage: `AI_OVERAGE_DEFAULT_MULTIPLIER = 1.5`, `computeMarkedUpCostCents()`, `roundUpToBlock()`, `resolveTenantAIOverage()`, `standardAIOverageDefaults` pro Plan, `TenantAIOverageOverride` (parse/resolve) | **anpassen** — genau das von M088/[N13] geforderte Aufschlags-Tarif-Modell. Markup-Faktor + Block-Rundung fertig; HiveGrid-Plan-Werte + Notbremse-Threshold (18.8.7) einsetzen |
| `packages/entitlements/src/ai-quotas.ts` | `aiQuotaCapabilityKeys`, `AIQuotaPlanDefaults` (aiQuotaCentsPerMonth / aiPerCapabilityCaps / aiMaxConcurrentCalls / aiDegradeTo), `standardAIQuotaDefaults` (starter/pro/business), `resolveTenantAIQuota()`, `parseTenantAIQuotaOverride()` | **anpassen** — Inklusiv-Kontingent + per-Capability-Caps pro Plan. HiveGrid-Token/Cent-Werte einsetzen (Spec: „konkrete Mengen mit Pricing-Festlegung", noch offen) |
| `packages/ai/src/cost/spend-cache.ts` | `createSpendCache()` — Monatsspend-Caching (TTL) als Watermark für 80%-Banner und Forecast | **1:1** — Datenbasis für 80%-Soft-Limit-Banner + Email (18.8.2) und Usage-Dashboard-Forecast (18.8.9) |
| `packages/ai/src/cost/tokens.ts` | `countTokens`/`countMessageTokens` (gpt-tokenizer + Heuristik-Fallback) | **1:1** — Token-Zählung für Budget pro Use-Case (Spec C: ~2000 in / 800 out etc.) |
| `packages/ai/src/cost/pricing/v2026-05-16.ts` + `pricing/index.ts` | Versionierte Pricing-Tabelle (`getPricingTable`, `LATEST_PRICING_VERSION`) | **anpassen** — EU-Provider-Preise sind als `aiModels[].costPerM*` bereits hinterlegt; HiveGrid-Aufschlags-Tarife ergänzen |
| `packages/ai/src/guards/index.ts` | `assertAICostBudget()`, `createFixedWindowAIRateLimiter()` (pro userId), `createAIAuditEvent()`/`createAI{Prompt,ToolCall,Mutation}AuditEvent()`, `redactAIAuditPayload()` (PII-Redaction), `createReviewRequiredResult()`, `AIGuardError` | **1:1 / anpassen** — `createReviewRequiredResult()` + Mutation-Audit-Events sind das Fundament der **Action-Boundary** (M087, Spec Block G/18.5.3: KI generiert nur Vorschläge, User bestätigt). Audit-Redaction deckt AV#6 |
| `packages/ai/src/embeddings/factory.ts` + `embeddings/types.ts` | `createEmbeddingProvider()`, `registerEmbeddingProviderAdapter()`, `resolveEmbeddingProviderName(env)`, `resolveEmbeddingDimensions(env)`, `EmbeddingProvider`-Interface | **1:1** — RAG-Schreib-/Leseseite-Fundament (M087 / Spec Block D) |
| `packages/ai/src/embeddings/providers/scaleway.ts` | Scaleway-Embeddings-Adapter, Default `bge-multilingual-gemma2` (1024 dim), Batch 64, max 4096 Tokens | **1:1** — Spec Block D: „Scaleway-Embeddings, 1024-Dim Default" — exakter Match |
| `packages/ai/src/embeddings/embed-and-upsert.ts` | `embedAndUpsert()` — chunked Embed + Upsert in `VectorUpsertSink`; erzwingt `tenantId` im Payload; deterministische `buildChunkId()`; optionale Kostenverfolgung über `executeLLMCall` | **1:1 / anpassen** — Embedding-Pipeline (Spec D: bei Anlage/Update Embedding). Re-Embed-bei-Text-Änderung via Hash (Spec D) muss als Trigger-Wiring ergänzt werden |
| `packages/ai/src/embeddings/retrieve.ts` | `retrieveRelevantContext()` — Query embedden, Fan-out über Collections, Rank-Merge, min-Score 0.7, top-K 8; tenant-scoped via `RagRetrievalStore.searchForTenant` | **1:1** — RAG-Leseseite. Spec D Permission-Pre-Filter andocken |
| `packages/ai/src/embeddings/chunking.ts` | `splitForEmbedding()`, `countTokens()`, `DEFAULT_CHUNK_TOKENS`/`...OVERLAP_TOKENS` | **1:1** |
| `packages/ai/src/embeddings/outbox-publisher.ts` | `publishRagUpsertEvent`/`publishRagDeleteEvent`, `ragEventType()` → `rag.index.<entity>.<verb>` (BullMQ-Queue `outbox.rag-index`), Idempotenz via `dispatchKey` | **1:1** — async Re-Index bei jedem Domain-Write (Spec D Embedding-Pipeline) |
| `packages/vector-store/src/factory.ts` + `adapters/pgvector.ts` | `createVectorStore()` (pgvector Default / Qdrant Upgrade), `PgvectorAdapter` mit HNSW-Index (`m`/`efConstruction`), Payload-Filter | **1:1** — Spec D: „pgvector mit HNSW-Index" — exakter Match. Offener Detail-Punkt der Spec (IVFFlat vs. HNSW) ist durch BP bereits auf HNSW entschieden |
| `packages/vector-store/src/wrappers/tenant-scoped.ts` | `withTenantScope()` → `TenantScopedVectorStore`; `searchForTenant()` erzwingt `tenantId`-must-Filter; bare `searchVectors()` wirft | **1:1** — Spec D: „kein Cross-Tenant!" + M087 Permission-aware. Tenant-Isolation built-in |
| `prisma/migrations/20260517085146_04_enable_pgvector/migration.sql` | Aktiviert `pgvector`-Extension | **1:1** — Voraussetzung für TenantEmbedding-Tabelle |
| `packages/ai/src/prompts/index.ts` | `createAIPromptRegistry()` mit Versionierung, `render(selection, variables)`, `{{var}}`-Templates, `AIPromptRegistryError` | **1:1 / als-vorlage** — System-Prompt-Trennung (Spec G/18.5.2) + Use-Case-Prompts. Strikte System/User-Daten/Frage-Trennung als Template-Konvention |
| `packages/ai/src/tools/index.ts` | `createAIToolRegistry()` (scoped Tools für Vercel AI SDK `ToolSet`), `toToolSet(selection)`, Secret-Redaction | **1:1** — Tool-Calling-Architektur (Spec G: Tools nur per Tool-Call-Output, nicht aus Text geparst). Basis für Sprach→Automation-Tools (M086) |
| `packages/ai/src/streaming/index.ts` | `createAITextStream()` via `streamText`, Guard-Evaluator, Prompt-/Tool-Registry-Integration, `getAITextStreamDiagnostics()` mit Redaction | **1:1** — Streaming-Chat-UX für Programm-Hilfe-Chat (Use-Case 3). Guard-Evaluator-Seam = Action-Boundary-Andock-Punkt |
| `packages/ai/src/promptfoo-provider.ts` + `promptfoo.config.yaml` (Repo-Root) + `tests/promptfoo/injection-vectors.yaml` + `.gitea/workflows/promptfoo.yml` | Promptfoo-Eval-Harness mit OWASP-LLM-Vektoren (LLM01/LLM02/LLM06…), Mistral-als-Primary-Label, deterministischer Test-Provider, CI-Workflow | **1:1 / anpassen** — M085 quasi fertig: `description: EU-only OWASP LLM injection-vector eval suite`. Pro neuem HiveGrid-Prompt-Flow eigene Eval-Vektoren ergänzen (Spec G: „pro Prompt-Flow eigene Eval-Suite") |
| `packages/ai/test/evals/promptfoo-baseline.test.ts` + `prompt-registry-cases.yaml` | Eval-Baseline-Vitest + Prompt-Registry-Testfälle | **als-vorlage** — Muster für HiveGrid-Prompt-Flow-Evals |
| `prisma/schema/ai.prisma` → `Chat`, `ChatMessage`, `ChatMessagePart` | Chat-Datenmodell (Typ tenant/admin/marketing, Scope, anonym via `sessionId`, Multi-Part-Messages) | **als-vorlage / anpassen** — deckt Spec `Conversation`/`ConversationMessage` strukturell. `Chat.kind`/HiveGrid-`kind`-Enum (programm_help/automation_builder) ergänzen; `lastMessageAt`/`archivedAt` bereits vorhanden |
| `prisma/schema/ai.prisma` → `GeneratedObject` | Strukturierte AI-Outputs mit Token/Cost-Feldern, `status` pending/success/error, `model`, `chatId` | **1:1 / anpassen** — Spec `GeneratedObject` (JSON-Schema-validierte Outputs). `schema_version`-Feld ergänzen |
| `prisma/schema/ai.prisma` → `AICostEvent` | Append-only Cost-Log (`requestId @unique`, KEINE Prompt-Bodies, `capability`/`provider`/`model`/Tokens/Cents, `isOverage`, `markedUpCostCents`, `stripeReportedAt`) | **1:1** — Spec `AiTokenUsage` (Verbrauch pro Tenant/User/Use-Case). Overage-Felder + Stripe-Watermark für M088 bereits da |
| `prisma/schema/ai.prisma` → `TenantAICostSummary` | Vor-aggregierte Cost-Summary pro Periode (`@@unique([tenantId, periodStart])`, `breakdown` JSON) | **1:1** — Spec `AiCredits`-Aggregat + Usage-Dashboard O(1)-Top-Line (18.8.9) |
| `prisma/schema/accounts.prisma` → `Tenant` AI-Felder | `aiQuotaOverrideJson` (Json, geformt als `TenantAIQuotaOverride`), `aiCostLastAlertedThreshold`, `aiCostLastAlertedPeriod` | **1:1 / anpassen** — Spec `AiSettings.usage_limit_tokens_per_month` + idempotente 80%-Alert-State. HiveGrid-`AiSettings` braucht zusätzlich `enabled_use_cases[]`, `default_models`, `data_residency` (s. Lücken) |
| `prisma/schema/promptFlows.prisma` → `PromptFlow`, `PromptTemplate`, `PromptFlowExecution`, `PromptFlowOutput*`, `PromptFlowInputVariable` | LLM-Prompt-Pipelines an Entity/Property gekoppelt, `executionType` sequential/parallel, Streaming-Flag, Execution + Result-Log, Output→Row-Property-Mapping | **als-vorlage** — Phase-2-`PromptFlow`/`PromptTemplate` (visueller Prompt-Editor, Spec Block J) bereits strukturell vorhanden. Für Phase 1 optional als Use-Case-Prompt-Definitionen |
| `packages/queue/src/payloads.ts` → `AiJob` | Typisierte AI-Jobs: `ai.chat-completion` / `ai.embedding` / `ai.browser-task`; Queue `toolctrl.ai-chatbot` (`names.ts`) | **1:1 / anpassen** — async KI-Verarbeitung. **Whisper-Transkriptions-Job-Typ fehlt** → ergänzen (`ai.transcribe`) |
| `packages/queue/src/*` (producers/priority/connection/runtime) | `enqueueJob()`, Idempotenz (`buildIdempotentJoben`), Plan-basierte Prioritäten (`resolveJobPriorityForTenant`), BullMQ-Runtime-Factory | **1:1** — Whisper-Async-Pipeline (Spec E: Audio-Upload → Job-Queue → Whisper → Resultat) baut hierauf |
| `packages/storage/src/index.ts` + `signed/index.ts` + `scan/*` | Scaleway-S3-Adapter, Signed-Upload/Download-URLs, ClamAV + magic-bytes Virus-Scan, Quarantäne | **1:1** — Audio-Upload für Whisper-Transkription (Spec E) + DSGVO-EU-Storage |
| `packages/db/src/outbox.ts` + `prisma/schema/outbox.prisma` | `publishOutboxEvent(tx, args)` transaktional, `OutboxEvent`-Modell | **1:1** — alle KI-Side-Effects (Cost-Persist, RAG-Reindex, Notifications) transaktional |
| `prisma/schema/notifications.prisma` → `NotificationDelivery`, `UserNotificationPreference` | In-App + Email + Push Notification-Delivery | **1:1** — 80%-Budget-Email an Tenant-Admin (18.8.2), Notbremse-Warnung (18.8.7) — via `notify()` (M011), nicht direkt |
| `prisma/schema/permissions.prisma` → `Role`, `Permission`, `RolePermission`, `UserRole`, `Group` | RBAC-Fundament | **1:1** — die 6 `ai.*`-Permissions (Spec Block I) als `Permission`-Rows + Bundle-Mapping + Default-Rollen-Zuweisung |
| `prisma/schema/featureFlags.prisma` → `FeatureFlag` | Feature-Toggles (scope global/tenant/user) | **1:1** — DoD verlangt Feature-Flag-Abschaltbarkeit; `ai-quota-soft-degradation`-Flag wird von `assertCredit.ts` bereits erwartet |
| `prisma/schema/knowledgeBase.prisma` → `KnowledgeBaseArticle` etc. | Help-Center-Datenmodell | **als-vorlage** — RAG-Quelle für Programm-Hilfe-Chat (Use-Case 3) + `HelpArticleEmbedding` (M38-Kopplung) |
| `packages/search/src/*` (Meilisearch) + `schemas/kb-articles.ts` | Tenant-scoped Volltext-Index | **1:1** — Spec D Hybrid-Suche (Volltext + Embeddings) + Graceful-Degradation-Fallback bei Provider-Down (Spec D/H: „Standard-Volltext-Suche aktiv") |
---
## Vorhandene Daten-Modelle (konkret)
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
| Spec-Modell (M18 Block A) | Boilerplate-Entsprechung | Datei | Bewertung |
| --- | --- | --- | --- |
| `Conversation` | `Chat` (type tenant/admin/marketing, scope, sessionId, title, `lastMessageAt`, `archivedAt`, metadata) | `ai.prisma` | strukturell vorhanden — `kind`-Werte (programm_help/automation_builder/tenant_assistant) als HiveGrid-Anpassung |
| `ConversationMessage` | `ChatMessage` + `ChatMessagePart` (role, Multi-Part content, order) | `ai.prisma` | vorhanden — Token-Felder (`tokens_input/output`) pro Message ergänzen (aktuell auf `GeneratedObject`/`AICostEvent`-Ebene) |
| `GeneratedObject` | `GeneratedObject` (object/type/model, userPrompt/fullPrompt, generatedData JSON, Token+Cost, status, chatId) | `ai.prisma` | nahezu 1:1 — `schema_version` ergänzen |
| `AiTokenUsage` | `AICostEvent` (capability, provider, model, in/out/total Tokens, costCents, requestId @unique, isOverage, markedUpCostCents, stripeReportedAt) | `ai.prisma` | 1:1 — append-only, KEINE Prompt-Bodies (PII-konform) |
| `AiCredits` (Aggregat-Teil) | `TenantAICostSummary` (periodStart/End, totalCostCents, total Tokens, breakdown JSON) | `ai.prisma` | 1:1 für vor-aggregierte Sicht |
| `AiSettings` (Teil) | `Tenant.aiQuotaOverrideJson` + `aiCostLastAlertedThreshold/Period` | `accounts.prisma` | teilweise — Quota-Override + Alert-State da; restliche AiSettings-Felder fehlen |
| Plan-Defaults / Inklusiv-Kontingent | `standardAIQuotaDefaults` + `AIQuotaPlanDefaults` (Code, kein DB-Modell) | `packages/entitlements/src/ai-quotas.ts` | 1:1 (Code-Registry-Stil) |
| Overage-/Aufschlags-Tarif | `standardAIOverageDefaults` + `resolveTenantAIOverage` (Code) | `packages/entitlements/src/ai-overage.ts` | 1:1 (Code-Registry-Stil) |
| `PromptFlow`/`PromptTemplate` (Phase 2) | `PromptFlow`, `PromptTemplate`, `PromptFlowExecution`, `PromptFlowOutput(+Mapping)`, `PromptFlowInputVariable`, `PromptFlowGroup(+Template+Entity)` | `promptFlows.prisma` | 12 Modelle bereits vorhanden (visueller Prompt-Editor Phase 2) |
**Provider-Registry als Code, nicht als DB:** Die Spec modelliert `LlmGatewayProvider` / `LlmGatewayModel` als „Plattform-weit, Code-Registry". Die Boilerplate setzt das **genau so** um: `providerMetadata` + `aiModels`-Katalog in `packages/ai/src/index.ts` (mit `costPerMInputTokens`/`costPerMOutputTokens`/`maxOutputTokens` pro Modell). Es gibt **keine** Prisma-Modelle `LlmGatewayProvider`/`LlmGatewayModel` — das ist konform mit der Spec (Code-Registry) und kein Defizit.
---
## Lücken / komplett neu zu bauen
### Daten-Layer (in `prisma/schema/app.prisma` — leerer HiveGrid-Platzhalter)
1. **`AiSettings` (HiveGrid-spezifisch)** — kein Modell vorhanden. Benötigt: `enabled_use_cases[]`, `default_models` (Use-Case→Modell-Key JSON), `data_residency` (Default `eu`, Hard-Constraint). Teilweise durch `Tenant.aiQuotaOverrideJson` gedeckt; HiveGrid-Settings-Modell neu.
2. **`TenantEmbedding`-Tabelle** — als Prisma-Modell **nicht vorhanden**. Die Boilerplate legt Vektoren über pgvector in `vec_<namespace>_<collection>`-Tabellen per Raw-SQL an (kein Prisma-Modell). Spec verlangt zusätzlich Metadaten-Tracking (`entity_type`, `entity_id`, `text_source` für Re-Embed-Hash, `embedding_model_id`, `last_embedded_at`) — **Metadaten-Begleittabelle neu bauen** (die Vektoren selbst kommen aus dem vorhandenen pgvector-Adapter).
3. **`HelpArticleEmbedding`** (M38-Kopplung) — nicht vorhanden; analog zu TenantEmbedding über pgvector + Begleit-Metadaten.
4. **Conversation-`kind`-Enum** + **per-Message-Token-Felder** — kleine Schema-Erweiterung an `Chat`/`ChatMessage`.
5. **Whisper-Transkriptions-Modell** (Job-Status, Audio-Ref, Transkript, Sprache, Edit-State) — komplett neu.
### Whisper-EU-Transkription (Spec Block E) — KOMPLETT FEHLT
- **Kein** Transcription-Adapter, **keine** `transcribe()`-Methode in `packages/ai`, **kein** Audio/Whisper-Code (grep über `packages/ai/src` ergab 0 Treffer für transcri/whisper/audio/speech).
- Queue-Payload `AiJob` kennt nur `ai.chat-completion`/`ai.embedding`/`ai.browser-task` — **`ai.transcribe` fehlt**.
- Neu zu bauen: Whisper-auf-Scaleway-GPU-Adapter (DSGVO-konform), Async-Pipeline (Storage-Upload → Queue → Whisper → Resultat — Bausteine `storage` + `queue` vorhanden), Auto-Sprache-Erkennung (DE/EN), Mikrofon-Aufnahme-UI, Edit-Funktion, Klartext-Fehler.
### Use-Case-Orchestrierung (Spec Block C) — Gateway-Bausteine da, Use-Cases neu
- **Lead-Zusammenfassung / Pre-Termin-Brief** (Use-Case 2): Activity-Stream + Custom-Felder + Form-Submissions als Kontext sammeln, Cache-Hit-Logik (gleiche Datenbasis), Widget im Kontakt-Detail. Neu.
- **Programm-Hilfe-Chat** (Use-Case 3): RAG über Help-Articles + Conversation-Historie. Streaming-Chat-Baustein vorhanden, Orchestrierung + UI neu.
- **Klartext-Diagnostik-Fallback** (Use-Case 4): KI nur Fallback bei unbekannten Fehler-Codes, klar markiert. Neu.
- **Stuck-Deal-Vorschläge** (Use-Case 5): wöchentlicher Cron-Job, Widget. Neu (Cron via M-Infra).
- **Email-Klassifizierung** (Use-Case 7): `lead|customer_question|invoice|spam|newsletter|other`, Inbox-Auto-Verknüpfung (M9). Neu.
- **Sprach-zu-Automation (M086, USP-Hauptstütze)**: Sprach-Befehl → Wenn-Dann-Vorschlag im visuellen Editor, Rückfrage bei Mehrdeutigkeit, Existenz-Probe referenzierter Pipelines/Mitarbeiter/Templates, Risiko-Warnungen, „Vorher/Nachher"-Diff, NIE Auto-Aktivierung. Tool-Registry + Streaming + Prompt-Registry als Fundament; die gesamte Orchestrierung + Editor-Integration (M078) + Voice-Input (Web-Speech-API) neu.
### Sicherheits-Layer (Spec Block G) — teilweise
- **Input-Sanitization (Runtime)**: **FEHLT** als Modul. Die Boilerplate hat Promptfoo-**Test**-Vektoren (`tests/promptfoo/injection-vectors.yaml`, deterministischer Test-Provider), aber **keine produktive Sanitizer-Funktion**, die Marker (`---SYSTEM:`, `[INST]`, `<|im_start|>`) in externen Daten neutralisiert oder Eingabe-Länge cappt (grep ergab 0 Runtime-Treffer). Neu bauen.
- **System-Prompt-Trennung**: Prompt-Registry (`{{var}}`-Templates) ist da; strikte 3-Block-Trennung (System / User-Daten „nicht als Anweisung" / Frage) als Konvention/Template neu definieren.
- **Action-Boundary (M087)**: Bausteine vorhanden (`createReviewRequiredResult()`, Mutation-Audit-Events, Streaming-Guard-Evaluator) — die **Bestätigungs-Workflow-Verdrahtung im UI** + Tool-Output-only-Policy neu.
### Multi-Provider-Fallback (M084) — fast fertig, 2 Lücken
- Aktiver **1-Min-Health-Ping** + **5-Min-Sperre** (Spec 18.6.3): vorhandener `AIProviderHealthTracker` ist reaktiv (failure-on-call, 30-Min-Window). Aktives Pingen + 5-Min-Re-Check-Fenster ergänzen.
- **Deterministischer Response-Cache** (Spec H/18.7: Cache-Hit auch bei KI-Down): **nicht vorhanden** — es gibt `spend-cache` (Kosten), aber keinen Output-Cache für deterministische Prompts. Neu (Hash-basiert).
### Pay-as-you-go (M088) — Engine da, Verdrahtung + Notbremse neu
- Overage-Berechnung (`ai-overage.ts`) + Cost-Felder (`AICostEvent.markedUpCostCents`/`stripeReportedAt`) fertig.
- **Umstellung Hard-Deny → Overage**: `assertCredit.ts` wirft aktuell bei Limit (HTTP 402). [N13] verlangt **weiterlaufen + Aufschlag**. Pfad umbauen.
- **Notbremse** (18.8.7): absolute Euro-Obergrenze pro Tenant → Drosselungs-Modus (nur geschäftskritische KI). Neu (Threshold + Capability-Whitelist).
- **Stripe-Metered-Billing-Reporter** (18.8.6): `stripeReportedAt`-Watermark + nightly Cron vorgesehen; Stripe-Anbindung kommt aus M153/M156. Verdrahtung neu.
- **Upsell-Logik** (18.8.5): Vergleich Overage-Kosten vs. Plan-Differenz → Soft-Recommendation. Neu.
### UI — KOMPLETT NEU (Boilerplate liefert KEIN HiveGrid-UI)
- Programm-Hilfe-Chat-Oberfläche (Streaming)
- KI-Sprach-Assistent (M086, Sidebar-Gruppe „AUTOMATION & KI" → laut INTEGRATION-CONTRACTS §1)
- Usage-Dashboard `/{tenant}/admin/usage/ai` (Pie pro Use-Case, Verbrauch über Zeit, Top-User, Forecast, Tarif, Notbremse-Stand)
- AI-Settings-Seite (EU-DSGVO-Klartext, Modell-Defaults pro Use-Case, Token-Override) — Sidebar „EINSTELLUNGEN → Mandant"
- Voice-Aufnahme-Komponente (Mikrofon-Tap/Toggle, Edit, Klartext-Fehler)
- Lead-Zusammenfassungs-Widget, Stuck-Deal-Widget
- Action-Boundary-Bestätigungs-Dialog
- **DoD-Pflicht** (alle Milestones): View-Model-Loader-Trennung, keine Prisma-Imports in `packages/ui-hivegrid/**`, Subframe-Adapter, i18n-Keys, Smoke-Tests, Hot-Swap-Drill gegen `packages/ui-mock`, Visual-Regression — alles HiveGrid-seitig neu.
### Querschnitt-Wiring (HiveGrid-seitig)
- Sidebar-Registrierung in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (M086 → Gruppe „AUTOMATION & KI"; Usage/Settings → „EINSTELLUNGEN")
- Routes unter Tenant-URL-Pattern, Breadcrumbs, Customer-Portal-Sichtbarkeit
- i18n-Keys für alle Klartext-Fehler (Spec 18.12 — 5 konkrete Beispiele) aus M002-Catalog
- Activity-Stream (`logActivity`) + Notifications (`notify()`) Anbindung
- Permission-Seed der 6 `ai.*`-Permissions + 3 Bundles + Default-Rollen-Zuweisung
- Feature-Flag pro KI-Modul
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Voraussetzung (vor M083):** EU-Sterilisation der Boilerplate prüfen. Der aktive Provider-Pfad ist bereits EU-only (Mistral/Scaleway/Aleph Alpha); **Anthropic/OpenAI existieren nur als Embedding-Stub bzw. `@ai-sdk/openai-compatible`-Bibliothek** (`packages/ai/src/embeddings/providers/{openai,anthropic}.ts`). Sicherstellen, dass diese nicht aktiviert/registriert werden (DSGVO-Hard-Constraint, Spec 18.2.2).
**M083 (EU-Provider-Layer) — überwiegend ÜBERNEHMEN:**
1. `packages/ai` Provider-Registry + Mistral/Scaleway/Aleph-Alpha-Adapter 1:1 nutzen.
2. `executeLLMCall` als zentralen Gateway-Wrapper verdrahten (Boundary in apps/api injiziert Env-Snapshots + Cost-Publisher + Prisma-Adapter).
3. EU-DSGVO-Klartext in AiSettings (Spec 18.2.4) als i18n-Key.
**M084 (Fallback) — ÜBERNEHMEN + 2 Erweiterungen:**
1. `fallback.ts` (30-Min-Window, Mistral→Scaleway→Aleph-Alpha) 1:1.
2. NEU: aktiver 1-Min-Health-Ping + 5-Min-Sperre.
3. NEU: deterministischer Output-Cache (Hash-basiert, Cache-Hit bei KI-Down).
4. Graceful-Degradation-Klartexte + Editor-Fallback-Hinweis (UI).
**M085 (Promptfoo) — fast fertig ÜBERNEHMEN:**
1. `promptfoo.config.yaml` + `tests/promptfoo/injection-vectors.yaml` + `.gitea/workflows/promptfoo.yml` 1:1.
2. NEU: pro HiveGrid-Prompt-Flow eigene Eval-Vektoren ergänzen; CI-Gate verifizieren.
**M087 (RAG + Aktions-Grenze) — Bausteine ÜBERNEHMEN, Wiring neu:**
1. pgvector-Migration aktivieren; `vector-store` tenant-scoped + `embeddings`-Pipeline 1:1.
2. NEU: `TenantEmbedding`-Metadaten-Modell in `app.prisma` (Re-Embed-Hash, embedding_model_id, last_embedded_at).
3. NEU: Permission-Pre-Filter vor Vector-Search (Spec 18.3.3).
4. NEU: Embedding-Trigger bei Entity-Anlage/Update (Outbox `rag.index.*` vorhanden — Domain-Writes andocken).
5. Action-Boundary: `createReviewRequiredResult()` + Mutation-Audit + UI-Bestätigungs-Dialog.
6. NEU: Runtime-Input-Sanitizer (Marker-Neutralisierung + Längen-Cap).
**M086 (Sprach-zu-Automation, USP) — meiste Eigenleistung:**
1. Tool-Registry + Streaming + Prompt-Registry als Fundament.
2. NEU: Sprach→Wenn-Dann-Orchestrierung, Existenz-Probe, Rückfrage-Loop, Risiko-Warnung, Vorher/Nachher-Diff, Voice-Input (Web-Speech-API), Editor-Integration (M078). NIE Auto-Aktivierung.
3. Abhängig von M087 (Aktions-Grenze) + M075-M077 (Automation-Schema).
**M088 (Token-Limits + Pay-as-you-go) — Engine ÜBERNEHMEN, Policy umbauen:**
1. `ai-quotas.ts` + `ai-overage.ts` + `AICostEvent`/`TenantAICostSummary` 1:1 (HiveGrid-Plan-Werte einsetzen, sobald Pricing fixiert).
2. UMBAU: `assertCredit.ts` Hard-Deny → Pay-as-you-go-Overage-Pfad ([N13]).
3. NEU: Notbremse (absolute Euro-Obergrenze → Drosselung statt Pause), Upsell-Logik, 80%-Banner+Email, Usage-Dashboard.
4. Stripe-Metered-Reporter andocken (M153/M156).
**Whisper-EU (Spec Block E) — separater Neubau-Strang (parallel/danach):**
1. NEU: Whisper-auf-Scaleway-GPU-Adapter + `transcribe()`-Methode in `packages/ai`.
2. NEU: `ai.transcribe`-Queue-Job + Async-Pipeline (storage + queue vorhanden).
3. NEU: Voice-Aufnahme-UI + Edit + Klartext-Fehler.
**Querschnitt zum Schluss jedes Milestones (DoD):** Sidebar-Wiring, Routes/Breadcrumbs, Permission-Seed (6 `ai.*` + Bundles + Default-Rollen), i18n-Klartexte (18.12), Activity/Notifications, Feature-Flags, View-Model-Loader-Trennung, Smoke- + Hot-Swap- + Visual-Regression-Tests.
@@ -0,0 +1,142 @@
# Boilerplate-Abgleich: M19 — KWP-Integration
| Feld | Wert |
|---|---|
| **Modul-ID** | M19 |
| **Name** | KWP-Integration |
| **Milestones** | M089 (Sync-Programm), M090 (Heartbeat+Recovery), M091 (Warteschlange+Replay), M092 (Schema-Drift-Sentinel), M093 (Konflikt-Auflösung „KWP gewinnt"), M094 (Plantafel-Sync), M095 (Dokumenten-Archiv-Sync) |
| **Block** | Block 4 — USP-Säulen (Modul 19), sitzt auf M33a Apps-Engine (M008-M010) |
| **Reuse-Level** | **medium** |
> **Verifikations-Basis:** Eigene Greps/Reads direkt in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (nicht nur Inventur). Wo Inventur und Realität abweichen, ist das markiert.
---
## Kernbefund in einem Satz
Die Boilerplate hat **kein KWP-, MSSQL-, Heartbeat-, Schema-Drift- oder Windows-Sync-Code** (grep über `*.ts`/`*.prisma` leer außer einem Test-Match in `packages/cli`). Was sie liefert, ist ein **solides Querschnitt-Fundament**: ein generisches Data-Sync-Datenmodell (`appsEngine.prisma`), eine Public-API-Runtime mit Tenant-API-Key/Webhook-Auth (`apps/api`), eine Cron+Queue-Worker-Runtime mit Transactional-Outbox (`apps/worker`), gehashte API-Keys (`core.prisma`), Idempotenz, Storage/Signed-URLs und Notifications. Die **gesamte KWP-Fachlogik** (Queue-Semantik, Mapping-Registry, Drift-Diff, Konflikt-Default „KWP gewinnt", Projektnummern-Sequenz/Reservierung) ist **neu zu bauen**.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/appsEngine.prisma` | `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` — generische Data-Sync-Engine mit Status/Mode/Metriken + Source→Destination-Mapping + Rollback-Daten | **anpassen** — deckt `KwpSettings` (als `App`/`DataConnection`), `KwpProjectQueue`/Sync-Lauf (als `AppSyncRun`) und `KwpRegistry` (als `AppSyncItem`) teilweise ab; KWP-spezifische Felder fehlen (s.u.) |
| `prisma/schema/core.prisma` → `ApiKey` + `ApiKeyLog` | Gehashte Keys (`keyHash`/`keyPrefix`/`keyLastFour`/`keyVersion`/`hashedAt`/`expires`/`active`), `@@unique([tenantId, alias])`, Request-Logging | **1:1** für `KwpApiKey` (Token-Auth des kwpsync.exe bzw. KWP-API). Rotation/Expiry-Felder vorhanden |
| `prisma/schema/core.prisma` → `IdempotencyKey` | `@@unique([scope, key])`, Response-Caching, `expiresAt` | **1:1** für die in der Spec geforderte `idempotency_key`-Doppel-Push-Erkennung (Block D) |
| `prisma/schema/core.prisma` → `FileObject` (+ `FileUploadProgress`/`FileChunk`) | Storage-Metadaten (provider/bucket/key/checksum/byteSize/metadata Json) | **anpassen** — Basis für `KwpDocument`/Dokumenten-Archiv-Sync (M095); KWP-Herkunfts-Felder (`direction`, `kwp_path`, gelöscht-Badge) ergänzen |
| `apps/api` (`@toolctrl/api`, Hono) + `apps/api/src/route-access-inventory.ts` | Public-API-Runtime mit Auth-Klassen `tenant-api-key`, `service-token`, `webhook-signature`, `optional-api-key-validation`; `apps/api/src/auth.ts` (`extractApiKeyFromRequest`, `extractBearerToken`, `createServicePrincipal`); Error-Envelope + Request-ID | **als-vorlage / anpassen** — exakt die Ingress-Schicht für `/api/v1/integrations/kwp/queue/{token}/...` (Pull/Push/Heartbeat). Neue Routes + Auth-Klasse für den kwpsync-Token andocken |
| `apps/api/src/webhooks/mailersend-signature.ts`, `billing/stripe-webhook-route.ts`, `email-sequences/provider-webhook-route.ts` | Bestehende inbound-Webhook-Handler mit Signatur-Verifikation | **als-vorlage** — Muster für `handleWebhook` (kwpsync.exe pusht Delta + Heartbeat) bzw. KWP-API-Webhook |
| `apps/worker` (`@toolctrl/worker`) + `apps/worker/src/jobs/*-cron.ts` | Cron+Queue-Runtime, single-instance Cron-Scheduler (Bsp. `dsgvo-grace-cron.ts` 24h, `plugin-audit-retention` nächtlich), DI-`HandlerDependencies`, Health/Admin-Server | **als-vorlage** — für Daily-Schema-Drift-Check (M092), Heartbeat-Watchdog (M090), Rate-Limited-Replay-Worker (M091). Neuen Queue-Namen + Handler registrieren |
| `apps/worker/src/outbox/{dispatcher,event-router}.ts` + `prisma/schema/outbox.prisma` | Transactional-Outbox: Event in DB-Tx committen, Worker fan-out per Prefix-Routing (longest-prefix-wins), Exponential-Backoff-Retry, DLQ | **anpassen** — Push aus HiveGrid → KWP-Queue als Outbox-Event (`kwp.push.*` Prefix-Routing ergänzen). Garantiert „nichts geht verloren" (Spec 19.3.3) ohne eigene Queue-Mechanik |
| `packages/queue` (`@toolctrl/queue`) | BullMQ-Wrapper: `enqueueJob`, `buildIdempotentJobId()`, plan-basierte Prioritäten (`resolveJobPriorityForTenant`), Idempotenz | **1:1 / anpassen** — Cloud-Queue-Verarbeitung + Idempotenz. Neuer Queue-Name `toolctrl.kwp-sync` o.ä. hinzufügen (Queue-Namen sind hartcodiert in `packages/queue/src/names.ts`) |
| `packages/foundation/src/adapters.ts` | `defineAdapter()`/`getAdapter()` + `AdapterStatus = not_configured\|configured\|healthy\|degraded\|unavailable` | **anpassen** — die 5 Status-Werte mappen direkt auf die M33a-/Spec-Status (`wartet auf Setup`/`aktiv`/`eingeschränkt`/`defekt`/`getrennt`). **ACHTUNG:** das ist nur eine 18-Zeilen-Status-Registry, **kein** Sync-Connector-Framework — siehe „Lücken" |
| `packages/storage` (`@toolctrl/storage`) | S3/Scaleway-Adapter, Signed-Upload/Download-URLs, Virus-Scan (ClamAV + magic-bytes), Quarantäne | **1:1** für Dokumenten-Archiv-Sync (M095) — KWP-Dokumente in Scaleway-S3 ablegen, Signed-URLs zum Lesen/Download |
| `packages/marketing-outbound/src/types.ts` → `adapterFetch()` + SSRF-Guard | Timeout + SSRF-Allowlist (nur HTTPS, kein RFC1918/metadata) für ausgehende HTTP-Calls | **als-vorlage** — falls die KWP-API direkt von HiveGrid Cloud aufgerufen wird (API-Variante, s.u.), als sicherer HTTP-Egress |
| `packages/realtime` (`@toolctrl/realtime`) | SSE-Event-Serialisierung (`notification.snapshot/update`) | **1:1** für sichtbaren Re-Sync-Fortschritt („847/1.230 abgearbeitet") und Live-Status-Indicator |
| `packages/db/generated/prisma/client/models/{App,DataConnection,AppSyncRun,AppSyncRunLog,AppSyncItem}.ts` | Generierter Prisma-Client für die Apps-Engine-Modelle (bereits vorhanden) | **1:1** — Modelle sind generiert und tenant-relation-verdrahtet; sofort nutzbar |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
Direkt für M19 relevante, **bereits existierende** Prisma-Modelle:
- `prisma/schema/appsEngine.prisma`
- `App` (`tenantId`, `type`-Identifier, `config` JSON-String, `isActive`, `installedByUserId`, `@@unique([tenantId, type])`) → Basis für „KWP-App ist installiert" + `KwpSettings.enabled_features`
- `DataConnection` (`tenantId`, `name` (sprechender Name „Geerkens Hauptbüro KWP"), `type` z.B. "rest-api"/"webhook", `config` = **verschlüsselte** JSON-Credentials) → Basis für `KwpSettings`/`data_connection_id`
- `AppSyncRun` (`status` pending/running/completed/partial/failed/cancelled/**reverted**, `executionMode` manual/scheduled/webhook, `itemsProcessed/Created/Updated/Failed`, `startedAt/completedAt`, `error`, `metadata` JSON) → Basis für Sync-Lauf-Historie + M33a-Sync-Verlauf
- `AppSyncRunLog` (`type` info/success/warning/error, `message`, `metadata`) → Klartext-Log pro Sync-Vorgang (M33a.4.2)
- `AppSyncItem` (`objectType`, `sourceId`, `destinationId`, `action`, `sourceData`/`destinationData` JSON, `status`, **`rolledBackData`/`rolledBackAt`**, `@@index([objectType, sourceId])`) → Basis für `KwpRegistry`-Mapping + Konflikt-Restore (M093)
- `prisma/schema/core.prisma`
- `ApiKey` + `ApiKeyLog` → `KwpApiKey` (gehasht, Rotation, Request-Logging)
- `IdempotencyKey` → Idempotenz-Schlüssel der Push-Operationen
- `FileObject` / `FileUploadProgress` / `FileChunk` → KwpDocument-Storage-Metadaten
- `Credential` (globaler Secret-Store, `value Json`) → falls Cloud-seitige Secrets nötig
- `prisma/schema/featureFlags.prisma` → `FeatureFlag`/`FeatureFlagFilter`/`FeatureFlagAudit` (DoD-Pflicht „Modul ohne Deploy abschaltbar")
- `prisma/schema/permissions.prisma` → `Role`/`Permission`/`RolePermission`/`UserRole` (generisches RBAC; die 6 `kwp.*`-Permissions sind hier zu **registrieren**, nicht neu zu erfinden)
- `prisma/schema/notifications.prisma` → `NotificationDelivery`/`UserNotificationPreference`/`DeviceToken` (Push/Email-Alerts bei broken/drift)
- `prisma/schema/outbox.prisma` → `OutboxEvent` (Transactional-Push-Queue)
- `prisma/schema/workflows.prisma` → `Workflow`/`WorkflowExecution`/… (M17-Engine; KWP-Trigger `kwp.auftrag_pulled`/`kwp.push_auftrag` und KWP-Actions docken hier an, **nicht** in M19 selbst neu bauen)
---
## Lücken / komplett neu zu bauen
**Es existiert KEIN KWP-spezifischer Code.** grep über das gesamte Boilerplate-Repo (`kwp|KWP|mssql|MSSQL|heartbeat|schema.drift|nssm|sqlserver`) liefert nur einen einzigen Treffer in `packages/cli/.../doctor.test.ts` (unbezogen). Konkret fehlt:
1. **Der komplette `kwpsync.exe` Windows-Client** (Block F). Nichts davon ist in der Boilerplate — kein .NET-/Go-Projekt, kein MSSQL-Treiber, kein NSSM-Wrapper, keine lokale SQLite-Queue, kein DPAPI-Verschlüsselungs-Code, kein Auto-Update. Das ist ein **eigenständiges externes Programm außerhalb des Monorepos** (M089). **(Bei API-Variante entfällt das ganz — siehe KWP-API-Auswirkung.)**
2. **`defineAdapter` ist NICHT das Apps-Engine-Connector-Pattern.** Die AGENTS.md-Tabelle (Zeile 134: „Apps-Engine-Adapter | M008-M010 | `defineAdapter()`") suggeriert ein fertiges Adapter-Framework. Realität: `packages/foundation/src/adapters.ts` ist eine **18-Zeilen-Status-Registry** (`Map` mit key→status). Das in Spec Block I geforderte Adapter-Interface (`connect`/`disconnect`/`validateConnection`/`syncPull`/`syncPush`/`handleWebhook` + Capabilities) **existiert nicht** und muss als Teil von M008-M010 (M33a) erst gebaut werden. M19 setzt darauf auf — ist also von M008-M010 blockiert (Vorbedingung steht korrekt in M089).
3. **KWP-spezifische Datenmodelle**, die `appsEngine.prisma` nicht abdeckt:
- `KwpProjectNumberSequence` (pro Jahr fortlaufende Auftragsnummern „2026-0042") — **komplett neu**, kein Sequenz-Modell vorhanden
- `KwpProjectNumberReservation` (24h-Reservierung mit `expires_at`/`consumed_at`) — **komplett neu**
- `KwpSchemaSnapshot` (`schema_hash`, `tables_metadata` JSON für Diff) — **komplett neu**
- `KwpErrorReport` (`error_kind` schema_drift/connection_lost/sync_conflict/…, `severity`, `summary_text`/`tech_details`, `acknowledged_by`) — teilweise via `AppSyncRunLog`, aber Tenant-Acknowledge-Flow + Severity-Filter fehlen → **neu**
- `KwpSettings`-Spezialfelder: `kwpsync_token`, `kwpsync_version`, `kwpsync_last_heartbeat_at`, `polling_interval_seconds` — als `App.config`/`DataConnection.config`-JSON ablegbar oder eigene Felder → **anpassen/ergänzen**
4. **Sync-Mechanik-Fachlogik** (Block D/G/H): Cursor-basierter Delta-Pull, Rate-Limited-Replay (max 100 Ops/Min mit Fortschritt), **Konflikt-Default „KWP gewinnt immer"** (M093, [N14]) inkl. HiveGrid-eigene-Felder-Schutz, Optimistic-Locking mit `version_hash`, Last-Known-Stand-Restore. `AppSyncRun`/`AppSyncItem` liefern die **Tabellen-Hülle**, aber keinerlei dieser Algorithmen.
5. **Schema-Drift-Sentinel-Fachlogik** (M092): Snapshot-Algorithmus, Hash-Vergleich, Auto-Pause, Plattform-Admin-zuerst-Benachrichtigung, Diff-Tool im Plattform-Admin (M37). Cron-Hülle vorhanden, Logik neu.
6. **Setup-Wizard-UI + alle Routes/View-Models/i18n** (Block C). Keine `app/routes`-Integration, keine `ui-hivegrid`-Components, kein Sidebar-Eintrag „KWP-Verbindung" (in INTEGRATION-CONTRACTS §1 unter Einstellungen vorgesehen → M089-M095, aber Code existiert nicht). Subframe-Design + Adapter-Layer komplett neu.
7. **Permissions registrieren:** `kwp.read/connect/manage/manual_sync/disconnect/admin` sind in `packages/entitlements/src/permissions.ts` (HiveGrid-Seite) noch zu definieren; RBAC-Tabellen existieren generisch.
8. **Plantafel-Sync (M094)** und **Dokumenten-Archiv-Sync (M095)** Fachlogik — Storage-/File-Modelle vorhanden, Spiegelungs-Logik (Kunden-Archiv vs. Projekt-Archiv, einseitig, „in KWP gelöscht"-Badge) neu.
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Voraussetzung außerhalb M19:** Erst M008-M010 (M33a Apps-Engine) bauen — das echte Adapter-Interface (`connect/syncPull/syncPush/handleWebhook` + Status + Setup-Wizard-Shell). M19 ist davon hart abhängig; `defineAdapter` reicht NICHT.
1. **Daten-Layer aus Boilerplate übernehmen + KWP-Felder ergänzen:** `appsEngine.prisma`-Modelle als Basis nehmen (`App`/`DataConnection`/`AppSyncRun`/`AppSyncItem`), `ApiKey`+`IdempotencyKey` 1:1 nutzen. Neue Modelle in eigenem `prisma/schema/kwp.prisma`: `KwpProjectNumberSequence`, `KwpProjectNumberReservation`, `KwpSchemaSnapshot`, `KwpErrorReport`. Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD F.28).
2. **Querschnitt 1:1 verdrahten, nicht nachbauen:** Token-Auth via `ApiKey`, Idempotenz via `IdempotencyKey`+`buildIdempotentJobId`, Push-Queue via Outbox (`kwp.push.*`-Prefix in `event-router.ts`), Notifications via `notify()` (M011), Storage via `@toolctrl/storage`, Status-5-Werte via `foundation/adapters` `AdapterStatus`, Feature-Flag via `FeatureFlag`.
3. **Ingress-Schicht aus `apps/api` ableiten:** KWP-Queue/Heartbeat/Pull-Endpoints unter `/api/v1/integrations/kwp/...`, Auth-Klasse `tenant-api-key` aus `route-access-inventory.ts`, Webhook-Handler nach Vorbild `mailersend-signature.ts`.
4. **Worker-Crons aus `apps/worker` ableiten:** Heartbeat-Watchdog (M090), Daily-Schema-Drift (M092), Rate-Limited-Replay (M091) — nach Muster `dsgvo-grace-cron.ts`; neuen Queue-Namen in `packages/queue/src/names.ts` registrieren.
5. **KWP-Fachlogik neu bauen (Kern-Aufwand):** Mapping-Registry-Semantik auf `AppSyncItem`, Konflikt-Default „KWP gewinnt" (M093) inkl. Restore aus `rolledBackData`, Projektnummern-Sequenz/Reservierung, Schema-Snapshot-Diff. Reine Domain-Funktionen in `app/domain/**` (AGENTS.md Layer-Trennung).
6. **UI komplett neu (Subframe → Adapter → Routes):** Setup-Wizard, Status-Dashboard, Sync-Verlauf, Fehlerbericht-Liste, Konflikt-Diff-View. Sidebar-Eintrag „KWP-Verbindung" (Einstellungen-Gruppe), Breadcrumbs, i18n, Smoke-Tests, Visual-Regression — alle DoD-Punkte.
7. **kwpsync.exe als separates Repo/Artefakt** (M089) — nur in der **Sync-Programm-Variante** nötig (siehe nächster Abschnitt).
---
## KWP-API-Auswirkung (Pflicht-Abschnitt — Stand 2026-06-04, NEU/WICHTIG)
> **Kontext:** KWP bekommt jetzt eine **offizielle API-Anbindung**. Der bisherige Plan (lokaler Windows-Service + NSSM + persistente lokale SQLite-Queue + Schema-Drift-Sentinel, M089-M095) war für **KWP OHNE API** konzipiert. Die Spec selbst hat das antizipiert (19.11.2: „Native KWP-API … würde die Architektur stark vereinfachen"). Mit API wird aus der Drei-Komponenten-Architektur eine **Zwei-Komponenten-Architektur** (HiveGrid Cloud ↔ KWP-API direkt), der „Kunde-vor-Ort"-Mittelteil entfällt.
### (1) Was die API-Anbindung am Architektur-Plan ändert
- **`kwpsync.exe` entfällt als Mittelschicht.** Statt Cloud → kwpsync.exe (Poll) → MSSQL wird es Cloud → HTTPS → KWP-API. Damit fallen weg: MSSQL-Direktzugriff, DPAPI-Config, lokale SQLite-Queue, NSSM-Service-Wrapper, Auto-Update-Mechanismus, Code-Signing.
- **Aus „windows_client" wird ein Standard-Connection-Type.** Die Spec Block I nennt `connection_type = windows_client` als KWP-Spezialfall. Mit API wird daraus ein **regulärer `rest-api`/`oauth2`-Adapter** — exakt das, was `DataConnection.type` in `appsEngine.prisma` ohnehin als Werte vorsieht ("rest-api", "oauth2", "webhook"). **Damit passt KWP plötzlich nahtlos ins generische Apps-Engine-Muster** statt Sonder-Pattern zu sein.
- **Egress statt Ingress:** Statt dass kwpsync.exe in die Cloud pollt, ruft die HiveGrid Cloud die KWP-API aktiv auf. Dafür ist `packages/marketing-outbound/src/types.ts` → `adapterFetch()` (HTTPS-only, SSRF-Allowlist, Timeout) die passende sichere HTTP-Egress-Vorlage. Pull wird zu einem normalen Cron-Job (`apps/worker`), Push zu einem Outbox-getriebenen API-Call.
- **DSGVO-Punkt verschiebt sich:** Spec 19.1.2 („KWP-Zugangsdaten liegen lokal beim Kunden, niemals in der Cloud") gilt bei API-Anbindung nicht mehr 1:1 — API-Credentials liegen verschlüsselt in `DataConnection.config` in der Cloud. Das ist DSGVO-konform (Plattform-Schlüssel, Pflichtenheft 33a.9.3), **erfordert aber eine bewusste Neubewertung** des „rohe DB-Zugriffe verlassen das Netzwerk nie"-Versprechens.
### (2) Welche Milestones M089-M095 sich vereinfachen oder entfallen
| Milestone | Mit Windows-Sync (alt) | Mit KWP-API (neu) | Verdict |
|---|---|---|---|
| **M089** kwpsync.exe (Win-Service+NSSM) | komplettes externes .NET/Go-Programm | — | **ENTFÄLLT** (ggf. Restaufwand: API-Connector-Adapter statt Programm, aber innerhalb des Monorepos) |
| **M090** Heartbeat + Auto-Recovery | 5-Min-Heartbeat des Clients, 15-Min-Watchdog, Auto-Restart | API-`validateConnection` = einfacher Health-Probe-Call (Spec/M33a haben das ohnehin: aktiv=5min/eingeschränkt=1min/defekt=15min) | **STARK VEREINFACHT** → reduziert auf den generischen M33a-Connection-Health-Check; kein Client-Recovery mehr |
| **M091** Persistente Warteschlange + Replay | **zwei** Queues (Cloud + lokale SQLite), Rate-Limited-Replay nach Outage | nur **eine** Cloud-Queue (Outbox) + Rate-Limit-Replay bei KWP-API-Down | **VEREINFACHT** → lokale SQLite-Queue entfällt komplett; Outbox + `packages/queue` decken den Rest ab |
| **M092** Schema-Drift-Sentinel | Daily-MSSQL-Schema-Snapshot via Client | **abhängig von API-Vertrag:** versionierte API → Drift wird zu **API-Versions-/Contract-Check** (deutlich leichter); KWP ändert MSSQL nicht mehr „still" hinter dem Rücken | **VEREINFACHT bis ggf. ENTFÄLLT** (bei stabiler versionierter API). Bleibt sinnvoll als API-Response-Schema-Validierung (zod) |
| **M093** Konflikt „KWP gewinnt" | unverändert relevant (fachliche Regel, nicht transport-abhängig) | unverändert relevant | **BLEIBT** (Domain-Logik, transport-unabhängig) |
| **M094** Plantafel-Sync | bidirektional via kwpsync.exe (Poll/Write MSSQL) | bidirektional via API (Webhook KWP→HiveGrid + API-Call HiveGrid→KWP) | **VEREINFACHT** falls KWP-API Webhooks bietet (Spec 19.11.3 „Trigger-basierter Pull" wird dann Phase-1-fähig statt Phase-2) |
| **M095** Dokumenten-Archiv-Sync | KWP→HiveGrid via Client-Filezugriff | KWP→HiveGrid via API-Dokumenten-Endpoint | **VEREINFACHT** (kein lokaler Dateizugriff; `@toolctrl/storage` + API-Download) |
**Netto:** M089 entfällt, M090/M091/M092/M094/M095 vereinfachen sich teils erheblich, nur M093 (Konflikt-Regel) bleibt unverändert. Der Gesamt-Aufwand des Moduls **sinkt deutlich**, und das Reuse-Level steigt faktisch von medium Richtung **medium-high**, weil die generische `appsEngine.prisma` + `apps/api`/`apps/worker`-Fundamente bei einer API-Anbindung **direkter** passen als beim Windows-Client-Sonderweg.
### (3) Wie Apps-Engine/Adapter (defineAdapter, plugins, plugin-sdk) statt des Sync-Programms genutzt werden
- **`appsEngine.prisma` ist der richtige Boden — nicht das WASM-Plugin-System.** Wichtige Abgrenzung (auch in der Inventur betont, `integrations-ki.md` §4 + „Wichtige Abgrenzungen"): Es gibt **zwei** „Apps-Engine"-Bedeutungen.
- **`packages/plugin-runtime` + `packages/plugin-sdk`** = WASM-Sandbox für **Drittanbieter-Plugins** (Capability-Consent, Ed25519-Signatur, Hook-Lifecycle). In Prod sind **nur `log`+`audit`-Capabilities** freigeschaltet (`PLUGIN_AVAILABLE_HOST_CAPABILITY_NAMES`), `http.outbound`/`db`/`storage` sind `productionAvailable: false`. → **Für KWP NICHT geeignet**: KWP ist ein First-Party-Connector mit DB/HTTP-Bedarf, kein sandboxed Drittanbieter-WASM-Modul. Marketplace ist ohnehin Phase 2 (33a.9.1).
- **`prisma/schema/appsEngine.prisma`** (`App`/`DataConnection`/`AppSyncRun`/`AppSyncItem`) = die **First-Party-Data-Sync-Engine**. → **Das ist das richtige Fundament für eine KWP-API-App.**
- **`defineAdapter()` (`packages/foundation/src/adapters.ts`)** liefert nur Status-Registry (`not_configured/configured/healthy/degraded/unavailable`). Diese 5 Werte mappen sauber auf die M33a-Connection-Status. Die eigentliche Connector-Verhaltens-Schnittstelle (`connect/syncPull/syncPush/validateConnection/handleWebhook` aus Spec Block I) muss in M008-M010 (M33a) gebaut werden; KWP-API ist dann der **erste konkrete Adapter** dahinter — als `rest-api`/`oauth2`-`DataConnection`.
- **Empfohlene Mapping-Strategie bei API-Variante:**
- KWP-App = `App{ type: "kwp" }`, eine `DataConnection{ type: "rest-api" | "oauth2", config: <verschlüsselte API-Creds> }` pro KWP-Server.
- Token/Key der KWP-API = `ApiKey` (gehasht) bzw. OAuth-Token in `DataConnection.config`.
- Pull-Lauf = `AppSyncRun{ executionMode: "scheduled" }`; Push-Lauf = `AppSyncRun{ executionMode: "webhook"/"manual" }`; Mapping HiveGrid↔KWP-Entität = `AppSyncItem` (`sourceId`/`destinationId`); Konflikt-Restore = `AppSyncItem.rolledBackData`.
- Connector-Adapter als reines Domain-Modul in `app/domain/integrations/kwp/**`, das `adapterFetch()` für Egress nutzt; Cron/Outbox aus `apps/worker`.
- **Konsequenz für die Planung:** Vor Umsetzung von M19 muss der Plan M089-M095 gegen die API neu geschnitten werden (M089 streichen, M090-M092/M094-M095 als API-Adapter-Tasks neu fassen, M093 unverändert lassen). Die Boilerplate **unterstützt die API-Variante besser** als die ursprünglich geplante Windows-Client-Variante.
---
## Reuse-Level-Begründung: **medium**
- **Pro (warum nicht low):** Komplettes Querschnitt-Fundament vorhanden — Data-Sync-Datenmodell (`appsEngine.prisma`), gehashte Token (`ApiKey`), Idempotenz, Outbox-Push-Queue, Cron+Queue-Worker, Public-API-Auth-Schicht, Storage, Notifications, Status-Registry, Feature-Flags, RBAC. Bei API-Anbindung passt das Apps-Engine-Datenmodell sogar direkt (`type: "rest-api"`).
- **Contra (warum nicht high):** Null KWP-/ERP-Fachlogik in der Boilerplate. Das in AGENTS.md angedeutete Adapter-Framework (`defineAdapter`) ist nur eine Status-Map; das echte Connector-Interface (M33a Block I) existiert nicht. Alle KWP-spezifischen Modelle (Projektnummern-Sequenz/Reservierung, Schema-Snapshot, Error-Report), die gesamte Sync-/Konflikt-/Drift-Algorithmik und die komplette UI sind neu. In der **Windows-Sync-Variante** kommt ein komplettes externes Programm dazu (low-touch zur Boilerplate). In der **API-Variante** entfällt das und das Modell rutscht praktisch Richtung medium-high.
@@ -0,0 +1,119 @@
# Boilerplate-Abgleich — M20 Dashboard / Reporting
| Feld | Wert |
|---|---|
| **Modul-ID** | M20 |
| **Name** | Dashboard / Reporting (Geschäftsführer-Dashboard) |
| **Milestones** | M147 (Layout + Widget-Engine), M148 (7 Rollen-Standard-Layouts), M149 (Drill-Down + Custom-Widget-Konfig), M150 (Export + Report-Versand) |
| **Pflichtenheft-Block** | Block 6 · Modul 20 (`_bmad-output/pflichtenheft/blocks/block6.md` §§20.1–20.10) |
| **Detail-Spec** | `_bmad-output/specs/M20-dashboard.md` |
| **Reuse-Level** | **medium** |
---
## Kurz-Verdict
Die Boilerplate liefert ein solides **Fundament für ein fixes Stat-Dashboard**, aber **keine konfigurierbare Widget-/Layout-Engine**, wie M20 sie verlangt. Konkret vorhanden und stark nutzbar:
- Ein funktionierendes Tenant-Dashboard-Route-Pattern mit Permission-Gate, Period-Filter, Server-Timing-Metrics und i18n.
- Ein **Dashboard-Modul-Registry-Pattern** (`dashboard-registry`) mit Feature-Flag-/Plan-Gating — ideale Vorlage für den permissions-aware Widget-Katalog (Block C/F).
- Ein **Stat-/Drill-Down-Pattern** (`Stat`-DTO mit `path`/`entity.slug`, `DashboardStats`-Komponente mit `<Link>`) — direkte Vorlage für die Kern-Anforderung Drill-Down (§20.4).
- Eine vollständige **Export-Infrastruktur** (`packages/exports`: PDF via `@react-pdf/renderer`, CSV, XLSX, S3-Sinks) für M150.
- Ein **Realtime-/SSE-Fundament** (`packages/realtime`) mit Reconnect/Backoff für Live-Updates (§20.7).
- Recharts + Chart-UI-Primitive für Visualisierungen.
Was komplett fehlt: das **Datenmodell** (`Dashboard`, `DashboardLayout`, `WidgetInstance`), die **Drag-&-Drop-Grid-Engine** (kein `react-grid-layout`; nur `@dnd-kit` als Baustein vorhanden), die **Per-Widget-Caching-/Aggregat-Schicht**, der **konkrete Widget-Katalog** (Sales/Projekt/HR/… aus den Modulen) und die HiveGrid-**Layer-Split-Packages** (`ui-hivegrid`, gefüllte `view-models`, Subframe-Adapter).
> **Wichtiger Hinweis zur „packages/metrics + Widget-Engine"-Annahme aus dem Auftrag:** `packages/metrics` ist **Prometheus/prom-client** (Ops-Observability: Histogramme, AI-Cost-Counter, Metrics-Token-Auth) — **NICHT** eine Business-KPI- oder Widget-Engine. Das `Widget`-Modell in `core.prisma` ist ein generisches Legacy-UI-Widget (`name`/`appearance`/`metadata` als Strings) und deckt das M20-Widget-Modell **nicht** ab.
---
## Übernehmbar aus Boilerplate
> Pfade beziehen sich auf `/Users/raffaelsheikh/Documents/GitHub/boilerplate`. Der Boilerplate-Code lebt in der Legacy-ToolCTRL-Struktur (`apps/web/app/...`, `~/utils/...`), **nicht** im HiveGrid-Ziel-Layer-Split. Übernahme bedeutet daher fast überall „als-vorlage" + Umbau in `app/routes` + `packages/view-models` + `packages/ui-hivegrid`.
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `apps/web/app/routes/app.$tenant/dashboard.tsx` | Tenant-Dashboard-Route: Permission-Gate (`app.dashboard.view`), Period-Filter (`PeriodHelper`), Server-Timing-Metrics, i18n-Title, Empty/Permission-Handling, Modul-Gating-Verdrahtung | **als-vorlage** (Loader-/VM-Struktur übernehmen, in HiveGrid-Layer-Split überführen) |
| `apps/web/app/services/dashboard-registry/registry.server.ts` | **Dashboard-Modul-Registry** als Code-Konstante (`id`, `titleKey`, `descriptionKey`, `featureFlagKey`, `planFeatureKey`), `Object.freeze`-Pattern | **als-vorlage** — direkte Blaupause für `WidgetCatalog` (Code-Registry, Block A/C) |
| `apps/web/app/services/dashboard-registry/gating.server.ts` | Gating-Engine: pro Modul Feature-Flag + Plan-/Entitlement-Check → `allowed` + Diagnostic + Redirect | **als-vorlage** — Vorlage für permissions-aware Widget-Sichtbarkeit (§20.8 / Block F); Permission-Check ersetzt/ergänzt Plan-Check |
| `apps/web/app/application/dtos/stats/Stat.ts` (+ `StatChange.ts`) | `Stat`-DTO mit `name`, `stat`, `previousStat`, `change`, `changeType`, **`path`**, `entity.slug` | **anpassen** — `path`/`entity.slug` sind die Drill-Down-Hooks (§20.4); ins VM überführen |
| `apps/web/app/components/ui/stats/DashboardStats.tsx` | Stat-Grid-Komponente, rendert klickbare Stat-Kacheln via `<Link to={item.path}>` | **als-vorlage** — Drill-Down-Verlinkung; nach `packages/ui-hivegrid` portieren (VM-only, kein Loader-Zugriff) |
| `apps/web/app/utils/services/appDashboardService.ts` | Aggregat-Service: zählt Entity-Rows seit `gte`, berechnet `change%`/`changeType`, baut `Stat[]` | **als-vorlage** — Muster für serverseitige Aggregat-Berechnung (§20.7.1); pro HiveGrid-Widget eigener Builder |
| `apps/web/app/utils/app/DashboardUtils.ts` (`getStatChangePercentage`, `getStatChangeType`) | Reine Change-Berechnungs-Helfer | **1:1** (pure functions, in VM-Builder nutzbar) |
| `packages/exports/src/pdf/` + `packages/exports/src/index.ts` | PDF-Export (`@react-pdf/renderer`), Streaming, S3-Multipart-Sink; `audit-pdf.ts` als konkretes PDF-Beispiel | **anpassen** — Dashboard-PDF-Snapshot (M150) |
| `packages/exports/src/csv/` + `packages/exports/src/xlsx/` | CSV-/XLSX-Export mit Streaming + Spreadsheet-Safety (`spreadsheet-safety.ts`), `format-caps.ts`, `limits.ts` | **anpassen** — Widget-CSV-Export (M150); ersetzt `json2csv` (nicht in BP) |
| `packages/realtime/src/server.ts` (`serializeRealtimeEvent`, SSE) | SSE-Event-Serialisierung (id/event/data + retry), Sanitizing | **anpassen** — Live-Update-Push-Kanal (§20.7.3); neue Event-Typen für Dashboard nötig |
| `packages/realtime/src/client.ts` | SSE-Subscriber mit Reconnect/Backoff, Status-Diagnostics, EventSource-Abstraktion | **anpassen** — Client-Side Live-Update-Empfang inkl. „Live-Updates pausieren"-Opt-Out (§20.7.4) |
| `packages/realtime/src/events.ts` | Event-Schema-Registry (`REALTIME_EVENT_NAMES`) + Validierung | **anpassen** — derzeit nur Notification-Events; Dashboard-Events (`deal.won`, `lead.received`, `defect.accepted`) ergänzen |
| `apps/web/app/components/ui/chart.tsx` | shadcn-Chart-Wrapper um **Recharts** (ChartConfig, Theming, Locale-Formatters) | **1:1 / anpassen** — Visualisierungs-Primitive für Trend-/Conversion-Widgets (§20.1) |
| `apps/web/app/components/analytics/AnalyticsOverview.tsx` (+ `AnalyticsOverviewChart.tsx`) | Echtes Chart-Dashboard-Pattern: MetricCards + lazy-geladener Chart, klickbare Metriken via `<Link>` | **als-vorlage** — Muster für klickbare KPI-Karten + **Lazy-Loading** (§20.7.5) |
| `packages/view-models/src/index.ts` | VM-Foundation: `VMState`, `ActionCallbacks`, `SidebarRegistryItem`, `RegistryGate` (`permission`/`flag`), `I18nLabel` | **1:1** — Pflicht-Basis für alle M20-VMs (AGENTS.md M013/M014) |
| `packages/feature-flags/` | Feature-Flag-Querschnitt (M006) für Dashboard- und Widget-Toggles | **1:1** |
| `packages/entitlements/` | Plan-/Entitlement-Checks (im `gating.server.ts` bereits verdrahtet) | **1:1** (für `general.tenant_health`-Widget + Gating) |
| `packages/db/src/client.server.ts` (`getReadDbClient`/`getExtendedDbClient`) | Read-/Tenant-scoped Prisma-Clients, Outbox/Audit-Middleware | **1:1** — read-heavy Dashboard-Queries |
| `packages/db/src/kpi.server.ts` | Admin-Plattform-KPIs (Tenant-Counts, Active-User via `log.groupBy`) | **als-vorlage** (nur Plattform-Admin-Scope; Muster für Count-/GroupBy-Aggregate, nicht der Tenant-Widget-Katalog) |
| `infra/grafana/business-kpi.json` | Vorgefertigtes Grafana-Business-KPI-Dashboard | **Referenz** — Ops-Sicht, kein In-App-Widget; als Inspiration für KPI-Auswahl |
---
## Vorhandene Daten-Modelle (Prisma)
> Verifiziert in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`.
| Modell | Pfad | Relevanz für M20 |
|---|---|---|
| `Widget` | `prisma/schema/core.prisma:267` | **Deckt M20 NICHT ab.** Generisches Legacy-UI-Widget: `id`, `tenantId?`, `name`, `appearance` (String), `metadata` (String), `@@unique([tenantId, name])`. Keine Layout-/Instanz-/Config-/Position-Struktur. Reader: `packages/db/src/widgets.server.ts` (`findLegacyWidgetById`). Allenfalls als Namens-Squatter zu beachten (Kollision mit neuem `WidgetInstance`). |
| `MetricLog` | `prisma/schema/core.prisma:180` | Request-Performance-Log (route/duration/userId/tenantId) — **Ops-Metrik**, nicht Business-Aggregat. |
| `AnalyticsSettings`, `AnalyticsUniqueVisitor`, `AnalyticsPageView`, `AnalyticsEvent` | `prisma/schema/analytics.prisma` | First-Party-**Web**-Analytics (Visitor/PageView/Event, UTM, Geo, Device), portal-zentriert. Quelle für ein evtl. „Web-Traffic"-Widget, aber **kein** CRM-/Sales-/HR-Aggregat. |
| `FeatureFlag` (+ Filter) | `prisma/schema/featureFlags.prisma` | Für Dashboard-/Widget-Feature-Gating (M006). |
| `CollabDoc` | `prisma/schema/collabDocs.prisma` | Yjs-Realtime-Docs — nicht Dashboard-relevant (nur falls geteilte Layout-Editing-Sessions gewünscht; Phase-1 nicht gefordert). |
**Fazit Daten-Layer:** Die vier M20-Kernmodelle (`Dashboard`, `DashboardLayout`, `WidgetInstance`; `WidgetCatalog` als Code-Registry) existieren **nicht** und müssen neu gebaut werden. `Tenant`-/`User`-Relationen und das Tenant-Scoping-Muster sind vorhanden und wiederverwendbar.
---
## Lücken / komplett neu zu bauen
1. **Datenmodell M20** — neue Prisma-Modelle `Dashboard`, `DashboardLayout`, `WidgetInstance` (Spec Block A). Forward-Only-Migration mit Inverse-SQL (DoD). Achtung: `Widget` ist als Modellname belegt → `WidgetInstance` + `WidgetCatalogKey` verwenden.
2. **WidgetCatalog (Code-Registry)** — die konkrete Liste aus Block C (`sales.*`, `projects.*`, `tasks.*`, `activity.*`, `comms.*`, `hr.*`, `ai.*`, `general.*`) mit Default-Config-Schema, Render-Komponente, Datenquelle + Quellen-Modul-Permission. Das `dashboard-registry`-Pattern ist die Vorlage, der **Inhalt** ist komplett neu und modul-abhängig (M3/M4/M26/M1/M9/M12/M14/M18).
3. **Drag-&-Drop-Grid-Engine** — `react-grid-layout` ist **NICHT** in den Deps (entgegen PLAN-Hinweis); nur `@dnd-kit/core` + `@dnd-kit/sortable` vorhanden. Entweder Grid-Library hinzufügen oder Grid auf `@dnd-kit` selbst bauen (Resize ist mit dnd-kit nicht out-of-the-box). Layout-Persistenz (`layout_data` JSON) neu.
4. **Per-Widget-Aggregat-/Caching-Schicht** — Cache-Key `tenant_id + widget_key + config_hash + user_id`, TTL 60 s, Invalidierung (§20.7). Kein generischer Widget-Cache vorhanden; `appDashboardService` zählt direkt ohne Cache. Pre-Calc-Aggregat-Tables + Cron (§20.7.2) neu — `apps/worker` + BullMQ als Fundament vorhanden.
5. **7 Rollen-Default-Layouts als deklaratives Branchen-Template** (M148, §20.5, LP-3/AV#3) — Seed-Daten beim Tenant-Anlegen. Seed-Infra (`packages/db/src/seed.server.ts`, `entitlements-seed`, `permissions-seed`) vorhanden, die **Layout-Templates** selbst neu.
6. **Widget-Datenquellen** — jeder Widget-Builder hängt an einem anderen Modul (Sales-Pipeline-KPIs, Forecast, Vertriebler-Performance, Projekt-Auslastung/Plantafel, offene Mängel, HR „wer ist heute da", ungelesene Mails, Anrufe heute, KI-Vorschläge). Diese Quell-Module sind im Boilerplate noch nicht als HiveGrid-Module gebaut → harte Abhängigkeit zu M01/M03/M04/M09/M12/M14/M18/M26.
7. **Drill-Down-Filter-Ableitung** (§20.4, Kern-Anforderung) — aus Widget-Config den vorgefilterten Listen-Link bauen, permissions-aware. `Stat.path`/`entity.slug` ist der Hook, die **Filter-Serialisierung** je Widget neu.
8. **Dashboard-Permissions** (`dashboard.read/customize/create/share/admin` + Bundles, Block F) — neue Permission-Keys. Boilerplate hat nur `app.dashboard.view` / `admin.dashboard.view` (`packages/db/src/permissions-seed.server.ts`). Permission-Definition gehört nach `packages/entitlements/src/permissions.ts` (Integration-Contract §10).
9. **Dashboard-Live-Events** — `packages/realtime` kennt nur Notification-Events; Dashboard-Events (`deal.won`, `lead.received`, `defect.accepted`) + Server-Push-Verdrahtung + „Live-Updates pausieren"-Opt-Out neu.
10. **HiveGrid-Layer-Split** — `packages/ui-hivegrid`, gefüllte `packages/view-models/src/dashboard/*.vm.ts`, Subframe-Adapter existieren noch nicht. Der Boilerplate-Dashboard-Code liegt monolithisch in `apps/web` mit `useLoaderData`/`~/db`-Nähe und verletzt die HiveGrid-Anti-Patterns → bei Übernahme zwingend umbauen.
11. **Sidebar-/Shell-Wiring** — `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (Integration-Contract §2) existiert nicht; Boilerplate nutzt eine andere Shell. Sidebar-Eintrag „Dashboard" (Gruppe ARBEITEN) neu zu registrieren. `SidebarRegistryItem`-Typ aus `packages/view-models` ist die Basis.
12. **Mobile-First Monteur-Dashboard** (LP-2, §20.5.7) — Mobile-Tab-Bar-Eintrag (M169) + reduziertes Layout neu.
13. **Klartext-States** — Empty/Loading/Error pro Widget aus M002-Catalog + M003-i18n. Boilerplate-Dashboard hat i18n-Keys (`app.dashboard.*`), die konkreten Widget-Texte (§20.10) neu.
14. **Report-Versand-Trigger** (M150) — manuelle Generierung via vorhandene `exports`-Infra; geplante Email-Reports sind explizit Phase 2 (§20.9.2, Out-of-Scope).
---
## Empfohlenes Vorgehen
**Phase 0 — Layer-Fundament & Übernahme der Patterns (vor M147):**
1. `packages/view-models`-Foundation (`VMState`, `ActionCallbacks`, `SidebarRegistryItem`) ist bereits da → 1:1 nutzen, `dashboard`-VM-Ordner anlegen.
2. `Stat`-DTO + `getStatChangePercentage`/`getStatChangeType` (pure) nach `packages/view-models`/`app/domain` portieren (1:1).
3. `DashboardStats`- und `AnalyticsOverview`-Komponente als Vorlage nach `packages/ui-hivegrid` übernehmen (VM-only, Drill-Down via `<Link>` beibehalten).
4. `dashboard-registry`-Pattern (`registry.server.ts` + `gating.server.ts`) als Blaupause kopieren → daraus den `WidgetCatalog` + permissions-aware Gating formen (Permission-Check statt Plan-Check).
**M147 — Layout + Widget-Engine:**
5. Neue Prisma-Modelle `Dashboard`/`DashboardLayout`/`WidgetInstance` + Migration. `Tenant`-Scoping-Muster aus `packages/db` nutzen.
6. Grid-Engine: Entscheidung `react-grid-layout` hinzufügen **oder** auf vorhandenem `@dnd-kit` bauen (Resize-Aufwand einplanen).
7. Per-Widget-Aggregat-Builder nach Muster `appDashboardService` (serverseitig, im Loader → VM). Caching-Schicht (TTL 60 s, Cache-Key per Spec) neu; `getReadDbClient()` für read-heavy Queries.
8. Recharts/`chart.tsx`-Primitive für Trend-/Conversion-Widgets 1:1 übernehmen.
9. Realtime: `packages/realtime` Server/Client übernehmen, Dashboard-Event-Typen ergänzen, Lazy-Loading (lazy-Chart wie `AnalyticsOverviewChart`).
**M148 — 7 Rollen-Default-Layouts:**
10. Deklarative Layout-Templates als Seed-Daten (Seed-Infra aus `packages/db/src/seed.server.ts` vorhanden); permissions-aware Widget-Filter aus dem Gating-Pattern.
**M149 — Drill-Down + Custom-Konfig:**
11. Drill-Down-Filter-Ableitung je Widget (`Stat.path`/`entity.slug` als Hook), permissions-aware. Widget-Picker mit Catalog-Gating (ausgegraut bei fehlender Permission).
**M150 — Export:**
12. `packages/exports` (PDF `@react-pdf/renderer` + CSV/XLSX) direkt anbinden: Dashboard-PDF-Snapshot + Widget-CSV. Geplante Email-Reports bleiben Phase 2.
**Querschnitt durchgehend:** Permission-Keys in `packages/entitlements`, Feature-Flags (M006), i18n (M003), Audit (M001 auto) für Layout-Änderungen an shared Dashboards (AV#6), Sidebar-Eintrag (§2), Smoke-Test + Hot-Swap-Drill + Visual-Regression (DoD D).
@@ -0,0 +1,119 @@
# Boilerplate-Abgleich — Modul 21: Audit-Log (Anzeige)
- **Modul-ID:** M21 (Detail-Spec `_bmad-output/specs/M21-audit-log.md`)
- **Name:** Audit-Log — tenant-weiter Trail aller schreibenden Aktionen mit Vorher/Nachher-Diff
- **Milestones:** M151 (Anzeige + Filter + Volltext-Suche), M152 (Compliance-Export + Aufbewahrung + Legal Hold); baut auf M001 (Audit-Default) auf
- **Pflichtenheft-Block:** Block 7, Abschnitte 21.1–21.8
- **Reuse-Level:** **medium**
> Die Boilerplate liefert ein produktionsreifes Audit-**Fundament** (Tamper-evidente `AuditEvent`-Tabelle mit Hash-Chain, Write-Path, Retention-Worker, Compliance-Export inkl. PDF/CSV, Permission-gegatete Admin- + Tenant-Routen). Aber: Das Boilerplate-Audit-Modell ist auf **Compliance-Evidence** (SOC2/HIPAA/GDPR) ausgelegt, **nicht** auf den HiveGrid-Detail-Spec mit Vorher/Nachher-**Diff**, Klartext-`summary_text`, Subject-/Actor-**Snapshot-Labels**, **Saved Views**, tenant-Admin-konfigurierbarer **Retention in Monaten** und **Legal Hold**. Diese fachlichen Kern-Features fehlen komplett. Die Listen-/Detail-Anzeige-UI für Endnutzer (Tabelle, Diff-View, Per-Subject-Drawer) ist ebenfalls neu zu bauen — Boilerplate hat nur Export-Forms und eine Admin-`Log`-Tabelle.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/core.prisma:55` (`model AuditEvent`) | Audit-Tabelle: `tenantId`, `actorId/Type/Email/Ip/UserAgent`, `action`, `targetType/Id`, `requestId`, `sourceModule`, `outcome`, `dataSensitivity`, `regulatoryScope[]`, `metadata` (JSON), `previousHash`/`eventHash`. Indizes auf `(tenantId,createdAt)`, `(actorId,createdAt)`, `(action,createdAt)`, `requestId`, `(tenantId,action,createdAt)` | **anpassen** — Felder weitgehend deckungsgleich mit Spec Block A; ABER es fehlen `before_diff`/`after_diff`/`summary_text`/`actor_label`/`subject_label`. Spec-`subject_type`/`subject_id` = boilerplate `targetType`/`targetId`. `actor_kind`-Werte (`ki_agent`, `automation`, `platform_admin`) müssen ergänzt werden. Append-Only-DB-Trigger (Spec) fehlt. |
| `packages/db/src/audit-events.server.ts` | Single-Write-Path `createAuditEvent()` / `publishAuditEventViaOutbox()` (Transaction-aware via Outbox), Metadata-Sanitizing (Secret-Redaction), Per-Tenant-Hash-Chain-Link, `buildAuditEventCreateData()`, `toAuditHashPayloadFromRow()` | **1:1** für M001-Fundament; **anpassen** für M21 (neue Diff-/Summary-Felder ins Write-Schema aufnehmen) |
| `packages/db/src/audit-hash.ts` | Tamper-Evidenz: `computeAuditHash()` (HMAC-SHA256 via `AUDIT_CHAIN_SECRET`, Fallback SHA-256), `canonicalizeAuditPayload()`, `verifyAuditChain()` mit Break-Reporting | **1:1** — deckt Spec Block I (Hash-Chain Phase 2) bereits vor; Verifikations-Tool-Backend ist da, nur UI fehlt |
| `packages/foundation/src/audit.ts` | DB-agnostische `auditEvent(input, client)`, `withAuditMiddleware(handler, buildEvent, client)`, Typen `AuditEventInput`/`AuditEventClient` | **als-vorlage** für M001-Querschnitt-Aufruf; M21 selbst liest nur |
| `packages/db/src/logs.server.ts` | Admin-/Tenant-Audit-**Listen-Query**: `getAdminAuditLogList()`, `getTenantAuditLogList(tenantId, …)`, `buildAuditLogWhereFromFilters()` (Filter q/action/url/userId/createdAtFrom/To, Volltext-OR), `serializeAdminAuditLogsCsv()`, Pagination (take/skip, max 500) — operiert allerdings auf dem **`Log`**-Modell, nicht `AuditEvent` | **als-vorlage** — Filter-/Pagination-/Where-Builder-Muster direkt übertragbar; muss auf `AuditEvent`-Modell + Spec-Filter (Actor-Kind, Subject-Type, Bulk-Op-ID, IP) umgeschrieben werden |
| `packages/db/src/export-jobs.server.ts` + `prisma/schema/queue.prisma:27` (`model ExportJob`) | Async-Export-Job-Lifecycle: `ExportJobCreateInput`, RUNNING/SUCCEEDED/FAILED/PAUSED-Transitions, `artifactBucket/Key`, `rowCount`, `expiresAt`/`deletedAt`/`hardDeletedAt` (TTL + Cleanup), `requestId`, Retention-Records | **anpassen** — exakt das Job-Modell für M152-Compliance-Export. Es fehlt im Modell `filter_criteria`/`format`-Enum-Detaillierung + `purpose/reason`-Pflichtfeld (Spec Block G) + Self-Audit `audit.exported` |
| `packages/exports/src/audit-pdf.ts` (`./audit-pdf`) | `serializeAuditEventsToPdf` / `…Stream`, `AuditPdfEvent`, Cover-Page (Tenant/Range/Filter/Integrity) + tabellarischer Event-Log, Row-Cap `PDF_STREAM_HARD_ROW_LIMIT=5000` | **1:1** für M152-PDF-Export (Spec Block G PDF-Format); HiveGrid muss DE-Labels + Zweck-Begründung in Header ergänzen |
| `packages/exports/src/{csv,json}` + `src/sinks/s3-multipart.ts` + `src/limits.ts` | CSV/JSON-Serializer (streaming), S3-Multipart-Sink (8 MB Parts), Plan-Row-Caps, Spreadsheet-Injection-Safety | **1:1** für M152-Export CSV/JSON nach Scaleway-S3 |
| `apps/web/app/routes/admin/audit-export.helpers.server.ts` | `parseAuditExportFilters()`, `buildAuditExportWhere()` (tenantId/actorType/outcome/regulatoryScope/Date-Range), `computeAuditIntegritySummary()`, `renderAuditExportCsv()`, `AUDIT_EXPORT_MAX_ROWS=50000`, `csvCell()` (injection-safe) | **als-vorlage** — Filter-→-Where-Übersetzung + Integritäts-Summary direkt adaptierbar; Filter-Set muss auf Spec Block F erweitert werden |
| `apps/web/app/routes/app.$tenant/settings/audit-export.tsx` | **Tenant-scoped** Export-Route (Permission `app.settings.auditTrails.view`, tenantId-locked gegen Query-Smuggling), CSV+PDF-Download-Form mit Filtern, i18n-Keys | **als-vorlage** — zeigt das korrekte Tenant-Scope-Pattern; ist aber synchroner Direkt-Download, **kein** Async-Job-mit-Notification (Spec verlangt Job + Vorschau-Count + Begründung) |
| `apps/web/app/routes/admin/audit-trails.tsx` + `apps/web/app/components/audit/AdminAuditLogToolbar.tsx` | Admin-Listen-View: `IndexPageLayout` + `LogsTable` + Filter-Toolbar + CSV-Export-Button + Pagination, `verifyUserHasPermission("admin.auditTrails.view")` | **als-vorlage** — Layout-/Toolbar-/Tabellen-Muster; läuft auf `Log`-Modell + Plattform-Admin (M041), nicht auf der Tenant-`AuditEvent`-Anzeige aus M151 |
| `apps/web/app/utils/audit/pdfRender.ts` (`renderAuditExportPdfResponse`, `buildAuditPdfLabels`) + `apps/web/app/utils/audit/withAuditContext.ts` | PDF-Response-Wrapper + Audit-Kontext-Middleware (Request-ID, Actor-Resolution) | **anpassen** — DE-Labels für HiveGrid |
| `apps/worker/src/jobs/audit-retention.ts` | Täglicher Retention-Cron: `runAuditRetentionJob()` mit Seams (tenantLister/eventDeleter/auditWriter), `resolveAuditRetentionPolicy()`, Meta-Audit der Löschung selbst | **anpassen** — Mechanik passt (Spec Block H: täglicher Lösch-Job mit Self-Audit). ABER: Boilerplate-Policy ist **regulatory-scope-basiert in Tagen** (365/6y/7y), Spec verlangt **tenant-Admin-konfigurierbar 6–120 Monate** + **Legal-Hold-Pause** — beide fehlen und sind nachzurüsten |
| `apps/worker/src/jobs/audit-event-persist.ts` (+ `-bootstrap`) | Outbox-Consumer der Audit-Inserts (`outbox.audit`-Queue), führt prevHash-Lookup + Chain-Link in kurzer Transaktion aus | **1:1** für M001-Async-Audit-Schreibpfad |
| `apps/worker/src/jobs/export.ts` + `dsgvo-export.ts` | Generischer Export-Job + DSGVO-Export-Muster (Aggregation, S3-Stream, Signed-URL, Self-Audit `EXPORT_PERSONAL_DATA`) | **als-vorlage** für M152-Audit-Export-Worker (gleiches Muster: Filter → Stream → S3 → Signed-URL → `audit.exported`) |
| `packages/db/src/permissions-seed.server.ts:102/177/202/237` | Permissions `admin.auditTrails.view` (SuperAdmin) + `app.settings.auditTrails.view` (SuperUser/Admin) bereits geseedet + Rollen-Mapping | **anpassen** — entspricht grob Spec `audit.read`; Spec verlangt zusätzlich getrenntes `audit.admin` (Export/Retention/Legal-Hold) und `audit.read` als atomares Bundle (M27) |
| `prisma/schema/featureFlags.prisma` + `packages/feature-flags` | Feature-Flag-Querschnitt (`FeatureFlag`, append-only `FeatureFlagAudit`) | **1:1** für DoD-Punkt „Feature-Flag-fähig" |
| `packages/i18n` + `apps/web/.../audit-export-i18n.test.ts` | i18n-Querschnitt + bestehende Audit-Export-i18n-Keys | **anpassen** — Keys-Schema nutzen, HiveGrid-Audit-Action-Labels + Klartext-Hinweise (Block L) neu |
| `packages/view-models` | View-Model-Layer-Paket (M013-Konvention) | **als-vorlage** — pure VM-Builder für Audit-Listen-/Detail-VM neu darin anlegen |
| `apps/api/.../middleware/audit-context.ts` + `request-id.ts` | Request-ID + Audit-Kontext-Middleware in der API | **1:1** — liefert `requestId`/Actor-Kontext für Audit-Einträge |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
| Modell | Pfad | Bezug zu M21 |
|---|---|---|
| `AuditEvent` | `prisma/schema/core.prisma:55` | **Kern-Modell.** Deckt Spec Block A zu ~70% (Actor-Felder, Action, Target, requestId, metadata, IP/UA, Hash-Chain, Indizes). **Fehlend:** `before_diff`, `after_diff`, `summary_text`, `actor_label`, `subject_label` |
| `Log` | `prisma/schema/core.prisma:36` | Älteres, schlankeres Aktivitäts-Log (url/action/details, Tenant/User/ApiKey/Row/Comment-Relationen). Wird von `logs.server.ts`-Listen-Query genutzt — **NICHT** das Spec-Audit-Modell, eher Aktivitäts-/Row-Log |
| `ExportJob` + Enum `ExportJobStatus` | `prisma/schema/queue.prisma:20/27` | **Direkt für M152-Export-Job.** Hat TTL (`expiresAt`/`deletedAt`/`hardDeletedAt`), `artifactBucket/Key`, `rowCount`, Status-Lifecycle. Fehlend: `filterCriteria`, `purpose/reason` |
| `ImpersonationAudit` | `prisma/schema/accounts.prisma:266` | Spezial-Audit für Admin-Impersonation (SetNull-Tombstone) — Referenz-Muster, nicht direkt M21 |
| `FeatureFlagAudit` | `prisma/schema/featureFlags.prisma:44` | Append-only Flag-Audit — Beispiel für append-only-Pattern; Spec `feature_flag.changed`-Marker |
| `PluginCapabilityUse` / `PluginInvocation` | `prisma/schema/plugins.prisma` | Per-Capability-Audit mit eigener Hash-Chain (`prevHash`/`rowHash`) — Referenz-Muster für Tamper-Evidenz |
| `QueueFailedJob` | `prisma/schema/queue.prisma:1` | Export-Job-Failure-Tracking |
**Komplett fehlende Modelle (Spec Block A Sub-Entitäten):**
- `AuditRetentionPolicy` (tenant-Admin Retention in Monaten + `legal_hold_active`/`legal_hold_reason`/`legal_hold_set_by/at`) — **existiert NICHT**
- Saved-View / `SavedAuditView` (max 5/User, Spec Block F / 21.3.4) — **existiert NICHT**
- `AuditExportJob` als dedizierte Audit-Variante mit `filter_criteria` + Zweck-Begründung — **existiert NICHT** (nur generisches `ExportJob`)
---
## Lücken / komplett neu zu bauen
### Daten-Layer
1. **Diff-Felder am `AuditEvent`** — `before_diff` (JSONB), `after_diff` (JSONB), `summary_text` (DE-Klartext, Pflicht), `actor_label`, `subject_label` (Snapshot-Namen für Hard-Delete-Resistenz). Spec-zentral (Block D/E), in Boilerplate **nicht vorhanden**.
2. **`actor_kind`-Erweiterung** — Boilerplate kennt `user/admin/api_key/system/plugin`; Spec braucht zusätzlich `automation`, `ki_agent`, `platform_admin`.
3. **`AuditRetentionPolicy`-Modell** + tenant-Admin-Konfig 6–120 Monate (Default 24) + Legal-Hold-Felder (Block H) — **neu**.
4. **Saved-Views-Modell** (max 5/User, geseedete Default-Ansichten) (Block F) — **neu**.
5. **GIN-Index auf `metadata`** + **Trigram-Index auf `summary_text`** (Volltext) — Spec Block A; Boilerplate hat weder `summary_text` noch diese Indizes.
6. **Append-Only-DB-Trigger** (UPDATE/DELETE-Block auf App-Role) — Spec verlangt DB-Trigger; Boilerplate setzt Append-Only nur auf App-Ebene (kein DELETE/UPDATE-Pfad im Code), kein DB-Trigger.
### Domänen-Logik
7. **Cursor-Pagination** (Spec: cursor-basiert, 100/Page, „Mehr laden") — Boilerplate `logs.server.ts` ist **offset-basiert** (take/skip).
8. **Erweiterte Filter** — Actor-Kind, Subject-Type-Multi-Select, Subject-ID-Autocomplete, Bulk-Op-ID, IP-Filter (Forensik). Boilerplate-Where-Builder kennt nur action/url/userId/tenantId/Date.
9. **Sensible-Diff-Maskierung** (HR/Portal/Secrets → nur „Wert geändert", permission-abhängig `hr.read_all`/`audit.admin`) — **neu** (Boilerplate redacted nur metadata-Keys generisch, kein permission-abhängiges Diff-Gating).
10. **Bulk-Op-Aggregat + Aufklapp-Logik** (Geschwister-Entries derselben `bulk_op_id`) — **neu**.
11. **Vorschau-Count vor Export-Submit** + **Pflicht-Zweck-Begründung** + **Async-Job statt Direkt-Download** (Block G) — Boilerplate-Tenant-Export ist synchroner Direkt-Stream.
12. **Legal-Hold-Logik** im Retention-Worker (Pause für Tenant bei `legal_hold_active`) + Retention-Reduzierungs-Vorschau („ca. X Einträge betroffen") — **neu**.
13. **Permissions-Split** — separates `audit.admin` (Export/Retention/Legal-Hold) vs. `audit.read`; Boilerplate hat nur ein `…auditTrails.view`. Legal Hold braucht zusätzlich `tenant.admin` UND `audit.admin`.
### UI (größte Lücke)
14. **Tenant-Audit-Listen-View für Endnutzer** (M151) — Tabelle/Stream mit Actor-Avatar, Action-Label (i18n), Subject klickbar, Summary-Text, relative/absolute Zeit, Quick-Filter, Date-Range, Saved-Views-UI. Boilerplate hat nur **Admin**-`Log`-Tabelle + **Export-Form**, keine Tenant-`AuditEvent`-Anzeige.
15. **Detail-View mit Diff-Visualisierung** (Block E) — Skalar nebeneinander, JSON-Struktur-Diff, Sensible-Marker, Copy-`request_id`, „Ähnliche/Verlauf"-Links. **Komplett neu.**
16. **Per-Subject-Audit-Drawer** in Detail-Views (Kontakt/Deal/Projekt) + **Per-User-Audit-Drawer** in Admin/users/:id (Block C) — **neu**, gegated `audit.read`.
17. **Settings-View** (`/admin/audit/settings`) — Retention-Slider, Legal-Hold-Toggle mit Pflicht-Begründung, Hash-Integritäts-Prüf-Button (Phase 2-Backend existiert via `verifyAuditChain`). **Neu.**
18. **Export-Job-Übersicht + Anlage + Status/Download-Routen** (`/admin/audit/exports*`) — **neu** (Boilerplate hat Form, keine Job-Übersicht).
19. **Klartext-Hinweise** (Block L: leerer Trail, Subject gelöscht, Bulk-Op, Automation/KI-Bezug, Legal-Hold-Banner) — i18n-Keys neu.
20. **Sidebar-Eintrag** (Gruppe EINSTELLUNGEN → Audit-Log, INTEGRATION-CONTRACTS §1) + Breadcrumbs — in HiveGrid-App-Shell neu zu registrieren.
### Querschnitt
21. **Activity-Stream-Brücke** (Block K: `audit_event`-Activity-Typ) — abhängig von M045; **neu**.
22. **Notifications** bei Export-Fertigstellung (`notify()`, M011) — Wiring neu.
---
## Empfohlenes Vorgehen
**Phase 0 — M001-Fundament prüfen/erweitern (Voraussetzung):**
1. `AuditEvent`-Modell (`core.prisma:55`) **übernehmen** und um Spec-Felder erweitern: `before_diff`, `after_diff`, `summary_text`, `actor_label`, `subject_label`; `actor_kind`-Werte ergänzen. Forward-only Migration mit GIN-(`metadata`)- + Trigram-(`summary_text`)-Index. Append-Only-DB-Trigger ergänzen.
2. Write-Path `createAuditEvent()`/`publishAuditEventViaOutbox()` (`packages/db/src/audit-events.server.ts`) + `audit-hash.ts` + Outbox-Consumer (`audit-event-persist.ts`) **1:1 übernehmen**, Diff-/Summary-Felder ins Schema einziehen.
**Phase 1 — M151 Anzeige (Wiederverwendung mittel, UI neu):**
3. Listen-Query: `logs.server.ts`-Filter-/Where-/Pagination-Muster **als Vorlage**, neu gegen `AuditEvent` schreiben (Cursor-Pagination, erweiterte Filter Block F, `withTenantScope()`+`withPermission()` aus M004).
4. View-Model-Builder in `packages/view-models` (M013) — Listen-VM + Detail-VM (Diff-Strukturierung, Sensible-Maskierung, Snapshot-Labels) — **neu**, pure Functions + Zod.
5. UI komplett neu via Subframe-Adapter (M015): Listen-View, Detail-/Diff-View, Per-Subject/-User-Drawer. Sidebar + Breadcrumbs + i18n-Keys.
6. Saved-Views-Modell + Default-Ansichten-Seed — **neu**.
**Phase 2 — M152 Export + Retention + Legal Hold:**
7. Export: `ExportJob`-Modell (`queue.prisma:27`) + `export-jobs.server.ts` + `dsgvo-export.ts`-Muster **übernehmen/anpassen** (filter_criteria + Zweck-Begründung + Vorschau-Count). Serializer `audit-pdf.ts`/`csv`/`json` + S3-Multipart-Sink **1:1**. Self-Audit `audit.exported` + `notify()` bei Fertigstellung.
8. Retention: `audit-retention.ts`-Worker **anpassen** — Policy von regulatory-scope-Tagen auf `AuditRetentionPolicy` (Monate, tenant-konfigurierbar) + Legal-Hold-Pause umstellen. Reduzierungs-Vorschau-Count.
9. Settings-UI (Retention/Legal-Hold/Integritäts-Prüfung) — **neu**; Hash-Verifikations-Backend (`verifyAuditChain`) ist bereits da.
**Permissions (parallel, M27-abhängig):** `audit.read` / `audit.admin` als atomare Bundle-Permissions definieren; Boilerplate-`…auditTrails.view` als Ausgangspunkt, aber splitten.
---
## Notizen / Realitäts-Check
- Das Boilerplate-Audit ist **Compliance-Evidence-orientiert** (SOC2/HIPAA/GDPR, Hash-Chain, regulatory-scope-Retention), nicht **operativ-nachvollziehbar** (Diff/Summary/Snapshot). Das ist die fundamentale Differenz: Tamper-Evidenz + Schreibpfad + Export-Pipeline sind **vorbildlich vorhanden**, aber der für HiveGrid-Endnutzer zentrale **Diff-/Klartext-/Anzeige-Layer** ist neu.
- Der Boilerplate hat **zwei** Audit-artige Tabellen: `AuditEvent` (Compliance, `core.prisma:55`) und `Log` (Aktivitäts-/Row-Log, `core.prisma:36`). Die bestehende Listen-UI (`audit-trails.tsx` + `logs.server.ts`) läuft auf `Log`, nicht auf `AuditEvent`. Für M21 ist `AuditEvent` das richtige Modell — die Listen-Query muss umgehängt werden.
- Phase-2-Features der Spec (Hash-Chain Block I) sind im Backend **bereits implementiert** (`audit-hash.ts`, `verifyAuditChain`) — nur das Verifikations-Tool-UI in den Settings fehlt. Das ist ein unerwarteter Vorsprung.
- Kein `before/after`-Snapshot in M001-Prisma-Middleware-Default: AGENTS.md/INTEGRATION-CONTRACTS §6 sagen „Audit ist automatisch via Prisma-Middleware" — diese Middleware ist im Boilerplate **nicht** vorhanden (es gibt `withAuditMiddleware` für Service-Handler + `createAuditEvent`, aber keine generische Prisma-`$extends`-Middleware, die before/after automatisch erfasst). Das ist eine M001-Lücke, die M21 voraussetzt.
@@ -0,0 +1,138 @@
# Boilerplate-Abgleich — M22 Notifications
| Feld | Wert |
|---|---|
| **Modul-ID** | M22 (Notifications) |
| **Modul-Name** | Drei-Kanal-Notifications (In-App / Email / Mobile-Push) |
| **Milestones** | M115 (Notification-Center + Lese-Status), M116 (User-Settings: Kanal + Stille-Stunden + Geräte), M117 (Kategorien + Bündelung + Anti-Spam + Versand-Pipeline) |
| **Block** | Block 5 (Kommunikation), §22 |
| **Service-Layer-Querschnitt** | M011 (`notify()`) — Boilerplate-Foundation deckt das Fundament |
| **Reuse-Level** | **MEDIUM** |
> **Quellen verifiziert (eigene Reads/Greps, nicht nur Inventur):**
> Detail-Spec `_bmad-output/specs/M22-notifications.md`, Pflichtenheft `block5.md §22`, die 3 PLAN.md (M115-M117), AGENTS.md (DoD A-F), INTEGRATION-CONTRACTS.md (§1 Sidebar, §7 Notification-Wiring), Boilerplate-Inventur (foundation/data-layer/apps-infra/ui-shell) UND direkte Reads der Boilerplate-Dateien (Prisma-Schema, db/foundation/realtime/mail-Pakete, API-Routes, Worker-Job, Web-Routes/Components).
---
## Kern-Befund (eine Zeile)
Die Boilerplate hat einen **fast vollständigen vertikalen In-App-Notification-Slice** (DB-CRUD → SSE-Stream-API → SSE-Client mit Reconnect → Notification-Center-Component → Tenant-Route + minimale Settings-Route) **plus** ein **Mobile-Push-Fundament** (DeviceToken-Modell, Register/Revoke-Routes, provider-pluggable Push-Fan-out-Worker, Capacitor-Push-Registration) **plus** BullMQ-`notifications`-Queue, `@toolctrl/mail` + React-Email-Templates und sogar eine Novu-Anbindung. **Aber:** Das Datenmodell ist eine schlanke *Delivery/Diagnostics*-Sicht (`NotificationDelivery`) — es fehlt das reiche M22-`Notification`-Aggregat (title/body/deeplink/actor/priority/bundle), die **PUSH-Channel-Enum-Werte**, **Quiet-Hours**, **Bundle-Window/Sliding-Window**, **Priority** und die ganzen **Settings-/Devices-/Bündel-UI-Flächen**.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/notifications.ts` | `notify()`, `notifyMany()`, `bundleNotifications()`, `isNotificationEnabled()`, `assertI18nKey()`, Typen `NotificationInput/Preference/Bundle` — DB-/framework-agnostisches Querschnitt-Primitiv mit Preference-Check, sourceKey-Upsert (Idempotenz), Metadata-Sanitizing/Redaction | **als-vorlage** — exakt der M011-`notify()`-Einstiegspunkt aus INTEGRATION-CONTRACTS §7. Muss aber um `PUSH`-Channel, `priority`, Quiet-Hours-Resolver und echte Bundle-**Window**-Logik erweitert werden (heute nur statisches Gruppieren ohne Zeitfenster). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/notifications.server.ts` | Vollständige Server-Helper: `createNotificationDelivery` (upsert/idempotent per sourceKey), `markInAppNotificationDeliveryRead`, `markNotificationDeliveryStatus`, `getNotificationDeliveryDiagnostics`, `getNotificationStreamSnapshot` (Cursor-Stream, 50/Seite), `upsert/getUserNotificationPreferences`, Redaction (`redactNotificationDiagnosticText`) | **anpassen** — Lese-Pfade (Stream-Snapshot, mark-read, Preferences) sind 1:1 nutzbar. Schreib-Pfad braucht die neuen M22-Felder (title/body/deeplink/actor/priority/bundle_id). PUSH-Channel und Priority-Threshold fehlen. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/notifications.prisma` | Modelle `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` + Enums `NotificationDeliveryStatus`, `NotificationPreferenceChannel` | **anpassen** — siehe „Vorhandene Daten-Modelle". DeviceToken ist quasi 1:1 die M22-`NotificationDevice`. Die anderen beiden sind Fundament, brauchen aber Felderweiterung + neue Modelle (Bundle, QuietHours, reiches Notification-Aggregat). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/device-tokens.server.ts` | `registerDeviceToken` (idempotent per token), `revokeDeviceToken`, `revokeDeviceTokensForUser` (Logout-Hook), `listActiveDeviceTokens`, `findDeviceTokenByToken`, `parseDevicePlatform`/`parsePushProvider`/`defaultPushProviderFor` | **1:1** — deckt Block H Token-Registrierung + Auto-Revoke (Logout/Token-ungültig) komplett ab. Nur Bulk-Revoke-UI und `last_seen_at`-Bump bei Push-Erfolg ergänzen. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/api/src/routes/devices-routes.ts` | `POST /v1/devices/register` + `POST /v1/devices/revoke` (Validierung, Längen-Limits, Klartext-Fehler) | **anpassen** — entspricht Spec-Endpoint `/api/v1/notifications/mobile-device`. Auth ist heute service-credential mit userId/tenantId aus dem Body; für M22-Self-Scope (eingeloggter User) muss gegen den authentifizierten Principal verifiziert werden. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/jobs/push-notification.ts` | `dispatchPushNotification()` — provider-pluggabler Fan-out (APNs/FCM/WebPush via Seam), Auto-Revoke bei `Unregistered`/`InvalidRegistration`/`BadDeviceToken`, Concurrency-Limit, Token-Redaction in Logs | **1:1** (Orchestrierung) — pure, testbar. Block J „Push-Sender" + Token-Invalidierungs-Handling (Block H). Provider-SDK-Adapter (firebase-admin/node-apn) werden in `apps/worker/src/index.ts` injiziert (Operator-Setup). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/realtime/src/events.ts` + `client.ts` + `server.ts` + `guards.ts` | Realtime-SSE-Schicht: `REALTIME_EVENT_NAMES` (`notification.snapshot`/`notification.update`/`keepalive`/`error`), `validateRealtimeEvent` (Secret-Key-Reject, Allow-list, Cursor), Subscriber-Client mit Exponential-Backoff-Reconnect, Scope-Guards | **1:1** — deckt Block B.1 „Real-time-Update über SSE" + Polling-Fallback (im Client). Nur `notification.update`-Push (Live-Toast) muss vom Sender aus emittiert werden. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/api/src/routes/notifications-routes.ts` | `GET /v1/notifications/stream` — SSE-Endpoint: Scope-Normalisierung, Workspace-Revalidation, Snapshot-Push, Keepalive, harte Security-Header | **anpassen** — Stream-Fundament steht. Heute reiner Snapshot+Keepalive (kein dauerhafter Live-Push pro neuer Notification); für echtes Live-Center muss ein Pub/Sub-Fan-out (shared-store/Redis) ergänzt werden. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/notifications/NotificationCenter.tsx` | Fertige In-App-Center-Component: SSE-Subscribe + Reconnect, Merge/Dedupe/Sort, Mark-as-read-Form, Empty-State, i18n, Status-Badges, Last-Error-Redaction | **als-vorlage** — gute Basis für M115, aber: zeigt heute *Delivery-Diagnostik* (Status/Attempts/Channel) statt der M22-Center-Felder (title/body/Actor-Avatar/Deeplink/Priority/Bundle-Count, Tabs Alle/Ungelesen/Markiert, Filter, Suche, Bulk). Darf NICHT direkt aus Routes importiert werden — über Adapter (`packages/ui-hivegrid/src/adapters/`, AGENTS.md A.4). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/routes/app.$tenant/notifications.tsx` (+ `notifications/stream.tsx`) | Tenant-Route mit Loader (Diagnostics→VM), Action (mark-read + CSRF), Stream-URL-Bridge | **als-vorlage** — exaktes RR7-Loader/Action-Muster für M115. Felder/VM müssen aufs reiche M22-Modell umgebaut werden. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/routes/app.$tenant/settings/notifications.tsx` | Settings-Route: Preference-Toggle pro Kanal/Kategorie (IN_APP/EMAIL), CSRF-Action, Loader | **als-vorlage** — Grundgerüst für M116-Präferenzen. Sehr schmal (3 Kategorien hartkodiert, kein PUSH, kein Priority-Threshold, kein Master-Toggle, keine Modul-Gruppierung, keine Quiet-Hours, keine Geräte). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/layouts/buttons/NotificationsButton.tsx` + `.../sidebars/shadcn/nav-actions.tsx` + `.../icons/IconNotifications.tsx` | Glocken-Button in der Header-Action-Leiste (feature-gated `appConfiguration.notifications.enabled`), verlinkt auf Tenant-/Admin-Notifications | **anpassen** — Block B.1 „Glocke in Top-Bar". Unread-Count-Badge + Tab-Title-Update fehlen und müssen ergänzt werden. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/mail/src/index.ts` (+ `templates-react/`, `mailersend.ts`, `queue.ts`) | `@toolctrl/mail`: MailerSend-Provider (EU-Region nutzbar), `QueuedMailProvider`, React-Email-Render (`renderTransactionalEmail`), Brand-Defaults (`buildBrand`/`withBrandDefaults`) | **anpassen** — Block B.2 Email-Versand + Branding. EU-Stack (LP-13). Tenant-Sending-Domain-Anbindung (Modul 9) + Bounce-Pause-Logik + Notification-spezifische Templates fehlen. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/email-templates/src/index.ts` | React-Email-Template-Engine (`renderEmail` → `{html,text}`), Layout-Primitives, Theme-Tokens | **als-vorlage** — Muster für die Notification-Email-Templates (Lead/Task/Termin/Auth/Subscription) aus Locale-Files (LP-12). |
| Worker-Infra: `apps/worker/src/queues.ts` (`defaultWorkerQueueNames` enthält `notifications`), `handlers.ts` (`HandlerDependencies` DI-Seam für notification), `outbox/event-router.ts` (`notification.`-Prefix → Queue), `@toolctrl/queue` `buildNotificationJob`/`enqueueJob`/`queueNames.notifications` | BullMQ-`notifications`-Queue + Transactional-Outbox-Routing + Retry/Backoff-Fundament | **1:1 / anpassen** — Block J Versand-Pipeline (Producer→Queue→Worker→Status-Tracker), Retry-Logik (3x Backoff) ist BullMQ-Standard. Bundle-Manager + Quiet-Hours-Resolver + Pro-User-Push-Limit (10/h) sind neu zu bauen. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/mobile/src/pushRegistration.ts` + `capacitor.config.ts` (Plugin `push-notifications`, `local-notifications`) | Capacitor-Push-Token-Registration gegen `/v1/devices/register`, idempotenter Boot | **1:1** — Block H Registrierungs-Flow (Modul 36). Apple-Compliance-Pre-Prompt-Teaser-Screen (LP-8) fehlt und ist im Mobile-Modul zu bauen. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/modules/notifications/services/.server/NotificationService.ts` | Modul-Service mit BullMQ-`notifications`-Queue-Enqueue + **Novu-API-Anbindung** (`novuApiFetch`, `NOTIFICATIONS_NOVU_API_KEY`), Subscriber/Message/Integration-DTOs | **als-vorlage / anpassen** — bestätigt Spec-Wahl „Novu als Abstraktions-Schicht" (Block B.3). ACHTUNG: `.server.ts`-Re-Export ist projektverboten (User-Memory) → Component-Extraktion statt Re-Export. |
---
## Vorhandene Daten-Modelle
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/notifications.prisma`:
### `NotificationDelivery` (`:14`)
- Felder: `id`, `createdAt`, `updatedAt`, `tenantId?`, `userId?`, `channel` (Enum), `category` (String), `messageKey`, `sourceKey?`, `status`, `attemptsMade`, `providerMessageId?`, `lastError?`, `payloadMetadata Json?`, `sentAt?`, `readAt?`
- Indizes: `(tenantId,userId,status)`, `(tenantId,channel,category)`, `(status,updatedAt)`, `(providerMessageId)`; **`@@unique([tenantId,userId,channel,sourceKey])`** (Idempotenz-Upsert)
- **Lücke vs. Spec-`Notification`:** kein `title`, `body`, `deeplink`, `event_type`, `event_subject_type/id`, `actor_user_id`, `actor_kind`, `priority`, `dismissed_at`, `bundle_id`, `delivery_status pro Kanal` (hier 1 Row pro Channel statt 1 JSONB). Ist eher eine *pro-Kanal-Delivery-Zeile* als das reiche *Notification-Aggregat* der Spec.
### `UserNotificationPreference` (`:41`)
- Felder: `id`, `tenantId`, `userId`, `channel` (Enum), `category` (String), `enabled` (Bool); `@@unique([tenantId,userId,channel,category])`
- **Lücke vs. Spec-`NotificationPreference`:** kein `priority_threshold`, kein PUSH-Channel (Enum nur IN_APP/EMAIL), `category` ≠ `event_type`-Katalog, kein Rolle-Default-Seeding.
### `DeviceToken` (`:66`)
- Felder: `id`, `createdAt`, `updatedAt`, `userId`, `tenantId?`, `platform` (`ios|android|web`), `token @unique`, `pushProvider` (`fcm|apns|webpush`), `appVersion?`, `lastSeenAt`, `revokedAt?`
- Indizes: `(userId,tenantId)`, `(tenantId,platform)`, `(revokedAt)`
- **Sehr nah an Spec-`NotificationDevice`** — fehlt nur `device_label`, `os_version` (separat von appVersion). `device_kind` = `platform`, `revoked_at` = `revokedAt`, `last_seen_at` = `lastSeenAt`. Quasi 1:1.
### Enums
- `NotificationDeliveryStatus`: `PENDING | SENT | FAILED | SKIPPED | READ` (passt grob, Spec hat granularere `delivery_status` pro Kanal als JSONB — z.B. `bounced`, `skipped:user_preference`, `failed:smtp_timeout`)
- `NotificationPreferenceChannel`: `IN_APP | EMAIL` — **`PUSH` fehlt** (obwohl DeviceToken + Push-Worker existieren). Konzeptioneller Bruch zwischen Preference-Enum und Push-Fähigkeit.
**FEHLENDE Modelle komplett (Spec Block A):** `Notification` (reiches Aggregat), `NotificationBundle` (Anti-Spam), `NotificationQuietHours` (Ruhezeiten). Diese existieren in der Boilerplate **nicht**.
---
## Lücken / komplett neu zu bauen
**Daten-Layer (neu):**
- `Notification`-Aggregat mit title/body/deeplink/event_type(Enum)/event_subject/actor/actor_kind/priority/dismissed_at/bundle_id/metadata + `delivery_status` JSONB pro Kanal (Spec Block A)
- `NotificationBundle`-Modell (event_type_group, count, subject_summary, bundle_window_seconds, closed_at) — **kein Pendant** in BP
- `NotificationQuietHours`-Modell (weekday, start/end, urgent_override, enabled) — **kein Pendant** in BP
- `PUSH` als dritter `NotificationPreferenceChannel`-Enum-Wert + `priority` + `priority_threshold`
- M22-Index `(tenant_id, recipient_user_id, created_at DESC)` und Unread-Count-Index — die BP-Indizes sind delivery-zentriert (status/channel/category), nicht ideal für das Center-Default-Query
**Domänen-Logik (neu / erweitern):**
- **Bundle-Manager mit Sliding-5-Min-Window** (BP `bundleNotifications` gruppiert nur statisch, kein Zeitfenster, kein Counter, kein 100-Max, kein Schließen-nach-5-Min)
- **Quiet-Hours-Resolver** (Send/Queue/Hold-Entscheidung pro Kanal; Urgent-Override; Queue-bis-Ruhezeit-Ende) — komplett neu
- **Priority-Pipeline** (urgent nie gebündelt; priority_threshold pro Preference) — komplett neu
- **Pro-User-Push-Limit 10/h** (Anti-Storm, M117) — neu
- **Email-Bounce-Pause-Logik** (7-Tage-Pause + Klartext-Hinweis im Center) — neu
- **Override-Hierarchie** (Channel-Stumm > Ruhezeit > User-Default > Channel-Default, §22.3.6) — neu
- **Default-Preference-Sets pro Rolle** als deklarative Templates (Vertriebler/PL/Monteur/Büro/GF/Marketing, LP-3) + Onboarding-Seeding — neu
- **Event-Typen-Katalog** (Enum/Registry über alle Producer-Module, Block I) — neu, wächst modulweise
- **Anomalie-/Rate-Limit-Detection** für Notification-Storms (AV #16) — neu
**UI (neu / stark erweitern):**
- **M115:** Reiches Notification-Center (Tabs Alle/Ungelesen/Markiert, Filter Event-Typ/Actor/Zeitraum/Priority, Suche, Bulk-Auswahl + Bulk-mark-read/clear mit >50-Bestätigung, Bundle-Expand „Alle anzeigen", Deeplink-Klick→mark-read, Actor-Avatar, Priority-Marker, Unread-Badge in Glocke, Tab-Title-Count). BP-Center ist Diagnostik-Liste — Umbau nötig.
- **M116:** Präferenz-Editor nach Modul gruppiert (3 Toggles + Priority-Threshold pro Event-Typ, Master „Alle Email aus", Reset-auf-Default, Default-Set-anwenden, Search). Quiet-Hours-Editor (Wochentag-Picker, Time-Picker, Urgent-Override, Master-Toggle, Konflikt-Hinweis). Geräte-Liste (Test-Push, Umbenennen, Revoke, Bulk-Revoke, Status-Marker, Empty-State App-Store-Link). **Alle drei UI-Flächen fehlen** (BP hat nur den minimalen Channel/Category-Toggle).
- **`/admin/notifications/templates`** read-only Email-Template-Anzeige + **`/admin/notifications/test`** Test-Notification-Werkzeug (Permission `notifications.admin`). BP-`admin/notifications/*` ist ein anderes Konzept (Novu-Operator-CRUD: channels/messages/subscribers) — als Inspiration, nicht direkt.
**Querschnitt-Wiring (HiveGrid-spezifisch, neu):**
- Sidebar-Eintrag in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (Gruppe gemäß INTEGRATION-CONTRACTS §1: „Notification-Center (Glocke) → M115-M117") — die BP-Sidebar/`sidebar.config.ts` existiert in HiveGrid noch nicht (neue Struktur lt. AGENTS.md)
- `@hivegrid/notifications` `notify()`-Fassade gemäß INTEGRATION-CONTRACTS §7 (mit `priority`, `category`, `template`, `payload`) — BP-`notify()` ist die Vorlage, aber die §7-Signatur (recipientId/template/priority) weicht ab
- View-Model-Layer in `packages/view-models/**` (pure) + Adapter `packages/ui-hivegrid/src/adapters/` für die Subframe/BP-Components (AGENTS.md A-Disziplin)
- Permission `notifications.admin` + Self-Scope-404-statt-403 (Spec Block K)
- Feature-Flag (M006) + Smoke/Visual/Hot-Swap-Tests (M016/M017) + i18n-Keys (M003)
- Sicherheits-Versand-Failures → Modul-21-Audit (AV #6)
**EU-Stack / Provider-Setup (Operator):**
- Novu Self-Hosted auf Scaleway (BP nutzt `api.novu.co` Cloud — für LP-13 auf EU-Self-Hosted umstellen)
- EU-SMTP-Provider-Config (MailerSend EU / Resend EU / Scaleway) — BP-MailerSend ist Region-konfigurierbar
- APNs/FCM-Credentials (`FCM_SERVICE_ACCOUNT_JSON`, `APNS_KEY/KEY_ID/TEAM_ID/BUNDLE_ID`) — Worker-Boot liest sie bereits
---
## Empfohlenes Vorgehen
**Phase 0 — Datenmodell-Fundament (vor M115):**
1. `DeviceToken` quasi 1:1 übernehmen, nur `device_label` + `os_version` ergänzen.
2. `NotificationPreferenceChannel` um `PUSH` erweitern; `UserNotificationPreference` um `priority_threshold` ergänzen.
3. Neues reiches `Notification`-Aggregat + `NotificationBundle` + `NotificationQuietHours` als Forward-Only-Migration anlegen (Inverse-SQL als Kommentar, AGENTS.md F.28). Entscheiden: `Notification`-Aggregat zusätzlich zu/ersetzend `NotificationDelivery` — Empfehlung: reiches `Notification` als SSOT, `delivery_status` als JSONB pro Kanal (Spec Block A), `NotificationDelivery`-Diagnostik-Pattern für den Versand-Status weiterverwenden.
**Phase 1 — M115 (In-App-Center):**
4. `@toolctrl/db/src/notifications.server.ts` Lese-Pfade (`getNotificationStreamSnapshot`, `markInAppNotificationDeliveryRead`, Preferences) übernehmen, Schreib-Pfad aufs neue Modell anpassen.
5. SSE-Stack (`packages/realtime` + `notifications-routes.ts` `GET /v1/notifications/stream`) 1:1 übernehmen; Live-`notification.update`-Fan-out über shared-store/Redis-Pub/Sub ergänzen.
6. `NotificationCenter.tsx` + `app.$tenant/notifications.tsx` als Vorlage; aufs reiche M22-Center (Tabs/Filter/Suche/Bulk/Bundle/Actor/Priority) umbauen; via Adapter aus `packages/ui-hivegrid` einbinden (kein Direkt-Import, kein `.server`-Re-Export).
7. Glocke (`NotificationsButton`) übernehmen + Unread-Count-Badge + Tab-Title-Count ergänzen. Sidebar-Eintrag in `sidebar.config.ts` (§1).
**Phase 2 — M116 (Settings + Quiet-Hours + Devices):**
8. `device-tokens.server.ts` + `devices-routes.ts` (auf Self-Scope-Auth umstellen) + Push-Fan-out-Worker übernehmen; Geräte-Verwaltungs-UI neu bauen (Test-Push/Umbenennen/Revoke/Bulk).
9. Präferenz-Editor (Modul-gruppiert, 3 Kanäle + Priority-Threshold + Master-Toggle + Reset) — `settings/notifications.tsx` nur als Action/Loader-Muster.
10. Quiet-Hours-Modell + Resolver + Editor komplett neu; Default-Set-Seeding pro Rolle (deklarative Templates).
**Phase 3 — M117 (Bündelung + Pipeline + Anti-Spam):**
11. BullMQ-`notifications`-Queue + Outbox-Routing + Retry 1:1 nutzen.
12. Bundle-Manager mit Sliding-Window (5 Min, Counter, 100-Max, Close-after-idle) neu — `foundation.bundleNotifications` nur als Daten-Shape-Vorlage.
13. Pro-User-Push-Limit (10/h), Urgent-Bypass, Bounce-7-Tage-Pause, Override-Hierarchie neu.
14. Push-Sender (Novu EU) + Email-Sender (`@toolctrl/mail` + `email-templates`, Tenant-Branding via Modul 31) + In-App-Sender (write + SSE-update) verdrahten; `delivery_status` zurückschreiben.
15. Sicherheits-Failures → Modul-21-Audit; Anomalie-Detection (AV #16).
**Querschnitt durchgehend:** `@hivegrid/notifications`-`notify()`-Fassade als einziger Producer-Einstieg (§7), pure View-Models, i18n-Keys, Feature-Flag, Smoke/Visual/Hot-Swap-Tests, 404-statt-403, Klartext-Empty/Loading/Error-States (AGENTS.md A-F).
@@ -0,0 +1,115 @@
# Boilerplate-Abgleich: M23 — Files / Dokumentenablage
| Feld | Wert |
| --- | --- |
| **Modul-ID** | M23 |
| **Name** | Files / Dokumentenablage |
| **Milestones** | M052 (Datei-Upload), M053 (Speicher-Backend Scaleway), M054 (Permissions/Sharing/Versionierung), M055 (Suche/Tagging/Archivierung) |
| **Block** | Block 2 (CRM-Kern), Pflichtenheft Modul 23 |
| **Reuse-Level** | **medium** |
| **Spec** | `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M23-files.md` |
## Kurzfazit
Die Boilerplate hat ein **reifes Storage-Infrastruktur-Fundament** (`packages/storage`): S3-Adapter (Scaleway-tauglich), Signed-URLs mit SigV4, Tenant-Pfad-Isolation, MIME-Magic-Bytes-Validierung, ClamAV-Anti-Virus-Pipeline (web → queue → worker → quarantine), MIME-Allow-List und Pre-Upload-Scan. Diese decken **Block E (teilweise), J (Storage-Tenant-Check), K (Storage-Architektur) und M052/M053 großflächig** ab.
**Aber:** Das HiveGrid-Fachdomänen-Modell (`File`, `FileVersion`, `FileEntityLink`, das fachliche `FileUploadProgress`/`FileChunk` mit Tenant/Resume/Checksum) fehlt komplett. Die Boilerplate-Modelle `FileObject`/`FileUploadProgress`/`FileChunk` (`core.prisma`) sind **nicht tenant-scoped, nicht versioniert, kein Entity-Link, kein Resume-State** — nur generische Storage-Metadaten. Der komplette **Files-Browser (UI), Versionierung, Entity-Verknüpfung, Preview-/Thumbnail-Generierung und Volltextsuche/OCR** ist neu zu bauen.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/index.ts` | `createS3StorageAdapter` / `createLocalStorageAdapter`, `putObject`/`deleteObject`, `StorageAdapterError` (mit Secret-Redaction), `UploadBody`-Typen | **1:1** — S3-PUT/DELETE auf Scaleway. Bucket-pro-Region passt zur Spec K. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/signed/index.ts` | `createS3SignedUrlAdapter`, `createSignedUploadUrl`/`createSignedDownloadUrl`, Expiry-Clamping (`DEFAULT_MAX_SIGNED_URL_EXPIRY_SECONDS=3600`), `checksumSha256`/`contentLength`-Header | **1:1** — kurzlebige Signed-URLs für Download/Preview (Spec K: keine Public-URLs). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/access/index.ts` | `authorizeStorageObjectAccess` (Tenant-Prefix `tenants/{tenantId}/` Mismatch-Check, blocked/quarantined-Gate), `authorizeStorageUploadConstraints` (MIME-Allow + maxBytes) | **1:1** — Spec K „App-Code prüft storage_key ↔ tenant_id" + Spec E Max-Size + Mime-Block. Pfad-Konvention `tenants/{tenantId}/...` deckt sich exakt mit Spec A/F. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/magic-bytes-adapter.ts` | `createMagicBytesScanAdapter` — synchroner Pre-Upload-Scan: Magic-Bytes vs. declared MIME, Allow-List, Filename-Path-Traversal-/Control-Char-Schutz, SVG-Sonderfall | **anpassen** — Allow-List-Kontexte erweitern (siehe unten). Deckt Spec E „Mime-Typ blockiert" + M052 Format-Whitelist. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/allow-list.ts` | `DEFAULT_ALLOW_LIST` + `resolveAllowList(env)` (env-overridable `STORAGE_SCAN_ALLOWLIST_<CONTEXT>`) | **anpassen** — Kontexte sind aktuell `avatar/mediaLibrary/emailAttachment/formUpload/kbAsset`; ein `files`-Kontext mit der breiteren HiveGrid-Liste (Video/Audio/HEIC/ODF) fehlt. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/clamav-scanner.ts` | `createClamAVStorageScanner` (clamd TCP, `loadObject`-Seam, Reachability-Check, `ClamAVUnreachableError`) | **1:1** — M052 Anti-Virus (ClamAV-EU/self-hosted). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/s3-quarantine.ts` | `createS3StorageQuarantineAdapter` — infizierte Objekte nach `quarantine/`-Prefix kopieren + Original löschen | **1:1** — Sicherheits-Quarantäne für infizierte Uploads. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/index.ts` | `createStorageScanService` (Scanner+Quarantine-Orchestrator), `ScanVerdict`, `StorageScanResult` (clean/infected/error, mit Klartext-Diagnostik) | **1:1** — Worker-Orchestrierung des Post-Upload-Scans. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/integrations/storageService.ts` | `storeFile` (Pre-Scan → PUT → `enqueuePostScan`), `putBufferAsFile`, `deleteFile`, SSRF-sichere `fetchUploadContent`, Provider-Fallback (s3↔local), `StorageScanRejectedError` | **als-vorlage** — fertiges Web-Wiring von Scan+Upload+Fallback; HiveGrid braucht tenant-scoped Variante (Bucket/Key aus `tenant_id`) und Chunked-Upload statt Single-Shot. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/integrations/storageAudit.server.ts` | `auditRejectedUpload(request, context)` — onReject-Callback schreibt `upload.rejected.scan` Audit-Event (PII-frei) | **als-vorlage** — Audit-Pattern für abgelehnte Uploads (Spec AV #6, M002 Klartext). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/scanService.ts` | `createWorkerScanService(env)` — verdrahtet ClamAV-Scanner + S3-Quarantine aus Env, undefined-safe Boot | **1:1** — Worker-Bootstrap des Scan-Service. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/handlers.ts` (queue `fileScan`, ab Zeile 753) | `toolctrl.file-scan`-Handler: ruft `scanService.scanObject`, liefert `scan.clean`/`scan.infected`, Klartext-Diagnostik bei `error` | **als-vorlage** — Vorlage für HiveGrid Scan-Job; muss um Status-Rückschreibung in `File.preview_status`/Scan-Status erweitert werden. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/api/src/storage.ts` | Vollständige **SigV4-Signierung** für S3-Signed-URLs inkl. Adapter-/Signing-Key-Cache (Secret nie roh gecached) | **1:1** — die konkrete Signer-Implementierung für `createS3SignedUrlAdapter`. Direkt für Scaleway nutzbar. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/integrations/fileScanQueue.server.ts` | `enqueueFileScan` (BullMQ-Enqueue für Post-Upload-Scan, no-op ohne `SCAN_QUEUE_ENABLED`) | **1:1** — Enqueue-Helper für den Scan-Job. |
| `prisma/schema/core.prisma` → `FileObject` (Zeile 213) | Storage-Metadaten (`provider/bucket/key` unique, `contentType`, `byteSize`, `checksumSha256`, `publicUrl`, `uploadedAt`, `lastSignedUpload/DownloadAt`, `metadata`) | **als-vorlage** — Feld-Set für das HiveGrid-`File`-Modell; aber **nicht tenant-scoped, keine Versionen, keine Soft-Delete/Tags/Preview** — als Spaltenvorlage, nicht 1:1. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/ui/uploaders/` (`UploadDocument`, `PreviewUploadersDocument`, `MediaItem`), `input/InputMedia.tsx`, `input/InputImage.tsx` | Drag-and-Drop-Dropzone + Base64-Multi-File-Upload + Media-Preview-Modal (i18n-fähig) | **als-vorlage** — UI-Bausteine für Drag-and-Drop. **Achtung:** Base64-Single-Shot, kein Chunked/Resume; in HiveGrid via `packages/ui-hivegrid`-Adapter + Subframe neu zu bauen (Layer-Disziplin AGENTS A). |
| `packages/exports` + Worker `dsgvo-export.ts` | `createS3MultipartUploadSink` (8 MB Multipart, Concurrency 4, Abort-on-fail), DSGVO-Export-Bundle als ZIP/JSON → S3 + Signed-URL + AuditEvent | **als-vorlage** — Spec D „DSGVO-Export (Datei + Metadaten als ZIP)" + Spec C „Download als ZIP" (Bulk). Multipart-Sink hilft bei Chunk-Concat (Spec E Schritt 5). |
| `prisma/schema/core.prisma` → `AuditEvent` (Zeile 55) + Audit-Worker (`audit-event-persist.ts`, `audit-retention.ts`) | Compliance-Audit-Trail-Modell + Persist-/Retention-Jobs | **1:1 (Querschnitt)** — Spec AV #6 / Block I Audit-Default. |
---
## Vorhandene Daten-Modelle (Boilerplate)
Quelle: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/core.prisma`
- **`FileObject`** (Zeile 213) — generische Storage-Objekt-Metadaten. **Nicht** tenant-scoped, **keine** Soft-Delete/Versionen/Tags/Preview/Entity-Links. → Feldvorlage für HiveGrid-`File`, **kein** Ersatz.
- **`FileUploadProgress`** (Zeile 195) — `id, fileName, progressServer, progressStorage, url, error, chunks[]`. **Deutlich dünner** als Spec A: **kein** `tenant_id`, `created_by_user_id`, `total_size_bytes`, `total_chunks`, `received_chunks`, `expires_at`, `status`-Enum, `target_file_id`, `target_version_intent`. → Konzept gleich, Felder fast komplett neu.
- **`FileChunk`** (Zeile 205) — `id (Int autoincrement), fileUploadId, index, data Bytes`. Speichert Chunk-Bytes **in der DB** (`data Bytes`), nicht im temporären Storage-Bucket wie Spec A (`storage_key`). **Kein** `tenant_id`, `checksum_sha256`, `size_bytes`, `received_at`, **kein** `(upload_id, chunk_index)`-Unique. → Architektur-Abweichung (DB-Bytes vs. Storage-Temp); neu zu modellieren.
- **`AuditEvent`** (Zeile 55) — Compliance-Audit-Trail (Querschnitt, 1:1 nutzbar).
**Nicht vorhanden** (komplett neu): `File` (fachlich, tenant-scoped, soft-delete, RLS), `FileVersion`, `FileEntityLink`.
**Kein passendes Tag/Activity-Modell auf Datei-Ebene:** Tags existieren nur row-scoped im Entity-Builder (`EntityTag`/`RowTag` in `entityBuilder.prisma`) — nicht das HiveGrid-Tag-System (M044) und nicht der zentrale Activity-Stream (M045). Beides ist HiveGrid-Eigenbau, auf den M23 nur referenziert.
---
## Lücken / komplett neu zu bauen
### Daten-Layer
- **`File`-Modell** (tenant-scoped, soft-delete, RLS) mit `display_name`, `mime_type`, `size_bytes`, `storage_key`, `current_version`, `checksum_sha256`, `preview_status`-Enum, `preview_storage_key`, `assigned_to_user_id`, `tags[]`, `notes`, `archived_at`, `source`-Enum, `created_by_portal_user_id` (Block H). Inkl. Indizes (Default-Sort, Owner, Checksum-Dedupe, **Trigram-Index `display_name`**).
- **`FileVersion`** (append-only, `(file_id, version_number)` unique).
- **`FileEntityLink`** (M:N, `(file_id, entity_type, entity_id)` unique, Index `(tenant_id, entity_type, entity_id)`, `link_role`).
- **Fachliches `FileUploadProgress`/`FileChunk`** mit Tenant, Resume-State, Checksum, Storage-Temp-Pfad (Boilerplate-Modelle reichen nicht).
### Domänen-/Worker-Logik
- **Chunked Upload mit Resume** (5 MB Chunks, max 3 parallel, Init→Stream→Concat→Finalize, Resume nach Reconnect) — Boilerplate kann nur Single-Shot `storeFile`. Multipart-Sink aus `packages/exports` als Concat-Baustein nutzbar.
- **Versionierung** (gleicher Display-Name → V2/V3, Rollback legt neue Version an, Storage-Pfad `…/v{n}/original`) — nicht vorhanden.
- **Preview-Generation** (PDF direkt, **HEIC→JPEG**, **Office→PDF via LibreOffice-Headless**, Video-Thumbnail, Thumbnail für Grid) — **kein** Worker-Job, **keine** Image/PDF/Office-Libs in der Boilerplate (`sharp` nur in pnpm `onlyBuiltDependencies`, **nicht** als Dependency; **kein** `browser-image-compression` trotz M052-Plan-Hinweis; kein libheif/imagemagick/libreoffice/pdf-lib). Komplett neu inkl. Library-Auswahl.
- **Duplikat-Erkennung per Checksum** (Spec E: „Datei existiert bereits…") — `checksumSha256`-Feld + Index vorhanden, Match-Logik + UI-Dialog neu.
- **Transitive Sichtbarkeit / `files.read_own`** (Owner ∨ Assignee ∨ Entity-Link mit Lese-Recht; Materialized-View/Cache-Erwägung) — Permission-Logik komplett neu; `withTenantScope()`/`withPermission()` (M004) als Wrapper.
- **Bulk-Actions** (Tag/Assign/Link/Archive/ZIP-Download/Hard-Delete) — neu.
- **Cleanup-Jobs** (expired Chunks täglich, Hard-Delete-Cascade Storage, Orphan-Reconciliation wöchentlich) — neu (Cron-Pattern wie `audit-retention.ts`/`dsgvo-grace-cron.ts` als Vorlage).
- **OCR + Volltextsuche** (M055; Tesseract Phase 1) — neu; Such-Index-Registrierung via M056/`indexed-entities`.
### Permissions
- **Bundle `files.none/read_own/read_all/write/delete/admin`** (Spec J Variante 2) — neu; HR-Sonderfall (`user`-Entity folgt HR-Hub M14).
### UI (komplett neu in `packages/ui-hivegrid` + Subframe via Adapter)
- Files-Browser (Tabelle/Grid umschaltbar, Filter, Bulk, Cursor-Pagination, Spalten-Config, Thumbnail-Lazy-Load).
- File-Detail (Preview-Viewer PDF/Bild-Zoom/Office/Video/Audio, Inline-Edit, Verknüpfungs-Verwaltung mit Auto-Complete, Versions-Sektion).
- Upload-View (Drag-and-Drop, Multi-File-Queue, Chunked-Progress mit Klartext + ETA, Resume) — Boilerplate-Dropzone nur als Vorlage.
- Embedded Files-Browser (vorgefiltert) in Detail-Views von Kontakt/Firma/Deal/Projekt/Lead/Auftrag (Spec B / Pflichtenheft 23.7.4).
- Versionsverlauf-Sub-View.
### Querschnitt-Wiring (HiveGrid-Eigenbau, M23 referenziert nur)
- Activity-Stream-Integration (`logActivity`, Activity-Typen `file_uploaded`/`file_version_added`/`file_link_*`/`file_archived`/`file_renamed`/`file_deleted`) — M045.
- Tags-Wiederverwendung — M044.
- Notifications via `notify()` — M011.
- Feature-Flag-Schaltbarkeit — M006.
- Sidebar-Eintrag „Dateien" — `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (INTEGRATION-CONTRACTS §1, Gruppe gem. Sidebar-Baum, Zeile 25).
- Mobile Offline-Foto-Upload (IndexedDB-Queue, LP-8) — Modul 36 / M170, nicht in Boilerplate.
---
## Empfohlenes Vorgehen
**Reihenfolge — zuerst BP-Infrastruktur verdrahten, dann Fachdomäne, dann UI:**
1. **M053 (Storage-Backend) zuerst-nah verdrahten:** `@toolctrl/storage` als Workspace-Dep einziehen. S3-Adapter + Signed-URL-Adapter (`apps/api/src/storage.ts`-SigV4 als Signer) auf Scaleway konfigurieren. `authorizeStorageObjectAccess` als verbindlichen Tenant-Pfad-Gate (`tenants/{tenantId}/files/{fileId}/v{n}/original`) übernehmen — **1:1**.
2. **M052 Anti-Virus + MIME-Whitelist:** ClamAV-Scanner + Quarantine + `createStorageScanService` + `file-scan`-Worker-Handler **1:1/als-vorlage** übernehmen. **Allow-List um `files`-Kontext erweitern** (Video/Audio/HEIC/ODF/Text/Markdown). `storageService.ts`/`storageAudit.server.ts` als Vorlage für das HiveGrid-Upload-Wiring (tenant-scoped, Audit bei Reject).
3. **Daten-Modell neu bauen:** `File`/`FileVersion`/`FileEntityLink` + fachliches `FileUploadProgress`/`FileChunk` (tenant-scoped, Resume, Checksum). `FileObject`/`AuditEvent` als Feld-/Querschnitt-Vorlage. Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD).
4. **Chunked Upload + Versionierung** (M052/M054): Init/Stream/Concat-Endpoints; Multipart-Sink aus `packages/exports` für Concat; Resume-Logik gegen `FileUploadProgress`. Versionierung + Rollback (neue Version statt In-Place).
5. **M054 Permissions:** Bundle-Engine `files.*` + transitive Sichtbarkeit über `FileEntityLink` (Index nutzen), via `withTenantScope()`/`withPermission()`. HR-Sonderfall an M14 anbinden.
6. **Preview-Generation neu** (eigener Worker-Job, Pattern aus `handlers.ts`): Library-Auswahl finalisieren (sharp/libheif für HEIC, LibreOffice-Headless für Office, pdf/Frame für Video). Status-Rückschreibung in `File.preview_status`. **Höchster Eigenbau-Aufwand, keine BP-Vorlage.**
7. **M055 Suche/Tagging/Archivierung:** Tags via M044, Archivierung (`archived_at`-Soft-Delete + „Archivierte anzeigen"-Toggle), OCR-Pipeline + Such-Index-Registrierung (M056). Cleanup-Jobs (Cron-Pattern aus `audit-retention.ts`).
8. **UI in `packages/ui-hivegrid` + Subframe** (Layer-Disziplin AGENTS A, mandatory Subframe-Design): Files-Browser, Detail, Upload (Chunked-Progress), Versions-Sub-View, embedded vorgefilterter Browser. Boilerplate-Dropzone nur als Funktions-Vorlage. Sidebar-Wiring + Breadcrumb + i18n-Keys.
9. **Querschnitt schließen:** Activity-Stream (M045), Notifications (M011), Feature-Flag (M006), Audit (M001), DSGVO-Export (`packages/exports`-Vorlage). Smoke-Test + Hot-Swap-Drill + Visual-Regression-Snapshot (DoD).
**Achtung-Punkte:**
- BP-`FileChunk` speichert Bytes in der DB (`data Bytes`) — Spec will Chunks im temporären **Storage-Bucket** (`storage_key`). Architektur-Entscheidung früh treffen, BP-Modell nicht blind übernehmen.
- `browser-image-compression` ist **nicht** in der Boilerplate (entgegen M052-Plan-Hinweis) — als Dependency neu hinzufügen oder Server-side-Compression.
- Preview/HEIC/Office-Konvertierung ist der größte Greenfield-Block — frühzeitig spiken (Library + Worker-Timeout).
@@ -0,0 +1,133 @@
# Boilerplate-Abgleich: M24 — Globale Suche
> Faktischer Abgleich der HiveGrid-Detail-Spec (M24) gegen die Boilerplate.
> Boilerplate-Wurzel (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
> Spec-Quelle: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M24-globale-suche.md`
> Alle Pfade absolut. Nichts erfunden — jeder Eintrag verweist auf konkrete Datei(en); fehlt etwas, ist es klar als Lücke markiert.
## Kopf
| Feld | Wert |
| --- | --- |
| Modul-ID | M24 |
| Name | Globale Suche (Cmd+K, hybrid FTS + Embeddings, permission-aware, Adapter-Pattern) |
| Milestones | M056 (Such-Index), M057 (Permission-aware-Search), M058 (Such-UI + Saved-Searches) |
| Block | Block 2 (`_bmad-output/pflichtenheft/blocks/block2.md`, Modul 24) |
| Reuse-Level | **MEDIUM** |
**Kernaussage:** Die Boilerplate hat ein erstaunlich vollständiges **Such-/Embedding-Such-Fundament**: ein tenant-scoped `@toolctrl/search`-Paket (Index-Schemas, Outbox-Publisher, Query-Layer, Sanitize, Fallback-Pfad), den dazu passenden **Search-Indexer-Worker** (Upsert/Delete/Bulk-Reindex über Outbox→BullMQ), die komplette **Embeddings-/RAG-Pipeline** (`@toolctrl/ai/embeddings`) mit EU-Providern (Scaleway 1024-dim — exakter Match zur Spec) und den **pgvector-Store** mit tenant-scoped Wrapper. Außerdem existiert eine funktionierende **Cmd+K-Command-Palette** + `SearchButton` (in der Boilerplate-Web-App). Das Adapter-/Schema-Pattern (`SearchIndexSchema`, `allowedDocumentFields`-Whitelist) ist konzeptuell genau das von der Spec geforderte SearchAdapter-Modell.
**Die zwei großen Architektur-Divergenzen, die das Reuse-Level auf MEDIUM drücken:**
1. **Such-Engine:** Die Boilerplate sucht via **Meilisearch** (`packages/search` → `meilisearch`-SDK). Die HiveGrid-Spec (Block C/H) und der M056-Plan verlangen **Postgres-FTS** (`tsvector`/`tsquery`, deutsche Konfiguration, „kein Extra-Service") + **pgvector**-Hybrid mit **Reciprocal-Rank-Fusion**. → Der FTS-Pfad und die Fusion sind in der Boilerplate **nicht** vorhanden. Es gibt einen SQL-ILIKE-Fallback (`crmContactSearch.server.ts`), aber kein `tsvector`-FTS und keine Hybrid-Fusion.
2. **Daten-Modell:** Die Spec verlangt eine **zentrale `SearchIndexEntry`-Tabelle** (polymorpher Cross-Entity-Index mit `tsvector_de`, `embedding vector(1024)`, `permission_subject` JSONB), plus `RecentSearch` und `EmbeddingProviderJob`. **Keines** dieser Prisma-Modelle existiert in der Boilerplate (verifiziert via Grep über `prisma/schema/*.prisma`). Die Boilerplate hält den Such-Index extern in Meilisearch + die Vektoren in `vec_*`-Tabellen (von pgvector via Raw-SQL angelegt) — kein zentrales Postgres-Index-Modell.
**Wo HiveGrid sich entscheiden muss:** Entweder (A) die BP-Meilisearch-Architektur übernehmen (entgegen Spec/Plan, dafür mehr 1:1-Reuse) oder (B) bei Spec/Plan bleiben (Postgres-FTS) und nur die **Embedding-/Vektor-Hälfte** + Outbox-/Worker-/Adapter-Muster aus der BP übernehmen, den FTS-Pfad + `SearchIndexEntry`-Modell + Fusion neu bauen. Dieser Report bewertet gegen die **HiveGrid-Spec (Variante B)**, weil Memory/Plan-Hinweise (M056: „Postgres FTS bevorzugen — kein Extra-Service") das so vorgeben.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/search/src/schemas/types.ts` | `SearchIndexSchema`-Interface: `name`, `primaryKey`, `searchableAttributes`, `filterableAttributes`, `sortableAttributes`, `rankingRules`, `allowedDocumentFields` (Whitelist gegen PII-Leak) | **als-vorlage** — konzeptuell exakt das **SearchAdapter**-Modell der Spec Block D (welche Felder fließen in den Index). Whitelist-Pattern (`allowedDocumentFields`) = direkte Vorlage für `buildSearchableContent()`. Muss um `buildPermissionSubject()`, `getRouteForEntity()`, `getDisplayMetadata()`, `filterVisibleForUser()` erweitert werden |
| `packages/search/src/schemas/{crm-contacts,users,rows,entities,kb-articles}.ts` + `schemas/index.ts` | Konkrete Index-Schema-Definitionen pro Entity-Typ; `ALL_SEARCH_INDEXES`, `BULK_REINDEX_SUPPORTED_INDEXES`, `getSearchIndexSchema(name)` (zentrale Schema-Registry) | **als-vorlage** — Muster für HiveGrid `indexedEntities`-Map (INTEGRATION-CONTRACTS §8 `packages/db/src/search/indexed-entities.ts`). `crm-contacts`/`users` decken Adapter-Typen `contact`/`user`. Felder/Permission-Keys auf HiveGrid-Schema umsetzen |
| `packages/search/src/outbox-publisher.ts` | `publishSearchUpsertEvent`/`publishSearchDeleteEvent`/`publishSearchBulkReindexEvent`, `searchEventType(entity, verb)` → `search.index.<entity>.<verb>`; `SearchOutboxPublisher`-Interface (dependency-frei, in DB-Transaktion committbar) | **1:1 / anpassen** — exakt das **Outbox-Pattern** der Spec Block H (schreibende Op → Outbox-Eintrag → Worker). Re-Index-Trigger (Insert/Update/Delete/Archiv) der Spec Block D docken hier an. `sanitizeDocument`-Aufruf bleibt; Event-Type-Konvention 1:1 übernehmbar |
| `packages/search/src/sanitize.ts` (`sanitizeDocument`) | Projiziert ein Dokument auf `allowedDocumentFields` (droppt nicht-gelistete Felder vor Index) | **1:1** — verhindert PII-Leak in den Index (Spec AV#5, M057 Field-Level-Redact-Fundament). Direkt für `body_text`-Aufbau wiederverwendbar |
| `packages/search/src/query.ts` | Tenant-scoped Query-Layer: `searchInIndex`, `searchWithFallback`, `bulkIndex`, `deleteFromIndex`, `health`, `TenantScopeError`; `assertTenantId()` erzwingt non-empty Tenant; `buildFilter()` AND-merged tenantId + extraFilters; Filter-Value-Escaping gegen Injection | **als-vorlage** — Tenant-Isolation-Pattern (Spec LP-1, RLS-Äquivalent) + Fallback-Architektur (Spec Block I: „Embedding-Provider-Down → nur FTS"). **Bei Variante B Meilisearch-spezifisch** → Pattern (Tenant-Pflicht, Filter-Escaping, Fallback-Hook) übernehmen, SQL-FTS-Implementation neu schreiben |
| `apps/worker/src/jobs/search-indexer.ts` | Search-Indexer-Worker: konsumiert `outbox.search-index`-Queue, projiziert `upsert`/`delete`/`bulk-reindex` auf den Index; Cursor-Pager für Bulk-Reindex (1000er-Batches), `BULK_PAGER_STALLED`/`BULK_REINDEX_INCOMPLETE`-Guards, Tenant-Mismatch-Check Envelope↔Payload | **als-vorlage** — exakt die **Indexierungs-Architektur** der Spec Block H (Outbox→Worker→Index, 5-10s Latenz). Bulk-Reindex = Initial-Backfill der Spec Block C + Admin-Re-Index (M_search.admin Phase 2). Bei Variante B: Index-Ziel von Meilisearch auf `SearchIndexEntry`-Upsert (FTS) + Embedding-Job-Enqueue umbauen |
| `apps/worker/src/jobs/search-indexer-bootstrap.ts` + `search-indexer-bulk-pagers.ts` | Worker-Bootstrap (Queue-Worker verdrahten) + Bulk-Pager-Registry pro Index | **als-vorlage** — Worker-Wiring-Muster |
| `apps/worker/src/outbox/{event-router,dispatcher,bootstrap}.ts` | Outbox-Event-Router (mappt `search.index.*` auf BullMQ-Queue `outbox.search-index`) + Dispatcher (liest Outbox-Tabelle, fan-out) | **als-vorlage / anpassen** — generisches Outbox→Queue-Fan-out. HiveGrid braucht eigenes Outbox-Modell (Spec Block H `search_outbox`); das Router-/Dispatcher-Muster ist direkt übernehmbar |
| `packages/ai/src/embeddings/factory.ts` + `embeddings/types.ts` | `createEmbeddingProvider()`, `registerEmbeddingProviderAdapter()`, `resolveEmbeddingProviderName(env)` (Default-Reihenfolge), `resolveEmbeddingDimensions(env)`; `EmbeddingProvider`-Interface (`embed`/`embedSingle`/`dimensions`/`maxBatchSize`), typisierte `EmbeddingProviderError` | **1:1** — Spec Block C Embedding-Generation-Fundament. Multi-Provider-Fallback-Architektur (Spec AV#13) |
| `packages/ai/src/embeddings/providers/scaleway.ts` | Scaleway-Embeddings-Adapter, Default-Modell `bge-multilingual-gemma2` (**1024 dim**), Batch 64, max 4096 Tokens | **1:1** — Spec Block C: „Embedding-Dimension einheitlich 1024" + EU-Provider (LP-13). Exakter Match. (Spec nennt primär Mistral-embed; Scaleway-Adapter liefert ebenfalls 1024-dim → der von der Spec offen gelassene Dimensions-Punkt ist faktisch auf 1024 entschieden) |
| `packages/ai/src/embeddings/providers/aleph-alpha.ts` | Aleph-Alpha-Embeddings-Adapter (EU, Germany) | **1:1** — Tertiär-Provider der Spec Block C (`alephalpha`) |
| `packages/ai/src/embeddings/embed-and-upsert.ts` | `embedAndUpsert()` — chunked Embed + Upsert in `VectorUpsertSink`; erzwingt `tenantId` im Payload; deterministische `buildChunkId()`; optionale Kostenverfolgung via `executeLLMCall` (capability `embedding`) | **1:1 / anpassen** — Spec Block C Schreibseite (bei Insert/Update → Embedding generieren). Re-Embed-bei-Text-Änderung (Spec Block D Trigger) + `embedding_status`-Pflege (`pending`/`generating`/`ready`/`failed`/`skipped`) andocken |
| `packages/ai/src/embeddings/retrieve.ts` | `retrieveRelevantContext()` — Query embedden, Fan-out über Collections, Rank-Merge (Score-sort + min-Score 0.7, top-K 8); tenant-scoped via `RagRetrievalStore.searchForTenant` | **1:1 / anpassen** — Spec Block C semantischer Pfad. Rank-Merge ist die **halbe Fusion** — der FTS-Pfad + RRF-Gewichtung (70/30) muss ergänzt werden |
| `packages/ai/src/embeddings/chunking.ts` | `splitForEmbedding()`, `countTokens()`, `DEFAULT_CHUNK_TOKENS`/`OVERLAP_TOKENS` | **1:1** — Text-Chunking für `body_text` (lange Inhalte) |
| `packages/ai/src/embeddings/outbox-publisher.ts` | `publishRagUpsertEvent`/`publishRagDeleteEvent`, `ragEventType()` → `rag.index.<entity>.<verb>` (Queue `outbox.rag-index`), Idempotenz via `dispatchKey` | **als-vorlage** — exakt das von der Spec Block C/D verlangte async Re-Embedding-Event-Muster (parallel zum FTS-Outbox). Kann für den Embedding-Teil des Such-Index 1:1 als Vorlage dienen |
| `apps/worker/src/jobs/rag-indexer.ts` + `rag-indexer-bootstrap.ts` | RAG-Indexer-Worker: konsumiert `outbox.rag-index`, chunk+embed+upsert / delete-by-source; tenant-scoped, provider-agnostisch | **als-vorlage** — exakt die **asynchrone Embedding-Generation** der Spec Block C (Worker holt Eintrag, baut Text, ruft Provider, persistiert). Ziel-Sink von `vec_*`-Tabelle auf `SearchIndexEntry.embedding` umlenken; Retry-Backoff (Spec: 3 Versuche → `failed` mit `last_error_text`) ergänzen (`EmbeddingProviderJob`) |
| `packages/vector-store/src/factory.ts` + `adapters/pgvector.ts` | `createVectorStore()` (pgvector Default / Qdrant Upgrade), `PgvectorAdapter` über `PrismaLike` (`$queryRawUnsafe`), legt `vec_<ns>_<collection>`-Tabellen + **HNSW-Index** an, Payload-Filter via `payload ->> 'key'` | **1:1 / als-vorlage** — Spec Block C/H: pgvector + Cosine-Similarity-Index. Spec lässt IVFFlat-vs-HNSW offen, nennt initial IVFFlat; BP-Adapter nutzt **HNSW**. Wenn HiveGrid das `embedding`-Feld direkt auf `SearchIndexEntry` legt (statt separate `vec_*`-Tabelle), ist der Adapter eher **Vorlage** für die SQL-Cosine-Query als 1:1-Drop-in |
| `packages/vector-store/src/wrappers/tenant-scoped.ts` | `withTenantScope()` → `TenantScopedVectorStore`; `searchForTenant()` injiziert `tenantId`-must-Filter zwingend; bare `searchVectors()` wirft | **1:1** — Spec LP-1 Tenant-Isolation für den Vektor-Pfad. „kein Cross-Tenant" built-in |
| `prisma/migrations/20260517085146_04_enable_pgvector/migration.sql` | Aktiviert `pgvector`-Extension in Postgres | **1:1** — Voraussetzung für `SearchIndexEntry.embedding vector(1024)` |
| `apps/web/app/components/ui/commandPalettes/CommandPalette.tsx` + `CommandPaletteDialog.tsx` + `command.tsx` | Cmd+K/Ctrl+K-Command-Palette: Keyboard-Listener (`metaKey\|ctrlKey + k`), Lazy-Loaded Dialog, Context-Provider, `ScopedCommandAction`-Actions | **als-vorlage** — Spec Block E: Cmd+K-Modal mit Auto-Fokus, Keyboard-Navigation, Esc-Schließen. **Achtung:** liegt in der **Boilerplate-Web-App** (shadcn-basiert), NICHT in HiveGrids `packages/ui-hivegrid`. M058-Plan-Hinweis „kbar in Boilerplate-Deps" ist **faktisch falsch** — `kbar` ist nirgends in der BP (verifiziert via Grep über alle `package.json`). Das vorhandene CommandPalette ist die nutzbare Vorlage, NICHT kbar |
| `apps/web/app/services/command-registry/commandRegistry.ts` | `ScopedCommandAction`-Registry (scoped Commands für die Palette) | **als-vorlage** — Muster für Action-Registrierung im Such-Modal (Treffer-Klick → Route via `getRouteForEntity`) |
| `apps/web/app/components/layouts/buttons/SearchButton.tsx` | Such-Anker im Header (`UI_ACTION_IDS.search`, i18n `shared.search`, `onClick`-Trigger) | **als-vorlage** — Spec Block B: „Such-Anker im Header", Mobile-Trigger. UI-Stil ist BP-spezifisch → in HiveGrid neu via Subframe/`ui-hivegrid` |
| `apps/web/app/modules/crm/services/crmContactSearch.server.ts` | Permission-/Tenant-scoped Such-Service mit **Fallback Meilisearch→SQL-ILIKE** (`SEARCH_BACKEND=sql` erzwingbar, transparenter Connectivity-Fallback) | **als-vorlage** — Muster für Service-Layer (View-Model-Aufbau, Fallback-Architektur Spec Block I). Der **SQL-ILIKE-Fallback** ist KEIN `tsvector`-FTS, dient aber als Skelett für den HiveGrid-FTS-Service |
| `apps/web/app/modules/rows/services/rowSearch.server.ts` + `rowSearchOutbox.server.ts` | Generischer Row-Such-Service + Outbox-Anbindung (Domain-Write → Such-Event) | **als-vorlage** — Muster wie ein Domain-Modul seinen Adapter+Outbox verdrahtet (Spec Block D Modul-Registrierung) |
| `packages/queue/src/{names,payloads,producers}.ts` | BullMQ-Queue-Namen, typisierte Job-Payloads (inkl. `ai.embedding`), Producer mit Idempotenz (`buildIdempotentJobId`) | **1:1 / anpassen** — async Embedding-Jobs (Spec Block C `EmbeddingProviderJob`). Eigener Queue-Eintrag `outbox.search-index` ist bereits konventioniert |
| `packages/ai/src/cost/executeLLMCall.ts` | Wrappt Provider-Calls, Token/Kosten-Tracking, Quota-Pre-Check, Outbox-Event `ai.cost.event.persist` | **1:1** — Query-Embedding-Calls (Spec Block C) sollen durch denselben Cost-Wrapper (capability `embedding`), damit Such-Embedding-Kosten ins Pay-as-you-go (M088) fließen |
| `packages/ai/src/cost/spend-cache.ts` / `createSpendCache` + `@toolctrl/shared-store` `createCacheStore` | Cache-Primitive (TTL) | **als-vorlage** — Spec Block C **Query-Embedding-Caching** (24h TTL, Cache-Key SHA256(query+provider_version)). `createCacheStore` (Redis-KV, Cross-Instance-Invalidation) ist das passende Primitive |
---
## Vorhandene Daten-Modelle
**Wichtig:** Für die globale Suche selbst existiert in der Boilerplate **kein einziges Prisma-Modell** (kein `SearchIndexEntry`, kein `RecentSearch`, kein `SavedSearch`, kein `EmbeddingProviderJob` — verifiziert via `grep -rilE "RecentSearch|SavedSearch|SearchIndex|SearchHistory" prisma/schema/`). Die BP hält Such-Daten **außerhalb** von Prisma (Meilisearch-Indexe + pgvector-`vec_*`-Tabellen via Raw-SQL).
Mittelbar relevante / als-Index-Quelle dienende Modelle (Stand BP, ToolCTRL-Schema — NICHT HiveGrid-Entitäten):
| Modell | Pfad | Bezug zur Spec |
| --- | --- | --- |
| `Row` / `RowValue` (Entity-Builder) | `prisma/schema/entityBuilder.prisma` | BP indexiert CRM-Contacts als `Row`s mit `entityName="contact"`; SQL-Fallback scannt `RowValue.textValue`. HiveGrid hat dagegen **dedizierte** Tabellen (Kontakt, Verkaufsfall, …) → BP-Row-Modell ist NICHT 1:1, nur Pattern-Vorlage |
| `AICostEvent` | `prisma/schema/ai.prisma` | Append-only Cost-Log für Embedding-Calls (capability `embedding`) — Such-Embedding-Kosten landen hier. **1:1 nutzbar** als Querschnitt |
| `Outbox`-Modell | `prisma/schema/outbox.prisma` | Generische Outbox-Tabelle, von Dispatcher gelesen. **Als-Vorlage** für `search_outbox` (Spec Block H) |
| `QueueFailedJob` | `prisma/schema/queue.prisma` | DLQ-Spiegel für fehlgeschlagene Jobs — deckt Spec Block C „Provider-Failure → retrying/failed" indirekt (BullMQ-Retry + DLQ) |
| pgvector `vec_*`-Tabellen | via `PgvectorAdapter` Raw-SQL (kein Prisma-Modell) | Vektor-Speicher. HiveGrid-Spec will `embedding` **direkt auf `SearchIndexEntry`** → hier weicht HiveGrid vom BP-Layout ab |
**Fazit Daten-Layer:** Die drei Kern-Modelle der Spec (`SearchIndexEntry`, `RecentSearch`, `EmbeddingProviderJob`) sind **komplett neu** zu bauen. Die `pgvector`-Extension (Migration vorhanden) und das Cost-Event-Modell sind die einzigen direkt nutzbaren DB-Bausteine.
---
## Lücken / komplett neu zu bauen
1. **`SearchIndexEntry` Prisma-Modell + Migration** (Spec Block A) — zentrale polymorphe Cross-Entity-Index-Tabelle mit `tsvector_de` (Generated Column, deutsche FTS-Config), `embedding vector(1024)`, `permission_subject` JSONB, `embedding_status`-Enum, `entity_type`-Enum, GIN-Index (FTS), HNSW/IVFFlat-Index (Cosine), Unique `(tenant_id, entity_type, entity_id)`, RLS. **Existiert nicht in BP.**
2. **Postgres-FTS-Pfad** (Spec Block C/M056) — `tsvector`/`tsquery` mit deutscher Konfiguration, Stemming, Umlaut-Normalisierung, **Trigram-Index** für Fuzzy-Name-Match. BP nutzt Meilisearch + SQL-ILIKE — **kein `tsvector`-FTS vorhanden**.
3. **Hybrid-Fusion (RRF)** (Spec Block C) — Reciprocal-Rank-Fusion / gewichtetes Score-Merging FTS↔Semantik (Default 70/30), plus Boosts (`last_activity_at`, exakter Title-Match, User-eigene Entitäten). BP hat nur einen **einseitigen** semantischen Rank-Merge (`retrieve.ts`), keine FTS↔Vektor-Fusion. **Neu.**
4. **`RecentSearch` Prisma-Modell + Service** (Spec Block G) — pro User letzte 50 Queries, `applied_filters` JSONB, `clicked_entity_*`, Retention (50 / 90 Tage), Privacy (privat pro User, DSGVO-Export, Hard-Delete bei Account-Löschung). **Existiert nicht.**
5. **Saved-Searches** (M058-Plan: bis 5 pro User; Spec: Phase 2) — User speichert Query+Filter unter Namen. **Modell + UI neu.** (Spec markiert als Phase 2, M058-Plan zieht es nach Phase 1 — Klärungs-/Scope-Punkt.)
6. **`EmbeddingProviderJob` Prisma-Modell** (Spec Block A) — Worker-Queue-State (provider, status, attempts, `last_error_text`, completed_at). BP nutzt stattdessen BullMQ-Job-State + DLQ; ein **persistiertes Job-Modell mit Klartext-Error** fehlt → neu (oder bewusst durch BullMQ+`QueueFailedJob` ersetzen).
7. **SearchAdapter-Voll-Interface** (Spec Block D) — BP-`SearchIndexSchema` deckt nur `buildSearchableContent`-Äquivalent (Feld-Whitelist). Es fehlen: `buildPermissionSubject(entity) → JSONB`, `getRouteForEntity(entity) → string`, `getDisplayMetadata(entity) → {icon, badge}`, `filterVisibleForUser(entries, perms) → entries[]`, `triggers`-Liste. **Erweiterung/Neu.**
8. **Permission-aware Server-Side-Filter** (Spec Block F / M057) — `filterVisibleForUser` pro Adapter, server-side **vor** Ausgabe (kein Client-Hiding), Trefferanzahl-Konsistenz (nur erlaubte Treffer), **Field-Level-Redact** für Snippets (M057-Erfolgskriterium: Volume-Wert im Snippet redacten). BP hat nur tenant-scoped Filter + `sanitizeDocument` (Index-Zeit-Whitelist), **kein per-User-Permission-Filter zur Query-Zeit** und **kein Snippet-Field-Redact**. **Neu** (Kern von M057).
9. **`indexedEntities`-Registry für HiveGrid** (INTEGRATION-CONTRACTS §8, `packages/db/src/search/indexed-entities.ts`) — Map `entity → {table, searchable[], permission}`. BP-`ALL_SEARCH_INDEXES` ist die Vorlage, aber auf ToolCTRL-Entitäten gemünzt. **Neu mit HiveGrid-Entitäten** (contact, company, lead, deal, project, order, form_submission, user, file, task).
10. **Domain-Adapter pro HiveGrid-Modul** (Spec Block D, M001/M042-M046 abhängig) — je Adapter für Kontakt/Firma/Lead (M01), Verkaufsfall (M03), Projekt/Auftrag (M04), Form-Submission (M05), User/Mitarbeiter (M14), File (M23), Task (M26). **Komplett neu** (jeweils im Ziel-Modul zu bauen).
11. **Such-UI in `packages/ui-hivegrid`** (Spec Block E, M058 + M015) — Cmd+K-Modal + Vollbild-Such-View (`/{tenant}/search`) als HiveGrid-VM-Component (View-Model vom Loader, keine Server-Imports im UI-Paket, i18n-Keys, Subframe-Adapter). Das BP-CommandPalette ist nur **Vorlage** (anderer UI-Stack/-Paket). **Neu** inkl. Filter-Chips, Tastatur-Navigation, Snippet-Highlight, Recent-Searches-Anzeige, Sortier-Optionen, Cursor-Pagination, Mobile-Vollbild.
12. **Routen + Wiring** — `/{tenant}/search` Route, globaler Cmd+K-Layout-Mount, Header-Such-Anker, Mobile-Tab/Header (INTEGRATION-CONTRACTS §3/§13/§14), Feature-Flag (M006), Audit (M001/M021: Suchanfrage + Trefferanzahl loggen — Spec Block F). **Neu.**
13. **`search_outbox` + Trigger/Outbox-Wiring** (Spec Block H) — HiveGrid-eigenes Outbox-Modell + Re-Index-Trigger auf den Quell-Tabellen. BP-Outbox-Router/Dispatcher ist Vorlage; das HiveGrid-Modell + Verdrahtung an die dedizierten Tabellen ist neu.
14. **Query-Embedding-Cache** (Spec Block C) — SHA256-Key, 24h-TTL. Primitive (`createCacheStore`) vorhanden, die Such-spezifische Cache-Schicht ist neu.
15. **Klartext-Hinweise** (Spec Block I / M002) — alle 7 Fehler-/Hinweis-Texte (keine Treffer, Permission-Reduktion, Embedding-Down-Banner, <2 Zeichen, Indexierungs-Verzögerung, Re-Index-Lauf, Server-Fehler) als i18n-Keys im M002-Catalog. **Neu.**
---
## Empfohlenes Vorgehen
**Phase 0 — Architektur-Entscheid (blockierend, vor M056-Bau):**
- Klären: **Postgres-FTS (Spec/Plan)** vs. **Meilisearch (BP)**. Memory + M056-Plan sagen FTS („kein Extra-Service"). Empfehlung: **bei FTS bleiben**, BP-Meilisearch-Pakete als **Pattern-Vorlage** (Outbox, Schema-Registry, Tenant-Scope, Fallback) statt als Engine nutzen.
- Klären: `embedding` **direkt auf `SearchIndexEntry`** (Spec) vs. separate pgvector-`vec_*`-Tabelle (BP). Spec-Variante reduziert Joins, weicht aber von `PgvectorAdapter` ab → Adapter wird Vorlage für die Cosine-Query.
- Klären: Saved-Searches Phase 1 (M058-Plan) vs. Phase 2 (Spec).
- Klären: `EmbeddingProviderJob`-Tabelle (Spec) vs. BullMQ-Job-State + `QueueFailedJob` (BP-Konvention).
**M056 — Such-Index (zuerst BP-Bausteine übernehmen):**
1. `pgvector`-Migration aus BP übernehmen (1:1).
2. `SearchIndexEntry`-Modell + Migration **neu** bauen (`tsvector_de` Generated Column, GIN-Index, Cosine-Index, RLS).
3. `EmbeddingProvider`-Pakete (`@toolctrl/ai/embeddings` factory/scaleway/aleph-alpha/embed-and-upsert/chunking/retrieve) **1:1** übernehmen (EU-1024-dim ist exakter Match).
4. Outbox-Publisher + Search-Indexer-Worker + RAG-Indexer-Worker als **Vorlage** übernehmen, Ziel-Sink auf `SearchIndexEntry` (FTS-Felder synchron, Embedding async) umbauen; `EmbeddingProviderJob`-State + Retry-Backoff ergänzen.
5. `indexedEntities`-Registry (HiveGrid) + erste Adapter (Kontakt/Firma/Lead aus M042-M046, da Vorbedingung) bauen.
6. FTS-Pfad (`tsquery` deutsch + Trigram) + Hybrid-Fusion (RRF + Boosts) **neu** — kein BP-Äquivalent.
**M057 — Permission-aware (auf M056 + M004):**
7. `permission_subject`-Befüllung pro Adapter (`buildPermissionSubject`).
8. `filterVisibleForUser` server-side im Query-Pfad (vor Ausgabe), `withTenantScope`-Pattern aus BP als Tenant-Basis, Permission-Filter darauf neu.
9. Field-Level-Snippet-Redact (M057-Erfolgskriterium Volume-Feld) — neu; BP `sanitizeDocument` deckt nur Index-Zeit, nicht Query-Zeit-Redact.
10. Trefferanzahl-Konsistenz + Klartext-Hinweis „weitere Treffer nicht sichtbar" (Schwellwert klären — offener Spec-Punkt).
11. Audit-Wiring (Suchanfrage + Trefferanzahl, M001/M021).
**M058 — UI + Saved-Searches (auf M056/M057 + M015):**
12. Cmd+K-Modal in `packages/ui-hivegrid` **neu** (BP-`CommandPalette` als Interaktions-Vorlage: Keyboard-Listener, Lazy-Dialog, Esc/Focus). **Nicht** kbar (existiert nicht in BP).
13. Vollbild-Such-View `/{tenant}/search` (Filter-Sidebar, Sortier, Cursor-Pagination, URL-State) — neu.
14. `RecentSearch`-Modell + Service (Retention, Privacy, DSGVO) — neu.
15. Saved-Searches (falls Phase 1) — neu.
16. Query-Embedding-Cache (`createCacheStore`, 24h-TTL) — Primitive aus BP, Schicht neu.
17. Klartext-Catalog (Spec Block I) + i18n-Keys; Feature-Flag (M006); Header-Anker + Mobile (BP-`SearchButton` als Stil-Vorlage, neu via Subframe).
**Reihenfolge-Prinzip:** Erst die **EU-Embedding-Pipeline + pgvector + Outbox/Worker-Muster aus der BP** übernehmen (höchster 1:1-Anteil), dann den **FTS-Pfad, das `SearchIndexEntry`-Modell, die Fusion und den Permission-Query-Filter** neu bauen (kein BP-Äquivalent), zuletzt die **HiveGrid-UI** (BP-CommandPalette nur als Vorlage).
@@ -0,0 +1,116 @@
# Boilerplate-Abgleich — Modul M25 (Calendar-Sync)
**Modul-ID:** M25 (Block 5 / Pflichtenheft 25.x)
**Name:** Calendar-Sync (Google + Microsoft, bidirektional)
**Milestones:** M118 (Google+MS via Apps-Engine), M119 (Termin-Sync + Konflikt), M120 (Display + Modul-Verknüpfung + Activity-Stream)
**Block:** block5.md §§ 25.1–25.7 (+ Phase-2 25.8)
**Reuse-Level:** **low**
> Begründung Reuse-Level: Es gibt in der Boilerplate **keinen** Calendar-, OAuth2-Connect-, Google-Calendar- oder Microsoft-Graph-Code und **kein** zugehöriges Datenmodell. Die fünf fachlichen Kern-Entitäten (`CalendarConnection`, `CalendarEvent`, `CalendarEventMapping`, `CalendarSyncCursor`, `CalendarWebhookEvent`), das `CalendarAdapter`-Interface, der bidirektionale Sync, das Webhook-Push-Subsystem und die Verfügbarkeits-Berechnung müssen komplett neu gebaut werden. Was vorhanden ist, ist **Querschnitt-Fundament** (Token-Verschlüsselung, SSRF-Schutz, Outbox/Queue/Cron, Notifications, Audit, Adapter-Registry, Webhook-HMAC-Verify, EU-Provider-Pattern) — solide, aber nur Bausteine, kein fertiges Modul. Damit klar über „none", aber nicht „medium".
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `packages/foundation/src/adapters.ts` | `defineAdapter()` / `getAdapter()` + `AdapterStatus` (`not_configured`/`configured`/`healthy`/`degraded`/`unavailable`) | als-vorlage — Registry-Muster für das `CalendarAdapter`-Interface (Block G). Das vorhandene `AdapterDefinition` ist generisch (`key`/`status`/`adapter`); die calendar-spezifische Methoden-Signatur (`initiateOAuth`/`fetchEventsDelta`/`createEvent`…) ist neu zu definieren. Status-Enum 1:1 nutzbar für Connection-Health. |
| `apps/web/app/utils/api/.server/CryptoApi.ts` | AES-256-GCM `encrypt`/`decrypt` (versionierter Payload `version:iv:tag:ciphertext`), Key via Hash | anpassen — direktes Vorbild für `oauth_refresh_token`/`oauth_access_token` at-rest (Block C, Token-Storage). Spec verlangt envelope-encryption mit tenant-spezifischem KMS-Schlüssel — CryptoApi ist single-key; für Tenant-Key/KMS erweitern. |
| `apps/web/app/utils/leads/marketingIntegrations.db.server.ts` | `encryptSensitive`/`decryptSensitive` über `SENSITIVE_KEYS` + `CRYPTO_TAG`-Präfix; „Admin-UI zeigt entschlüsselte Secrets nie erneut" | als-vorlage — exakt das Pattern für selektiv verschlüsselte Token-Felder in `CalendarConnection` + Never-Redisplay-Regel (Block C: „Logging niemals Token-Klartext"). |
| `packages/foundation/src/outbound-http.ts` (Subpath `@toolctrl/foundation/outbound-http`) | `fetchOutboundHttpWithRedirects`, `validateOutboundHttpUrl`, SSRF-Block (private/internal IPv4+IPv6, DNS-Resolve, Redirect-Limit, Timeout, Response-Size-Limit) | 1:1 — für jeden ausgehenden Provider-Call (Google/MS Token-Endpoint, Calendar-API, Webhook-Subscribe). Pflicht-Querschnitt. |
| `packages/api-client-ts/src/webhooks.ts` + `apps/api/src/webhooks/mailersend-signature.ts` | HMAC-SHA256-Verify mit `timingSafeEqual`, Timestamp-Toleranz, Header-Parsing (`webhook-signature`), typisierte Failure-Codes | als-vorlage — Vorbild für `verifyWebhookSignature(headers, body)` (Block G/E). Provider-spezifisch anzupassen (Google `X-Goog-Channel-Token`, MS `clientState`) — nicht HMAC, aber Verify-Struktur (constant-time, fail-closed, Failure-Codes) übernehmbar. |
| `packages/db/src/outbox.ts` + `prisma/schema/outbox.prisma` (`OutboxEvent`) | `publishOutboxEvent(tx, args)` in `$transaction`, `dispatchKey @unique` (Idempotenz), `eventType`-Pattern `<domain>.<entity>.<verb>` | 1:1 — Webhook-Empfang → DB-Write → async Verarbeitung (Block E, Schritt 3-5). `CalendarWebhookEvent` kann eigenständig sein ODER über Outbox laufen; Outbox-Idempotenz (`dispatchKey`) deckt „Provider duplizieren Notifications" (Block E Idempotenz) ab. |
| `apps/worker/src/outbox/event-router.ts` (`DEFAULT_OUTBOX_ROUTING`) | Prefix→Queue-Routing (longest-prefix-wins) | anpassen — neuen Prefix `calendar.` (z.B. `calendar.sync.*`) ergänzen, auf eine Worker-Queue routen. |
| `packages/queue` (`enqueueJob`, `buildIdempotentJobId`, Prioritäten) + `apps/worker` (Handler-Registry, Cron-Scheduler `*-cron.ts`, Gruppen/Concurrency) | BullMQ-Wrapper + single-instance Cron-Scheduler-Muster (`dsgvo-grace-cron.ts`, `lead-stale-trigger.ts`, `ai-cost-*-cron.ts`) | als-vorlage — (a) Sync-Worker (Webhook-Delta-Pull), (b) **Webhook-Subscription-Renewal-Cron** (Block E: alle 6h, Subscriptions die in 24h ablaufen). Cron-Job-Skelett + Idempotenz direkt übernehmbar. |
| `packages/foundation/src/notifications.ts` (`notify`, `bundleNotifications`, `assertI18nKey`, `NotificationPreferenceChannel` IN_APP/EMAIL) + `prisma/schema/notifications.prisma` | Tenant-pflichtige Notifications mit Preference-Check, Upsert per `sourceKey`, Bündelung | 1:1 — Konflikt-Notifications (Block F), Verbindungsfehler-Mails (Block C Re-Connect), „externe Version gewinnt"-Hinweis. INTEGRATION-CONTRACTS §7 verlangt ohnehin `notify()` statt Direkt-Mail. |
| `packages/foundation/src/audit.ts` (`auditEvent`, `withAuditMiddleware`) + `prisma/schema/core.prisma` (`AuditEvent`, Hash-Chain) | Audit-Trail mit Tamper-Evidence | 1:1 — Connect/Disconnect/Konflikte (AV #6, Spec „Audit-Trail-Default"). Da OAuth-Connect/Webhook-Calls außerhalb Prisma laufen, **manuelles** `auditEvent` nötig (INTEGRATION-CONTRACTS §6 Ausnahme). |
| `packages/foundation/src/permissions.ts` (`withTenantScope`, `withPermission`, `withOwnerCheck`, `requirePermission`; 404-statt-403) | Tenant-Scope + Permission- + Owner-Gating | 1:1 — `calendar.connect_own` (Owner-Check `connection.user_id = self`) + `calendar.admin` (Block I). Permission-Denied → 404 deckt Bauprinzip A.5.3 / DoD ab. |
| `prisma/schema/permissions.prisma` (`Role`/`Permission`/`RolePermission`/`UserRole`) | RBAC-Fundament | als-vorlage — die zwei atomaren Permissions + Bundles (Block I) sind neu zu seeden; das Modell trägt sie. HiveGrid-seitig `packages/entitlements/src/permissions.ts` (INTEGRATION-CONTRACTS §10). |
| `packages/foundation/src/idempotency.ts` (`withIdempotency`) + `prisma/schema/core.prisma` (`IdempotencyKey`) | Replay-sichere Mutationen, In-Process-Lock, Fingerprint-Hash | anpassen — für Webhook-Verarbeitung + Create/Update-Push (Optimistic-Locking-Ergänzung, Block F). |
| `packages/feature-flags` (`evaluateFlag`, Targeting, React-Hooks) + `prisma/schema/featureFlags.prisma` | Feature-Flag-Engine | 1:1 — DoD verlangt „Modul ohne Deploy abschaltbar". Connect-Button + Routes hinter `calendar`-Flag. |
| `packages/i18n` (Namespaces/Locales, `formatDate`/`formatRelativeTime`, `assertI18nKey`) | i18n + locale-explizite Datums-Formatierung | 1:1 — alle Klartext-Hinweise (Block J), Termin-Zeiten in Detail-View. DoD: alle UI-Texte als i18n-Keys. |
| `packages/view-models/src/index.ts` (`VMState`, `ActionCallbacks`, `RegistryGate`, `SidebarRegistryItem`, `ready`/`empty`) | VM-State-Maschine + Shell-Registry-Typen | 1:1 — Loader baut VM, UI empfängt nur VM+Actions (DoD Code-Layer + INTEGRATION-CONTRACTS §11). Loading-/Empty-/Error-State (Klartext-DoD). |
| `packages/foundation/src/errors.ts` (`CatalogError`, `foundationErrors`, `toPinoLogObject`) | Strukturierte Klartext-Fehler (`code`/`status`/`i18nKey`) | als-vorlage — Adapter-Klartext-Codes (Block G: `auth_token_expired`, `rate_limit_exceeded`, `provider_outage` …). Catalog-Einträge sind HiveGrid-spezifisch neu zu registrieren. |
| `packages/logger` (`createLogger` mit Redaction von `token`/`secret`/`apiKey`/`authorization`) | Pino-Logger mit Secret-Redaction | 1:1 — Block C „Logging niemals Token-Klartext" wird durch die eingebauten Redact-Paths abgedeckt. |
| `prisma/schema/notifications.prisma` (`DeviceToken`) + `apps/worker/src/jobs/push-notification.ts` | Push-Token + Push-Versand | 1:1 — Termin-Erinnerungen / Konflikt-Push (Pflichtenheft 22.7.4). Über `notify()` (Kanal-Entscheidung im Notification-Service). |
| `prisma/schema/entityBuilder.prisma` (`EntityView.layout` kennt `"calendar"`) | EntityView-Calendar-Layout-Enum (No-Code-Builder) | als-vorlage (schwach) — nur ein Layout-String, **keine** fertige Calendar-View-Component. Für M120 (Tag/Woche/Monat-Display) liefert die BP keinen Renderer; Component ist neu (Subframe-Design + ui-hivegrid). |
| `apps/api` (Hono-App, `route-access-inventory.ts`, `webhook-signature`-Route-Klasse, `error-envelope`, `request-id`, `body-limit`) | Public-API-Runtime mit Auth-Klassen-Matrix inkl. `webhook-signature` | als-vorlage — die öffentlichen Webhook-Endpoints `/webhooks/calendar/{provider}` (Block E, keine User-Auth, Provider-Signature) passen in die bestehende `webhook-signature`-Route-Klasse + Middleware-Kette. |
| `prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`) | Data-Sync-„Apps-Engine": App-Installation pro Tenant, **`DataConnection.config` = „Encrypted JSON credentials"**, Sync-Run mit `executionMode` manual/scheduled/webhook + Metriken (`itemsProcessed/Created/Updated/Failed`) + Rollback (`AppSyncItem.rolledBackData`) | als-vorlage — **wichtigstes Boilerplate-Modell für M118** (Milestone-Titel: „via Apps-Engine"). `DataConnection` kann die OAuth2-Verbindung tragen ODER als Muster für `CalendarConnection` dienen. `AppSyncRun`/`AppSyncRunLog` ist ein fertiges Sync-Lauf-/Log-Modell (Sync-Status, Konflikt-Logs Block F „letzte 50 Konflikte"). **Aber:** keine Provider-Logik, kein Cursor/Webhook-Modell, kein Event-Cache — nur Hülle. Entscheidung nötig: `appsEngine`-Modelle wiederverwenden vs. dedizierte `Calendar*`-Modelle in `app.prisma`. |
---
## Vorhandene Daten-Modelle (konkrete Prisma-Modelle mit Pfad)
Es gibt **kein** Calendar-spezifisches Prisma-Modell. Nutzbare/angrenzende Modelle:
- `prisma/schema/appsEngine.prisma` — `App`, `DataConnection` (verschlüsselte Credentials), `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`. **Am nächsten** an „Connection + Sync-Lauf + Konflikt-Log". Deckt aber `CalendarEvent`-Cache, `CalendarEventMapping`, `CalendarSyncCursor`, `CalendarWebhookEvent` **nicht** ab.
- `prisma/schema/outbox.prisma` — `OutboxEvent` (`dispatchKey @unique`, Idempotenz, `priority`, `lockedUntil`). Für Webhook→Worker-Entkopplung + Dedup.
- `prisma/schema/notifications.prisma` — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken`. Konflikt-/Fehler-Notifications + Push.
- `prisma/schema/core.prisma` — `AuditEvent` (Connect/Disconnect/Konflikt-Audit), `IdempotencyKey`, `Credential` (globaler Secret-Store, `value Json`).
- `prisma/schema/accounts.prisma` — `User`, `Tenant`, `TenantUser` (User-/Tenant-Anker; pro-User-Connection-Scoping). `WorkspaceAuthProvider` (inbound SSO/OIDC — **nicht** outbound OAuth-Connect, nur als Feld-Vorbild `authorizationUrl`/`tokenUrl`/`clientId`).
- `prisma/schema/permissions.prisma` — `Permission`/`Role`/`UserRole` für `calendar.connect_own` / `calendar.admin`.
- `prisma/schema/featureFlags.prisma` — `FeatureFlag` (Modul-Abschaltung).
- `prisma/schema/app.prisma` — **leerer Platzhalter** (`// custom database models`): vorgesehener Ort für die neuen `Calendar*`-Modelle.
**Neu zu erstellende Modelle (alle, gemäß Spec Block A):** `CalendarConnection`, `CalendarEvent`, `CalendarEventMapping`, `CalendarSyncCursor`, `CalendarWebhookEvent` — in `prisma/schema/app.prisma` (oder eigene `calendar.prisma`). Pflicht: tenant-scoped + RLS, FK auf `User`/`Tenant`, Eintrag in `packages/db/src/dsgvo/user-fk-map.ts` (CI-Gate bricht sonst — DSGVO Block, Spec „Account-Löschung → harte Löschung der Event-Caches").
---
## Lücken / komplett neu zu bauen
**Datenmodell**
- Alle fünf `Calendar*`-Modelle inkl. Indizes/Constraints (Block A) — nicht vorhanden.
- `user-fk-map.ts`-Einträge für die neuen User-FK-Modelle (DSGVO, Pflicht-Gate).
**Provider-Integration (Kern, fehlt vollständig)**
- `CalendarAdapter`-Interface mit allen Methoden (Block G): `initiateOAuth`, `handleOAuthCallback`, `refreshAccessToken`, `listCalendars`, `subscribeWebhook`/`unsubscribeWebhook`/`renewWebhook`, `fetchEventsInitial`/`fetchEventsDelta`, `createEvent`/`updateEvent`/`deleteEvent`, `verifyWebhookSignature`.
- **Google-Adapter** (Calendar API v3, Push-Notification-Channels, `syncToken`, `If-Match`/etag) — neu.
- **Microsoft-Adapter** (Graph Calendar, Subscriptions/`deltaLink`, `clientState`, Azure-AD-Multi-Tenant-App + Admin-Consent-Flow) — neu.
- OAuth2-Connect-Flow Ende-zu-Ende (state-Token signiert mit `tenant_id+user_id`, code↔token-Exchange, User-Info-Fetch) — **kein** outbound-OAuth-Connect existiert (nur inbound SSO/OIDC + ein GitHub-Service `apps/web/app/utils/integrations/githubService.ts`, das als loses Vorbild taugt).
**Sync-Engine (fehlt)**
- Bidirektionaler Sync (Block D): Schreib-Pfad HiveGrid→extern (Booking/Projekt/Plantafel/Tasks-Spiegelung, Mehrfach-Provider-Mappings), Lese-Pfad extern→HiveGrid (Initial-Full-Pull -7/+60, inkrementell via Cursor, „Free"-Filter, Private→„Privat"-Titel-Reduktion).
- Konflikt-Handling Last-Write-Wins-mit-Sichtbarkeit (Block F): 412-Precondition-Failed-Behandlung, „externe Version gewinnt" + Restore-Option, Mapping-Cleanup bei extern gelöschten Events, `last_known_internal_version_token`-Check.
**Webhook-Subsystem (fehlt fachlich)**
- Provider-Webhook-Empfangs-Endpoints `/webhooks/calendar/{provider}` mit Provider-spezifischer Signature-Verifikation (Google `X-Goog-Channel-Token`, MS `clientState`) — generisches HMAC-Verify-Muster vorhanden, aber Provider-Logik neu.
- **Subscription-Renewal-Cron** (Google ~1 Woche, MS ~3 Tage; alle 6h, Renewal in 24h-Fenster) — Cron-Skelett vorhanden, Logik neu.
- 410-Gone → Full-Resync.
**Verfügbarkeits-Berechnung (fehlt, Block H)**
- Slot-Engine: Working-Hours + interne Events + externe Busy-Events + Plantafel → freie Slots; 30-Tage-Slot-Cache mit Invalidierung bei `CalendarEvent`-Update; DSGVO-Filterung (Booking erhält nur `is_available`-Boolean, nie Event-Inhalt). Hängt an Modul 6/M126.
**Querschnitt-Wiring (HiveGrid-seitig neu zu verdrahten)**
- Sidebar-Eintrag „Termine" (Gruppe ARBEITEN, M120) + Settings-Eintrag „Integrationen → Kalender" in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts`.
- Routes (Block B / INTEGRATION-CONTRACTS §3): `settings/integrationen/calendar/...` + Connect/Callback + `:connection_id`-Detail.
- Calendar-Display-Component (Tag/Woche/Monat) für M120 — kein BP-Renderer vorhanden (Subframe-Design Pflicht, siehe Memory `feedback_subframe_mandatory`).
- Activity-Stream-Hooks (`logActivity`): `calendar_connected`/`_disconnected`/`_sync_error`/`appointment_synced_external` — bewusst NICHT pro Event-Update (M120 / INTEGRATION-CONTRACTS §5).
- Off-Boarding-Hook (Block I / Modul 27): User-Deaktivierung → Connections `paused`, Webhooks abmelden; Hard-Delete → Caches hart löschen.
- Tenant-spezifische KMS/Envelope-Encryption für Refresh-Tokens (Spec verlangt Tenant-Key; CryptoApi ist single-key — Erweiterung nötig).
**Anti-Liste (Phase 2, NICHT bauen):** iCal-Feed, Resource-Calendar, Tenant-Zentral-Connection, Apple/iCloud-CalDAV, FastMail, konfigurierbares Sync-Fenster, Multi-Calendar-Settings-UI, Color-Sync, KI-Konflikt-Resolution, erweiterte Zeitzonen, Recurring-Event-Single-Instance-Edits.
---
## Empfohlenes Vorgehen
1. **Querschnitt zuerst aus BP verdrahten (1:1):** `withTenantScope`/`withPermission`/`withOwnerCheck` (Permissions), `notify`/`auditEvent` (Konflikt/Connect-Audit), `VMState`/`ActionCallbacks` (VM-Layer), `i18n`-Keys + `formatDate`, `feature-flags` (Modul-Abschaltung), `outbound-http` (SSRF für alle Provider-Calls), `logger` (Token-Redaction). Permissions `calendar.connect_own`/`calendar.admin` in `packages/entitlements/src/permissions.ts` + seed.
2. **Datenmodell (M118):** Die fünf `Calendar*`-Modelle in `app.prisma`/`calendar.prisma` anlegen (Block A, inkl. Indizes/Unique-Constraints), `user-fk-map.ts` ergänzen, Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD). **Vorab entscheiden:** `appsEngine`-Modelle (`DataConnection`/`AppSyncRun`/`AppSyncRunLog`) wiederverwenden für Connection+Sync-Lauf+Konflikt-Log, oder dedizierte Modelle — `appsEngine` ist die nächste Vorlage, deckt aber Cache/Cursor/Webhook nicht und vermischt zwei „Apps-Engine"-Bedeutungen (siehe Inventur integrations-ki §4.4).
3. **Token-Storage (M118):** `CryptoApi`/`marketingIntegrations`-Verschlüsselungs-Pattern als Vorlage; auf Tenant-Key/KMS-Envelope erweitern (Spec/AV #13). Never-Redisplay-Regel übernehmen.
4. **Adapter-Pattern (M118):** `CalendarAdapter`-Interface (Block G) definieren; Google- und MS-Adapter neu implementieren; Klartext-Fehler-Codes als `CatalogError`-Katalog (Block G/J) registrieren. OAuth-Connect/Callback-Routes über `apps/api`-Webhook/Auth-Klassen-Muster + `outbound-http`.
5. **Webhook + Sync-Worker (M118→M119):** Public Webhook-Endpoints (Provider-Signature-Verify nach `mailersend-signature`-Muster) → `CalendarWebhookEvent`/Outbox (`dispatchKey`-Idempotenz) → BullMQ-Sync-Worker (Cursor-Delta-Pull). `calendar.`-Prefix in `event-router.ts`. Renewal-Cron nach `*-cron.ts`-Muster.
6. **Bidirektionaler Sync + Konflikt (M119):** Schreib-Pfad (Spiegelung Booking/Projekt/Plantafel, Mehrfach-Provider-Mappings), Lese-Pfad (Privacy-Reduktion), Last-Write-Wins-mit-Restore-Option via `notify`.
7. **Verfügbarkeit + Display (M119/M120):** Slot-Engine + Cache (an Modul 6/M126 koppeln); Calendar-View-Component via Subframe neu (kein BP-Renderer); Activity-Stream-Hooks; Sidebar/Route/Breadcrumb-Wiring; Off-Boarding-Hook.
8. **DoD-Schluss je Milestone:** Smoke-Test je Route, Hot-Swap-Drill gegen `ui-mock`, Visual-Snapshot, Permission-Denied→404, Feature-Flag, Customer-Portal-Sichtbarkeit explizit (default NICHT sichtbar).
---
### Quellen-Hinweis
Alle Aussagen direkt in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` verifiziert (Greps auf `calendar|ical|google.?calendar|microsoft.?graph|oauth2|encrypt`, gelesene Dateien: `foundation/src/adapters.ts`, `CryptoApi.ts`, `marketingIntegrations.db.server.ts`, `api-client-ts/src/webhooks.ts`, `mailersend-signature.ts`, `appsEngine.prisma`, `entityBuilder.prisma`, `outbox/event-router.ts`). **Kein** Calendar-/OAuth-Connect-/Provider-Code gefunden.
@@ -0,0 +1,138 @@
# Boilerplate-Abgleich: M26 — Tasks / Aufgaben
| Feld | Wert |
| --- | --- |
| Modul-ID | M26 |
| Name | Tasks / Aufgaben |
| Milestones | M071 (CRUD + Zuweisung), M072 (Listen pro Modul / Inline), M073 (Erinnerungen + Push + Email), M074 (Aufgaben-Sync ERP / KWP) |
| Block | Block 3 · Pflichtenheft §26 (26.1–26.10) |
| Spec | `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M26-tasks.md` |
| **Reuse-Level** | **low–medium** (Querschnitt-Infrastruktur reif; das eigentliche Task-Domänen-Modell muss neu gebaut werden — `RowTask` deckt es NICHT ab) |
> Boilerplate-Wurzel: `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (nur gelesen).
---
## Kern-Befund (Anti-Erfindung)
In der Boilerplate existiert **`RowTask`** (`prisma/schema/entityBuilder.prisma:434`) — aber das ist **NICHT** das HiveGrid-Task-Modul. `RowTask` ist eine **leichtgewichtige Checklisten-Sub-Entität, die fest an eine Entity-Builder-`Row` hängt** (Mini-To-do im Row-Overview), vergleichbar mit `RowComment`/`RowTag`. Es fehlen die zentralen Eigenschaften aus der M26-Spec:
| M26-Anforderung | `RowTask` (Boilerplate) | Lücke |
| --- | --- | --- |
| `tenantId` (direkt am Task, für Tenant-Scope-Filter + Indizes) | fehlt (nur indirekt über `row.tenantId`) | **ja** |
| `status` Enum `open\|in_progress\|done` | nur `completed Boolean` | **ja** (kein In-Arbeit-Status) |
| `priority` Enum `low\|normal\|high\|urgent` | fehlt | **ja** |
| `assigned_to_group_id` (Gruppen-Zuweisung) | nur `assignedToUserId` (Person) | **ja** |
| `source` Enum (`manual\|chat_message\|form_submission\|automation`) + `source_ref` JSON | fehlt | **ja** |
| `linked_entity_type` / `linked_entity_id` (polymorphe Verknüpfung zu Contact/Company/Lead/Deal/Project) | fehlt — Bindung ist hart an `rowId` einer Entity-Builder-Row | **ja** (Architektur-Unterschied) |
| `archived_at` (Auto-Archivierung) | fehlt | **ja** |
| `deadline_at` | vorhanden (`deadline DateTime?`) | nein |
| `completed_at` / `completed_by_user_id` | vorhanden (`completedAt`, `completedByUserId`) | nein |
| `created_by_user_id` | vorhanden (`createdByUserId`) | nein |
| `TaskWatcher` (M:N) | fehlt | **ja** |
| Reminder-Notifications / Auto-Archivierungs-Cron | fehlt | **ja** |
| `tasks.*`-Permissions (read_own/read_all/write/admin) + Owner-Check + 404-statt-403 | fehlt | **ja** |
**Konsequenz:** `RowTask` (Modell + UI `RowTasks.tsx` + Service `rowTasks.db.server.ts`) ist als **Vorlage/Muster** wertvoll (Felder, Service-Layer-Struktur, Event-DTOs, i18n-Keys, Toggle-UI), aber nicht 1:1 übernehmbar. Das HiveGrid-`Task`-Modell ist eine **eigenständige Entität** in `prisma/schema/app.prisma`, kein Anhängsel an Entity-Builder-Rows.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/entityBuilder.prisma:434` (`model RowTask`) | Felder-Inspiration für das neue `Task`-Modell (title, description, completed/completedAt/completedByUserId, assignedToUserId, deadline, createdByUserId) | **als-vorlage** — Feld-Set übernehmen, aber um tenantId/status/priority/group/source/linked_entity/archived erweitern |
| `apps/web/app/utils/db/entities/rowTasks.db.server.ts` | Service-Layer-Muster: `get*/create/update*/delete*/getAll*` mit `include`-Pattern, `getAllRowTasks({ completed, assignedOrCreatedUserId, tenantId })` (Owner-/Filter-Logik) | **als-vorlage** — Repository-Struktur + „assigned OR created"-Owner-Filter direkt übertragbar (entspricht Owner-Check der M26-Spec) |
| `apps/web/app/components/entities/rows/RowTasks.tsx` | UI-Muster: Toggle-Erledigen, Quick-Add (nur Titel), Inline-Delete mit `canDelete`-Permission-Gate, Empty-State, i18n-Keys (`shared.addTask`, `shared.noTasks`, `models.rowTask.plural`) | **als-vorlage** — passt zum „Inline-Aufgaben-Bereich" (M072) + Quick-Add (Block E.1); in HiveGrid via Subframe-Adapter neu zu bauen, Logik-Muster übernehmbar |
| `apps/web/app/modules/events/dtos/RowTasks{Created,Updated,Deleted}Dto.ts` + `apps/web/app/modules/events/utils/EventUtils.ts` (Cases `row.tasks.created/updated/deleted`) | Event-/Activity-DTO-Muster + Klartext-Übersetzung pro Event-Typ | **als-vorlage** — Vorlage für M26-Activity-Typen (`task_created/assigned/completed/reopened/deadline_changed/priority_changed/archived`, Block G) |
| `prisma/schema/notifications.prisma` (`NotificationDelivery`, `UserNotificationPreference`, `DeviceToken`) | Vollständiges Notification-Datenmodell: In-App + Email + Push (APNs/FCM/WebPush), Per-Channel/Category-Präferenzen, `@@unique([tenantId, userId, channel, sourceKey])` (Dedup) | **1:1** — direkt für M073 Reminder-Versand nutzbar (Empfänger = Assignee/Group/Watcher) |
| `packages/db/src/notifications.server.ts` | Notifications-Repository: `createNotificationDelivery`, `markNotificationDeliveryStatus`, `upsertUserNotificationPreference`, `getUserNotificationPreferences`, `getNotificationStreamSnapshot`, `redactNotificationDiagnosticText`; Typen `NotificationPreferenceChannel`/`...DeliveryStatus` | **1:1** — Schreib-/Lese-Fläche für Reminder-Deliveries + User-Toggle „Task-Erinnerungen" (M073, Block F.1) |
| `apps/web/app/modules/notifications/services/.server/NotificationService.ts` | Versand-Service (Novu-Integration, `send`, `sendToRoles`, Channel→Category-Mapping, Skipped-Delivery-Tracking, `withNotificationQueue`) | **anpassen** — als `notify()`-Backend (INTEGRATION-CONTRACTS §7) für Task-Reminder; Bündelung (max 1/4h) muss ergänzt werden |
| `apps/worker/src/jobs/dsgvo-grace-cron.ts` | Cron-Job-Vorlage: BullMQ `upsertJobScheduler` (keine Doppel-Schedules bei Re-Deploy), 24h-Kadenz, host-agnostische Dependency-Injection (`listOverdue…` + `enqueue…` + logger), idempotent | **als-vorlage** — Blaupause für (a) Reminder-Cron 24h-vor/bei/+24h und (b) Auto-Archivierungs-Cron `done + completedAt <= now-30d` (M073, Block F.2) |
| `apps/worker/src/jobs/email-sequence-scheduler.ts`, `outbox-done-retention-cron.ts`, `workflow-execution-stalled-reconciler-cron.ts` | Weitere reife Cron-Beispiele (Scheduler-Pattern, Retention-Sweep) | **als-vorlage** — Retention-Sweep = direktes Muster für Auto-Archivierung |
| `packages/db/src/outbox.ts` (`publishOutboxEvent`) + `prisma/schema/outbox.prisma` (`OutboxEvent`) | Transaktionales Outbox: Side-Effects (Reminder-Schedule, Activity, ERP-Push) atomar mit DB-Write; `dispatchKey @unique` (Idempotenz), `scheduledAt`, `priority` | **1:1** — Pflicht-Muster für alle Task-Side-Effects; `scheduledAt` deckt die 24h-Reminder-Zeitpunkte ab |
| `prisma/schema/permissions.prisma` (`Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser`) | RBAC-Fundament inkl. **`Group`/`GroupUser`** | **1:1** — `Group`/`GroupUser` deckt `assigned_to_group_id` + Owner-Check „Mitglied der zugewiesenen Gruppe" (Block H) ab; `tasks.*`-Permissions als neue `Permission`-Einträge |
| `packages/db/src/client.server.ts`, `transactions.server.ts` | DB-Client (`getDbClient`/`getReadDbClient`/`getExtendedDbClient`), `runDbTransaction` | **1:1** — Fundament für alle Task-Repositories; Read-Replica für Listen-Views |
| `packages/db/src/dsgvo/user-fk-map.ts` | Zentrale User-FK-Karte (Test bricht CI bei fehlendem Eintrag) | **anpassen (Pflicht)** — neue `Task`-FKs (`createdByUserId`, `assignedToUserId`, `completedByUserId`) + `TaskWatcher.userId` müssen hier eingetragen werden |
| `prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`) | Integrations-/Sync-Engine: pro-Tenant `App` (`@@unique([tenantId, type])`), verschlüsselte `DataConnection`-Credentials, Sync-Run mit Status/Modus/Metriken, `AppSyncItem` mit **`sourceId`/`destinationId`-Mapping + `rolledBackData`/`rolledBackAt`** | **anpassen** — Fundament für M074 KWP-Aufgaben-Sync: Source↔Destination-ID-Brücke (KWP-Email-Identifikation), Sync-Modi (manual/scheduled/webhook), Rollback. Sync-Modi A/B/C („KWP gewinnt") sind als Config-/Konfliktregel zu ergänzen |
| `@toolctrl/view-models` (`packages/view-models/src/index.ts`) | `VMState<T>`, `ActionCallbacks`, `I18nLabel`, `assertI18nLabel`, `SidebarRegistryItem`/`RegistryGate` | **1:1** — View-Model-Vertrag (INTEGRATION-CONTRACTS §11) für Task-Listen/Detail; i18n-Key-Zwang |
| `@toolctrl/ui-app` (`createSidebarRegistry`, `EmptyPage`, `generateA11yTest`) | Sidebar-Registry-Factory + a11y-Test-Template | **1:1** — Sidebar-Eintrag „Aufgaben" (Gruppe `arbeiten`) + a11y-Gate |
| `apps/web/app/components/ui/tables/*` (`TableSimple`, `TablePagination`, `ColumnSelector`, `RowsLoadMoreCard`), `components/ui/multi-select.tsx`, `calendar.tsx`, `command.tsx`, `modals/*`, `emptyState`, `loaders` | shadcn/Radix-Komponentenbibliothek: Tabelle + Cursor-Pagination („Mehr laden"), Multi-Select-Filter, Date-Picker, Modale, Empty/Loading-States | **als-vorlage** — deckt fast alle UI-Elemente aus Block C/D ab (Filter, Bulk-Checkboxes, Pagination, Quick-Actions); in HiveGrid via Subframe-Adapter |
| `apps/web/app/application/sidebar/*` + `apps/web/app/components/layouts/sidebars/shadcn/*` | Datengetriebene Sidebar mit Permission-/Feature-Gating, App-Shell (`AppLayout`/`ShadcnSidebarLayout`), Breadcrumb-Header | **als-vorlage** — Muster für HiveGrid-`sidebar.config.ts` + Breadcrumb (INTEGRATION-CONTRACTS §1/§4) |
| `packages/i18n` + `apps/web/app/locale/*` | i18next + SSR (de/en), `formatRelativeTime`/`formatDate` | **1:1** — Deadline-Anzeige „relativ wenn ≤7 Tage" (Block C) + alle Klartext-Texte (Block I/F) als i18n-Keys |
| `prisma/schema/featureFlags.prisma` + `FeatureFlag`-Layer | Feature-Flags (scope tenant/user, Targeting) | **1:1** — DoD-Pflicht „Modul ohne Deploy abschaltbar"; pro-Tenant ERP-Sync-Aktivierung (M074) |
| `prisma/schema/core.prisma` (`AuditEvent`, Hash-Kette) + `packages/db/src/audit-hash.ts` | Tamper-evidenter Audit-Trail | **1:1** — DoD-Audit-Wiring (INTEGRATION-CONTRACTS §6); ERP-Sync-Konflikt-Markierung im Audit (M074) |
---
## Vorhandene Daten-Modelle (konkret)
**Direkt wiederverwendbar (1:1 / Querschnitt):**
- `prisma/schema/permissions.prisma` — `Group`, `GroupUser` (Gruppen-Zuweisung + Owner-Check), `Permission`/`Role`/`RolePermission`/`UserRole` (RBAC für `tasks.*`).
- `prisma/schema/notifications.prisma` — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` (M073 Reminder In-App/Email/Push).
- `prisma/schema/outbox.prisma` — `OutboxEvent` (atomare Side-Effects + `scheduledAt` für Reminder-Timing).
- `prisma/schema/core.prisma` — `AuditEvent` (Audit-Querschnitt), `FileObject` (falls Attachments später).
- `prisma/schema/accounts.prisma` — `User`, `Tenant`, `TenantUser` (Identity/Scope-Anker).
- `prisma/schema/featureFlags.prisma` — `FeatureFlag` (Abschaltbarkeit + ERP-Sync-Toggle).
**Vorlage / nahe verwandt, aber nicht das Task-Modell:**
- `prisma/schema/entityBuilder.prisma:434` — `RowTask` (Checklisten-Sub-Entität an `Row`; Feld-Vorlage, nicht die HiveGrid-`Task`).
**Sync-Fundament (M074):**
- `prisma/schema/appsEngine.prisma` — `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (ID-Brücke + Rollback für KWP-Aufgaben-Sync). Konkrete KWP-Sync-Foundation (M089–M095) ist Vorbedingung und liegt außerhalb dieses Moduls.
**Platzhalter für Neu-Modelle:**
- `prisma/schema/app.prisma` — leerer Platzhalter (`// custom database models`), vorgesehener Ort für `Task` + `TaskWatcher` (+ ggf. `TaskSyncLink` für M074).
---
## Lücken / komplett neu zu bauen
1. **`Task`-Prisma-Modell** (neu, in `app.prisma`): alle Felder aus Block A inkl. `tenantId`, `status`-Enum, `priority`-Enum, `source`/`source_ref`, `linked_entity_type`/`linked_entity_id` (polymorph), `archived_at`, `assigned_to_group_id`. Plus die 4 Indizes aus Spec Block A. Plus die Constraints (oneOf Assignee, completed-Felder nur bei `done`, Reset bei `done→open`).
2. **`TaskWatcher`-Modell** (neu, M:N User↔Task) — existiert nirgends.
3. **`tasks.*`-Permissions + Bundle-Mapping** (Block H): `tasks.read_own/read_all/write/admin` als neue `Permission`-Einträge + Owner-Check-Logik (Assignee OR Group-Member OR Creator OR Watcher) + 404-statt-403. Muss neu (RBAC-Fundament vorhanden, Keys nicht).
4. **Listen-View mit Server-Side-Filter** (Block C): Scope-Presets (`mine`/`created_by_me`/`all`), Multi-Select-Filter (Status/Priorität/Quelle/Verknüpfungs-Typ), Date-Range mit Presets, Volltext-Suche (Titel+Beschreibung), Sortierung, Bulk-Actions, Cursor-Pagination. UI-Primitives vorhanden, die Verdrahtung + VM-Builder neu.
5. **Detail-View mit Inline-Edit** (Block D): Markdown-Editor, Assignee-Picker (Person ↔ Group umschaltbar), Entity-Picker (Auto-Complete Contact/Company/Lead/Deal/Project), Status-Wechsler, Duplizieren, Watcher-Verwaltung, Aktivitätsstrom. Neu.
6. **Polymorphe Entity-Verknüpfung + Embed-Anzeige** (Block B/C, M072): Tasks-Tab/Section in Contact/Company/Lead/Deal/Project-Detail-Views mit Pre-Fill. `RowTask`-Modell kann das architektonisch NICHT (hart an Entity-Builder-`Row`) — neu zu bauen.
7. **Erstellungs-Quellen-Integration** (Block E, M072): „Mark as Task" aus Team-Chat (M110–M114), Form-Action „Aufgabe erstellen" (M121–M125), Automation-Action (M075–M082). Abhängig von Modulen, die teils noch nicht existieren. Quell-DTO-Muster aus `events/dtos/RowTasks*` als Vorlage.
8. **Reminder-Logik** (M073, Block F.1): Cron 24h-vor/bei/+24h, Empfänger-Auflösung (Assignee/Group-Members/Watcher), **Anti-Spam-Bündelung max 1/4h pro User** (Bündelung im NotificationService NICHT vorhanden — neu), Email-Eskalation bei +24h. Cron-Pattern + Notification-Layer vorhanden, Domänen-Logik neu.
9. **Auto-Archivierung** (M073, Block F.2): täglicher Cron `status=done AND completed_at<=now-30d AND archived_at IS NULL → archived_at=now()`. Cron-Vorlage vorhanden, Job neu.
10. **Activity-Typen** (Block G, M045): 7 Task-Activity-Typen mit `related_entity_refs` (Task-Activity erscheint im Stream der verknüpften Entität). DTO-/Übersetzungs-Muster aus `RowTasks*Dto` als Vorlage; `@hivegrid/activity`-`logActivity`-Wiring neu.
11. **ERP-Aufgaben-Sync M074** (Pflichtenheft 26.10, [N11]): Per-Mandant/Per-Adapter aktivierbar, Sync-Modi A/B/C („KWP gewinnt"), Identifikations-Brücke (KWP-Box: Email), KWP-Badge, Sync-Status im Detail, Anti-Endlosschleife, Aushebel-Schutz. `appsEngine`-Schema liefert ID-Brücke + Rollback-Run; Konflikt-Auflösung soll M093 wiederverwenden (Vorbedingung). Task-spezifische Mapping-Schicht neu.
12. **i18n-Key-Set** für alle Klartext-Texte (Block I + F + Permission-Tooltips) — neu (Pattern + Infra vorhanden).
13. **Sidebar-Eintrag + Route** in HiveGrid-Targets (`packages/ui-hivegrid/src/app-shell/sidebar.config.ts`, Gruppe `arbeiten`) — die HiveGrid-Pakete (`packages/ui-hivegrid`, `@hivegrid/*`) existieren in der Boilerplate **nicht**; nur das `@toolctrl/*`-Äquivalent als Vorlage.
---
## Empfohlenes Vorgehen
**Phase A — Fundament (M071), zuerst aus BP übernehmen:**
1. `Task` + `TaskWatcher` in `prisma/schema/app.prisma` modellieren (Felder-Vorlage `RowTask`, erweitert um Block-A-Felder; `Group`/`GroupUser` für Gruppen-Zuweisung wiederverwenden). Forward-Only-Migration mit Inverse-SQL.
2. **Pflicht:** neue User-FKs in `packages/db/src/dsgvo/user-fk-map.ts` ergänzen (sonst CI-Block).
3. Repository-Layer nach Muster `rowTasks.db.server.ts` bauen (`get*/create/update/delete/getAll` + Owner-Filter „assigned OR created OR watcher OR group-member"). DB-Client + `runDbTransaction` 1:1 aus `@toolctrl/db`.
4. `tasks.*`-Permissions + Bundle-Mapping (Block H) auf RBAC-Fundament; Owner-Check + 404-statt-403.
5. VM-Builder + Listen-/Detail-View über `@toolctrl/view-models` + shadcn-Tabellen/Modale/Picker (als-vorlage); Sidebar-Eintrag „Aufgaben" (Gruppe `arbeiten`) via Registry-Factory; Quick-Add/Toggle-Logik aus `RowTasks.tsx`.
**Phase B — Embed + Quellen (M072):**
6. Polymorphe Verknüpfung + Tasks-Section in Entity-Detail-Views (neu); Pre-Fill bei „Aufgabe anlegen".
7. Quellen-Integration (Chat/Form/Automation) — DTO-Muster `events/dtos/RowTasks*` übernehmen; abhängig von M110–M114 / M121–M125 / M075–M082.
8. Activity-Typen (Block G) via `logActivity` + Outbox.
**Phase C — Reminder & Archivierung (M073):**
9. Reminder-Cron + Auto-Archivierungs-Cron als BullMQ-`upsertJobScheduler`-Jobs nach Vorlage `dsgvo-grace-cron.ts` / `outbox-done-retention-cron.ts` (host-agnostisch, idempotent).
10. Versand über `notify()`/`NotificationService` + `notifications.server.ts` (1:1); Empfänger-Auflösung + **Anti-Spam-Bündelung (max 1/4h) neu** ergänzen; User-Toggle über `UserNotificationPreference`.
**Phase D — ERP-Sync (M074), zuletzt:**
11. Auf `appsEngine` (`App`/`DataConnection`/`AppSyncRun`/`AppSyncItem`) aufsetzen; KWP-Email-Identifikations-Brücke (`sourceId`/`destinationId`), Sync-Modi A/B/C + Konflikt-Regel (M093 wiederverwenden), KWP-Badge + Sync-Status im Detail, Anti-Endlosschleife (markierte Sync-Herkunft löst keinen Rück-Push aus), Aushebel-Schutz. Vorbedingung: KWP-Sync-Foundation M089–M095.
**Querschnitt durchgängig (DoD):** Outbox für alle Side-Effects, Audit automatisch (M001), Feature-Flag pro Modul, i18n-Keys statt Klartext, View-Model-Trennung (keine Prisma-Imports in UI-Paket), Smoke-Test + Hot-Swap-Drill + Visual-Snapshot.
---
## Hinweise / Vorbehalte
- **`RowTask` ≠ HiveGrid-Task.** Wer `RowTask` 1:1 übernimmt, baut am Datenmodell vorbei (kein tenantId/status/priority/group/source/linked_entity/archived/watcher). Nur als Feld-/Service-/UI-**Vorlage** verwenden.
- **HiveGrid-Target-Pfade existieren nicht in der BP.** `packages/ui-hivegrid`, `@hivegrid/activity`, `@hivegrid/notifications`, `@hivegrid/audit`, `packages/entitlements/src/permissions.ts` (HiveGrid-Variante) sind Soll-Zustand laut INTEGRATION-CONTRACTS; die BP liefert nur die `@toolctrl/*`-Äquivalente als Muster.
- **Bündelung (max 1/4h pro User)** ist im vorhandenen NotificationService nicht implementiert — eigene Window-Logik nötig (M073-Erfolgskriterium).
- **`@toolctrl/ui-subframe` ist leer** (Stub). Der Subframe-Adapter-Layer ist nicht gebaut; HiveGrid muss diese Grenze selbst füllen (MEMORY: „Subframe mandatory for all routes").
- **M074 hängt an externer Foundation** (M089–M095 KWP-Sync, M008–M010 Apps-Engine). `appsEngine`-Schema ist das Fundament, die KWP-spezifischen Adapter/Konfliktregeln liegen außerhalb von M26.
@@ -0,0 +1,142 @@
# Boilerplate-Mapping — M27 Auth / Multi-Tenancy / Rollen / Permissions
**Modul-ID:** M27 (HiveGrid-Modul 27)
**Name:** Anmeldung, Mandanten, Rollen & Permissions
**Milestones:** M018-M027 (M018 Mandanten-Anlage, M019 Mandanten-Trennung-Hardening, M020 Email/PW-Auth, M021 Magic-Link/Sessions, M022 TOTP-2FA, M023 Rollen-Engine/SHK-Rollen/Gruppen, M024 Mitarbeiter-Einladung/Deaktivierung, M025 Konto-Löschung, M026 Mandanten-Lebenszyklus, M027 API-Keys/Tarif-Gates)
**Block:** Block 1 — Plattform-Fundament (Pflichtenheft v1.1, §27)
**Reuse-Level:** **HIGH** — Die Boilerplate liefert ein nahezu vollständiges Auth/Tenancy/RBAC-Fundament inkl. Daten-Modelle, Service-Layer, fertige Settings-UI-Routen und Querschnitt-Helper. HiveGrid muss primär: (1) HiveGrid-spezifische Inhalte (SHK-Rollen-Template, Permission-IDs) einfüllen, (2) drei echte Architektur-Lücken schließen (Server-Side-Sessions in Postgres, Tenant-Lifecycle-Statusmaschine, Reassign-Workflow vor Deaktivierung), (3) das App-Level-Tenant-Scoping ggf. um Postgres-RLS härten (Spec A.4 — bauliche Vorgabe, in BP NICHT vorhanden).
> Verifiziert per direktem Read/Grep in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (nicht nur Inventur). Stand der Vorphase-Inventur bestätigt; Abweichungen unten markiert.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/accounts.prisma` | `User`, `Tenant`, `TenantUser`, `TenantUserInvitation`, `MagicLinkToken`, `AdminUser`, `Registration`, `Blacklist`, `ImpersonationAudit`, `TenantIpAddress`, `WorkspaceAuthProvider`, `TenantType` | **anpassen** — Identity/Tenancy-Kern. User hat bereits `passwordHash`, `totpSecretEncrypted`/`totpPendingSecretEncrypted`/`totpEnabledAt`, `mfaRecoveryCodeHashes`, DSGVO-Flags (`pendingDeletion`/`scheduledDeletionAt`/`pseudonymized`/`deletionRequestId`), `defaultTenantId`. Felder zu ergänzen siehe Lücken. |
| `prisma/schema/permissions.prisma` | `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` | **1:1** als RBAC-Fundament. `Role` ist tenant-scoped (`tenantId?`), hat `type`/`isDefault`/`assignToNewUsers`/`order`. `UserRole.tenantId?` (Multi-Rolle pro User + tenant-Scope). `Group`/`GroupUser` = exakt die orthogonalen Gruppen aus Spec C.4. Permission `name @unique` (global, atomar) + optional `entityId` (Entity-gebundene Rechte). Deckt C.1 (atomar gespeichert), C.3 (Multi-Rolle additiv), C.4 1:1 ab. |
| `prisma/schema/core.prisma` → `ApiKey`, `ApiKeyLog` | API-Key-Modell mit `keyHash`/`keyPrefix`/`keyLastFour`/`keyVersion` (gehashte Keys, einmalig sichtbar), `alias`, `expires`, `active`, `@@unique([tenantId, alias])`; `ApiKeyLog` für Request-Logging (ip/endpoint/method/status/duration) | **anpassen** — deckt Block E fast komplett (Anlage, Hash, Rotation, Logs). Lücke: Scopes (`read_only`/`webhook_inbound`/`read_full`/`automation_trigger`) + per-Tenant-Rate-Limit-Override + 365-Tage-Default fehlen als Felder. |
| `prisma/schema/core.prisma` → `AuditEvent` | Tamper-evidente Audit-Hash-Kette (`previousHash`/`eventHash`), `actorType`/`actorId`/`actorEmail`/`actorIp`, `dataSensitivity`, `regulatoryScope[]`, `outcome`, reichlich Indizes | **1:1** — Audit-Trail für C.5 (Rollen-/Permission-Änderungen geloggt), D-Lifecycle, E (API-Key-Anlage/Widerruf). Querschnitt M001. |
| `prisma/schema/subscriptions.prisma` (14 Modelle) + `packages/entitlements` | `SubscriptionProduct`/`SubscriptionPrice`/`SubscriptionFeature`/`TenantSubscription`/`TenantFeatureOverride` + Feature-Gate-Engine (`evaluateEntitlement`, `featureGateRegistry`, `featureKeys`, `evaluateProductAccess`, `productBlueprints` mit `crm-saas`) | **anpassen** — deckt Block F.1 (Subscription-Feature-Gates) als Engine ab; Datenmodell SubscriptionProduct→Features→TenantSubscription exakt wie Spec F.1. HiveGrid-Plan-Definitionen (Cloud/Cloud+/Enterprise) sind geparkt (Spec), daher nur Engine übernehmen, `featureKeys` mit HiveGrid-Keys erweitern. |
| `prisma/schema/featureFlags.prisma` | `FeatureFlag` (scope global/tenant/user, v2-Targeting `rules`/`variants`, `enabledFrom/Until`, Flag-Dependencies), `FeatureFlagFilter`, `FeatureFlagAudit` (append-only) | **1:1** — deckt Block F.2 (Feature-Flags, Modul 32) inkl. Filter-Regeln + Audit. |
| `apps/web/app/services/auth/totp.server.ts` (+ `utils/auth/mfa/recovery-codes.server.ts`, `enforcement.server.ts`, `step-up.server.ts`, `challenge-rate-limit.server.ts`) | TOTP-Enrollment (otpauth, SHA1/6-stellig/30s), QR/otpauth-URI, verschlüsseltes Secret (CryptoApi), 10 Recovery-Codes, Pending→Activate-Flow, MFA-Enforcement-Gate, Step-Up, Challenge-Rate-Limit (5/5min konfigurierbar) | **1:1 / anpassen** — deckt Block B.4 (TOTP, Backup-Codes, Setup-Flow) nahezu vollständig. Anpassen: Trust-Device-Cookie + Pflicht-2FA-Toggle pro Tenant (siehe Lücken). |
| `apps/web/app/services/auth/password-policy.server.ts` (+ `password-policy-banner.server.ts`, `password-reset-token.server.ts`) | Zentrale Passwort-Validierung, env-getrieben, HIBP-k-Anonymity-Check (`api.pwnedpasswords.com/range/`, Timeout 3s), Min-Length, bounded i18n-Error-Codes, Soft-Banner bei veraltetem PW, Reset-Token | **1:1** — deckt B.1 (≥12 Zeichen via Config, HIBP-Block mit Klartext, keine erzwungenen Sonderzeichen). Cost-Faktor: siehe `passwordHasher.server.ts`. |
| `apps/web/app/utils/auth/passwordHasher.server.ts` | Passwort-Hashing | **anpassen** — Spec B.1 verlangt bcrypt Cost 12; verifizieren/setzen. |
| `apps/web/app/services/auth/magic-link.server.ts` | Magic-Link: signierte Tokens, `MAGIC_LINK_TOKEN_TTL_MINUTES=15`, einmalig nutzbar (`consumeMagicLinkToken`), Purpose-gebunden, `MagicLinkToken`-Tabelle mit `tokenHash`/`consumedAt`/`expiresAt` | **1:1** — deckt B.2 (15-Min-TTL, einmalig) exakt. Rate-Limit 3/15min via auth-rate-limit ergänzen. |
| `apps/web/app/services/auth/auth-rate-limit.server.ts` | Rate-Limit für `login`/`forgot-password`/`reset-password`/`mfa`, IP+Identifier-gehasht, Window+Limit konfigurierbar, retryAfter | **1:1** — deckt B.1 (5/15min pro Email, IP-Limit) + B.2 + B.4. Captcha (hCaptcha) ab 3. Versuch fehlt (siehe Lücken). |
| `apps/web/app/utils/session.server.ts` | Cookie-Session-Storage (`createCookieSessionStorage`), `setLoggedUser` (löst defaultTenant → Fallback erster Tenant), Impersonation-Session-State + Validierung (TTL, Actor-Check), CSRF | **als-vorlage** — Login-Flow + Tenant-Resolution + Impersonation übernehmbar. ABER: Sessions sind **cookie-basiert, NICHT server-side in Postgres** — Spec B.5 verlangt explizit Postgres-Sessions (siehe Lücken). |
| `apps/web/app/utils/services/tenantService.ts` (+ `utils/app/UrlUtils.ts`, `app/PublicRouteSegments.ts`) | `normalizeTenantSlug`, `UrlUtils.slugify`, `isReservedTenantSlug`, `getAvailableTenantSlug` (Auto-Suffix `-2` bei Konflikt), Reserved-Slug-Set | **1:1 / anpassen** — deckt A.2 (Auto-Generierung, Eindeutigkeit, Reserved-Words, Vorschlag mit Nummer). Reserved-Word-Liste + Umlaut-Mapping (ae/oe/ue) + GmbH/AG-Suffix-Erhalt an HiveGrid-Regeln angleichen. |
| `apps/web/app/utils/services/rolesAndPermissionsService.ts` (+ `@toolctrl/db/permissions-seed.server`) | `seedRolesAndPermissions`, `defaultAppRoleSeeds`/`defaultAdminRoleSeeds`, `defaultPermissionSeedDescriptors`, `syncDefaultRolesAndPermissions`, Seed-Diagnostics | **als-vorlage** — Seeding-Mechanik 1:1 nutzbar. ABER Default-Rollen sind **generisch** (`SuperAdmin`/`SuperUser`/`Admin`/`Billing Admin`/`User`), NICHT die SHK-Rollen. SHK-Branchen-Template (C.2/27.7, 7-10 Rollen) ist als deklaratives Seed neu zu definieren. |
| `apps/web/app/components/layouts/selectors/TenantSelector.tsx` + `NewTenantSelector.tsx` (eingebunden in `routes/app.tsx`) | Tenant-Switcher-Komponente in der App-Shell | **anpassen** — deckt A.3/D.4 (Tenant-Switcher überall verfügbar). Suchfeld bei 5+ Tenants + `last_accessed_at`-Sortierung ergänzen (Feld fehlt, siehe Lücken). |
| `apps/web/app/routes/app.$tenant/settings/members.tsx` (+ `members/groups`) | Mitarbeiter-Verwaltung + Einladungs-Flow (nutzt `TenantUserInvitation`) | **anpassen** — Basis für D.1 (Einladung mit Rolle/Groups/Nachricht, 7-Tage-Token, 3 Pfade). Reassign-Workflow vor Deaktivierung fehlt. |
| `apps/web/app/routes/app.$tenant/settings/roles-and-permissions.tsx` (+ `roles-and-permissions/roles`, `components/core/roles`) | Rollen-Editor-UI (Liste, Anlegen, Permissions, Matrix-Test vorhanden) | **anpassen** — Basis für C.3 (Editor, neue Rolle, „Basieren auf", Duplizieren, Löschen mit Reassign). Bundle/Advanced-Mode-Toggle (C.1) und Permission-Preview-Tool (C.5) ergänzen. |
| `apps/web/app/routes/app.$tenant/settings/groups.tsx` | Gruppen-Editor | **1:1 / anpassen** — deckt C.4 (Anlegen/Umbenennen/Löschen, Mitglieder, Description). |
| `apps/web/app/routes/app.$tenant/settings/api/keys/` (`keys.tsx`, `new.tsx`, `$id.tsx`) + `api/logs.tsx`, `api/docs.tsx` | API-Key-Settings-UI inkl. Anlage, Detail, Logs | **anpassen** — deckt Block E-UI (Liste, einmalig sichtbarer Key, Logs der Anfragen). Scope-Auswahl + Rate-Limit-Override ergänzen. |
| `apps/web/app/routes/app.$tenant/settings/account.tsx` + `privacy.tsx` + `privacy.delete.confirm.$token.tsx` + `privacy.delete-mail` | Account-Löschung (Multi-Step), DSGVO-Privacy, Token-Bestätigung | **anpassen** — deckt D.3 (Multi-Step-Löschung, PII-Überschreibung, 24h-Reverse via Email-Token). Last-Tenant-Admin-Block + 3-Sek-Countdown ergänzen. Cascade-Karte in `packages/db/src/dsgvo/user-fk-map.ts` ist Pflicht-Referenz. |
| `apps/web/app/routes/app.$tenant/settings/profile.tsx` (+ `profile.mfa`, `profile.session`, `profile.locale-picker`, `theme.tsx`) | Persönliche Settings: 2FA-Setup, Session-Übersicht, Sprache, Theme | **anpassen** — deckt B.5-UI (Session-Liste/Revoke) + B.4-UI (2FA-Setup) + Persönliche `/settings/`. Trust-Device-Liste mit Revoke ergänzen. |
| `apps/web/app/routes/app.$tenant/settings/audit-export.tsx` + `logs/` | Audit-Log-UI + Export | **1:1** — Audit-Log-Anzeige für C.5. |
| `packages/foundation/src/permissions.ts` | `requirePermission`, `withTenantScope`, `withPermission`, `withOwnerCheck` | **1:1** — Querschnitt-Helper (Spec AV #5 Permissions-aware-Default, AGENTS.md DoD C.17). Exakt die in INTEGRATION-CONTRACTS §10 referenzierte API. |
| `packages/foundation/src/{audit,notifications,flags,concurrency,idempotency,errors}.ts` | Audit-Helper, Notify, Feature-Flag-Eval, Concurrency (Last-Write-Wins), Idempotenz, Catalog-Errors | **1:1** — Querschnitt für C.5 (Concurrent-Update Last-Write-Wins), D.3-Notify, F.2, Klartext-Errors (M002). |
| `packages/db/src/{client.server,transactions.server,outbox,audit-hash}.ts` + `dsgvo/user-fk-map.ts`, `dsgvo/pseudonymize.ts` | Prisma-Client-Grenze, Transaktionen, Outbox, Audit-Hash, DSGVO-FK-Karte + Pseudonymisierung | **1:1** — Fundament für jede schreibende Aktion (Audit/Outbox), D.3-Pseudonymisierung. |
| `packages/db/src/{users,accounts,api-keys,auth-boundary,auth-providers,device-tokens,impersonation-audit,workspace-invites,permissions-seed,entitlements-seed,subscriptions,settings}.server.ts` | Repository-Befehlsfläche für alle Auth/Tenancy-Domänen | **1:1 / anpassen** — DB-Layer-APIs direkt nutzbar; je Repo-Methode neue HiveGrid-Felder durchreichen. |
| `apps/web/app/utils/services/admin*` + `services/auth/admin-mfa-gate.server.ts`, `admin-fallback.server.ts` | Admin-Panel-Auth (Pflicht-2FA, Fallback-Admin) | **als-vorlage** — relevant für Plattform-Admin (Modul 37, außerhalb M27-Kern, aber `AdminUser`-Modell + Pflicht-2FA-Gate direkt nutzbar). |
| `packages/shared-store` | Redis-KV: `createFixedWindowRateLimiter`, `createSlidingWindowRateLimiter`, `createSessionStore`, `createIdempotencyStore`, Cache mit Tenant-Präfix | **1:1** — Cross-Replica-Rate-Limit (B.1/B.2/B.4, Spec verlangt mehr als der In-Memory-`cache` in auth-rate-limit), Cache-Isolation `tenant:{id}:` (A.4), Session-Store falls hybrid. |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
**accounts.prisma:**
- `User` — `email @unique`, `passwordHash?`, `firstName`/`lastName`/`avatar`/`phone`, `defaultTenantId?`, `verifyToken`, TOTP (`totpSecretEncrypted`, `totpPendingSecretEncrypted`, `totpEnabledAt`, `totpPendingCreatedAt`), `mfaRecoveryCodeHashes Json`, `mfaRecoveryCodesGeneratedAt`, `active`, DSGVO (`pendingDeletion`, `scheduledDeletionAt`, `deletionRequestedAt`, `pseudonymized`, `pseudonymizedAt`, `deletionRequestId @unique`), `locale`, `lightOrDarkMode`. **Hat noch `githubId`/`googleId @unique` (Boilerplate-OAuth — EU-Sterilisation pending, für M27-Scope irrelevant/zu entfernen).**
- `Tenant` — `slug @unique`, `name`, `icon`/`logo`, `subscriptionId?`, `active`, `deactivatedReason?`, `theme`/`themeConfig`. **Kein Lifecycle-Status-Enum, kein `lastAccessedAt`.**
- `TenantUser` — Membership (`tenantId`, `userId`, `type Int`, `joined Int`, `status Int` — Int-codiert, kein Enum).
- `TenantUserInvitation` — `email`, `firstName`/`lastName`, `type Int`, `pending`, `status @default("pending")`, `tokenHash?`/`tokenPrefix?`, `expiresAt?`, `acceptedAt?`/`revokedAt?`, `createdUserId?`/`fromUserId?`/`acceptedByUserId?`/`revokedByUserId?`. Indizes auf `(tenantId,status,expiresAt)`, `(tenantId,email,status)`, `(tenantId,tokenPrefix)`.
- `MagicLinkToken` — `tokenHash @unique`, `expiresAt`, `consumedAt?`, FK User Cascade.
- `AdminUser` — Plattform-Admin-Panel-Zugang (+ OIDC-SSO-Felder `ssoProvider`/`ssoSubjectId`/`ssoGroups`/`lastSsoLoginAt`).
- `Registration` — Self-Service-Signup-Staging (`email @unique`, `slug?`, `token @unique`, `company?`, `selectedSubscriptionPriceId?`, Lead-Conversion-Felder, `createdTenantId?`).
- `Blacklist` (email/domain/ip), `TenantIpAddress`, `ImpersonationAudit` (Actor/Target/Tenant SetNull), `WorkspaceAuthProvider` (SSO/SAML/OIDC pro Tenant), `TenantType`.
**permissions.prisma:**
- `Role` (`tenantId?`, `name`, `description`, `type`, `assignToNewUsers`, `isDefault`, `order`, `@@unique([tenantId, name])`), `Permission` (`name @unique` global atomar, `type`, `isDefault`, `order`, `entityId?`), `RolePermission`, `UserRole` (`tenantId?`, partielle Eindeutigkeit via Migration-SQL), `Group` (`tenantId?`, `name`, `description`, `color`), `GroupUser`.
**core.prisma:** `ApiKey` (gehasht), `ApiKeyLog`, `AuditEvent` (Hash-Kette), `IdempotencyKey`, `Credential` (Secret-Store), `Event`/`EventWebhookAttempt`, `Log`, `IpAddress`/`IpAddressLog` (Geolocation für Session-Standort B.5).
**subscriptions.prisma:** `SubscriptionProduct`, `SubscriptionPrice`, `SubscriptionFeature`, `TenantSubscription`, `TenantFeatureOverride` (`@@unique([tenantId, featureKey])`), `TenantProductConfiguration` (`blueprintId` default `crm-saas`) — Block-F.1-Fundament.
**featureFlags.prisma:** `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit` — Block-F.2-Fundament.
**notifications.prisma:** `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` — für D.3-Lösch-Notification + B.5-Push-Token-Cleanup.
---
## Lücken / komplett neu zu bauen
Verifiziert per Grep — folgendes existiert in der Boilerplate **NICHT** und ist neu zu bauen:
1. **Server-Side-Sessions in Postgres (B.5) — ARCHITEKTUR-LÜCKE.** Boilerplate nutzt `createCookieSessionStorage` (Cookie-only, `apps/web/app/utils/session.server.ts:124`). Es gibt **kein** `Session`/`UserSession`/`AuthSession`-Prisma-Modell (Grep leer). Spec B.5 verlangt explizit Postgres-Sessions wegen Logout/Revoke, Session-Liste mit Gerät/Browser/IP/Standort/Letzte-Aktivität, globalem „Von allen Geräten abmelden", 4h-Inaktivitäts-Timeout, 30-Tage-Sliding-Window, Auto-Logout bei PW/2FA/Email-Änderung. → **Neues `Session`-Modell + Session-Service neu bauen.** (`profile.session.tsx`-UI existiert als Hülle, Backend fehlt.)
2. **Postgres Row-Level-Security (A.4) — ARCHITEKTUR-LÜCKE.** Kein `current_setting('app.tenant_id')`, kein `SET LOCAL`, keine RLS-Policy-Migrations (Grep nur Doku/Tests, keine `ENABLE ROW LEVEL SECURITY`). Boilerplate-Tenant-Isolation ist **App-Level** (`withTenantScope`, repo-Filter, `tenant-scoped.ts`-Wrapper). Spec A.4 schreibt RLS als bauliche Vorgabe vor (Policy USING/WITH CHECK, App-Role ohne BYPASSRLS, Middleware `SET LOCAL app.tenant_id`). → **RLS-Layer neu (Migration + Request-Middleware + Worker-Job-Context)** — M019.
3. **Tenant-Lifecycle-Statusmaschine (A.5 / 27.11) — FEHLT.** `Tenant` hat nur `active: Boolean` + `deactivatedReason?`, **kein** Status-Enum. Status-Werte `trial/active/past_due/frozen/suspended/deletion_pending/deleted`, Übergänge, Frozen-Read-Only-Rechte-Matrix, Statusabhängige UI-Banner, 30-Tage-Grace-Cron — alles neu. → **Tenant-Status-Feld/Enum + State-Machine + Banner + Cron** — M026.
4. **Reassign-Workflow vor Deaktivierung/Entfernen (D.2 / 27.9.5) — FEHLT.** Kein `reassign`/`handover`/`orphan`-Code in `apps`. Anzeige offener Verknüpfungen pro Typ (Deals/Projekte/Tasks/Termine), Bulk-Reassign, Einzel-Reassign, „verwaist lassen"-Override mit Bestätigung. → Neu (querschnittlich, braucht spätere Modul-Entitäten). — M024.
5. **SHK-Branchen-Rollen-Template (C.2 / 27.7) — FEHLT (generische Seeds vorhanden).** `defaultAppRoleSeeds` = `SuperUser/Admin/Billing Admin/User` (generisch). Die 7-10 SHK-Rollen (GF, Vertriebsleiter, Vertriebler, Projektleiter, Büro, Buchhaltung, Personal, Lagerist, Marketing, Monteur) inkl. Default-UI-Modus (Büro/Baustelle) und Permission-Bundles sind als **deklaratives Branchen-Template** neu zu schreiben (Seeding-Mechanik selbst ist wiederverwendbar). — M023.
6. **Permission-Bundle/Advanced-Mode + Permission-IDs (C.1) — FEHLT.** Permissions sind atomar gespeichert (vorhanden), aber die Variante-2-Bundle-Stufen (`crm.none/read_own/read_all/write/admin`), der Advanced-Mode-Toggle und „Benutzerdefiniert"-Erkennung sind neu. Konkrete HiveGrid-Permission-IDs entstehen modulweise (Spec offen). — M023.
7. **`Tenant.lastAccessedAt` pro Membership (A.3 / D.4) — FEHLT.** Kein Feld für Default-Sortierung des Switchers / „letzter genutzter Tenant". → Feld auf `TenantUser` ergänzen + im Switcher (Suchfeld bei 5+) verdrahten. — M019/M018.
8. **Trust-Device / „30 Tage merken" (B.4) — FEHLT.** Kein `trustedDevice`/`rememberDevice`-Code (Grep leer). Signed-Cookie umgeht 2FA 30 Tage + Trust-Device-Liste mit Revoke neu. — M022.
9. **Pflicht-2FA-Toggle pro Tenant (B.4 / 27.4.3) — FEHLT.** MFA-Enforcement existiert für Admin-Panel (`admin-mfa-gate.server.ts`), aber nicht der Tenant-weite „2FA für alle Pflicht"-Toggle (zwingt User ohne 2FA beim nächsten Login). → Tenant-Setting + Enforcement-Erweiterung. — M022.
10. **Captcha ab 3. Fehlversuch (B.1 / 27.3.5) — FEHLT.** `AppConfiguration.authRecaptchaSiteKey` existiert als Feld, aber keine hCaptcha-Integration/Trigger-Logik. Spec verlangt hCaptcha (DSGVO). — M020.
11. **API-Key-Scopes + Rate-Limit-Override + 365-Tage-Default (Block E) — TEILWEISE.** `ApiKey`-Modell hat keine Scope-Spalte; Scopes (`read_only`/`webhook_inbound`/`read_full`/`automation_trigger`), per-Tenant-Rate-Limit-Override (1000/h Default, erhöhbar) und 365-Tage-Zwangs-Ablauf neu. — M027.
12. **Signup-Formular-Felder (A.1 / 27.1.2-3) — TEILWEISE.** `Registration` hat `company`/`slug`, aber nicht: Branche (SHK-preselect, andere „Coming soon"), Firmengröße-Dropdown, AGB/DSGVO/AVV-Akzeptanz-Checkboxen (AVV elektronisch unterschrieben), USt-Id, Telefon. → Felder + Formular-Validierung ergänzen. — M018.
13. **Slug-Live-Validierung beim Tippen (A.2, debounced 500ms) — TEILWEISE.** Server-Funktionen (`getAvailableTenantSlug`, `isReservedTenantSlug`) vorhanden; debounced Live-Check-Endpoint + Umlaut-Mapping (ae/oe/ue) + Suffix-Erhalt (GmbH) ergänzen. — M018.
14. **HiveGrid-UI-Layer (`packages/ui-hivegrid`, Subframe-Adapter, View-Models, sidebar.config) — NEU.** Boilerplate-UI liegt in `apps/web/app/routes` + `components/core` (klassisch, kein VM/Adapter-Pattern). HiveGrid-DoD verlangt VM-Layer (`packages/view-models`), `ui-hivegrid`-Adapter, `sidebar.config.ts`-Eintrag „Mitarbeiter & Rollen" (Gruppe Einstellungen), i18n-Keys. Boilerplate-Routen sind **als-vorlage** (Logik/Felder), nicht 1:1 (Layer-Disziplin AGENTS.md §A). — alle Milestones.
15. **Domain-/Pseudonymisierungs-Erweiterung der `user-fk-map.ts` — PFLICHT bei neuen User-FKs.** Jedes neue M27-Modell mit User-FK muss in `packages/db/src/dsgvo/user-fk-map.ts` eingetragen werden (CI-Test bricht sonst).
---
## Empfohlenes Vorgehen
**Phase 1 — Fundament 1:1 aktivieren (geringes Risiko, größter Hebel):**
1. Prisma-Modelle `accounts.prisma` + `permissions.prisma` + `core.prisma`(ApiKey/AuditEvent) + `featureFlags.prisma` + `subscriptions.prisma` als HiveGrid-Schema übernehmen (in `prisma/schema/` — sind bereits Teil der Codebase). `githubId`/`googleId` im Zuge der EU-Sterilisation entfernen.
2. Querschnitt-Helper aus `packages/foundation` (`permissions.ts`, `audit`, `notifications`, `flags`, `concurrency`, `errors`) + `packages/db`-Repos + `packages/entitlements` + `packages/shared-store` aktivieren — sie sind die in INTEGRATION-CONTRACTS/AGENTS referenzierten APIs.
3. Auth-Services 1:1 verdrahten: `totp.server.ts` (+ mfa/*), `password-policy.server.ts`, `magic-link.server.ts`, `auth-rate-limit.server.ts` (auf `shared-store`-Rate-Limiter umstellen statt In-Memory-cache).
**Phase 2 — Architektur-Lücken schließen (M019/M021/M026 — die drei echten Neubauten):**
4. **Server-Side-Sessions** (B.5): neues `Session`-Prisma-Modell + Session-Service (Erstellen/Laden/Revoke/Liste, Sliding-Window, Inaktivitäts-Timeout, Auto-Logout-Trigger). Cookie hält nur Session-ID-Referenz. — M021.
5. **RLS-Härtung** (A.4): RLS-Policies als Forward-Migration (Inverse-SQL als Kommentar, AGENTS §F.28), Request-Middleware `SET LOCAL app.tenant_id`, App-Role ohne BYPASSRLS, Worker-Job-Tenant-Context-Wrapper, Cache-Präfix `tenant:{id}:`, S3-Pfad `tenants/{id}/`. Sonderfälle ohne RLS: `users`/`subscription_plans`/`feature_flags`/`branchen_templates`. — M019.
6. **Tenant-Lifecycle** (A.5): `Tenant.status`-Enum + State-Machine + Frozen-Read-Only-Gate (write-blockierend) + Status-Banner + 30-Tage-Grace-Cron. — M026.
**Phase 3 — HiveGrid-Inhalte einfüllen (auf Fundament):**
7. **SHK-Rollen-Template** (C.2): deklaratives Branchen-Seed (10 Rollen + UI-Modus + Bundle-Permissions) über die vorhandene `seedRolesAndPermissions`-Mechanik; bei Tenant-Anlage mit Branche=SHK seeden. — M023.
8. **Permission-Bundles + Advanced-Mode** (C.1) + konkrete HiveGrid-Permission-IDs (modulweise) + `featureKeys`-Erweiterung in entitlements. — M023.
9. **Signup-Formular** (A.1) + Slug-Live-Validierung (A.2) + `lastAccessedAt` + Tenant-Switcher-Suchfeld. — M018.
10. **Mitarbeiter-Lifecycle**: Einladung (D.1, drei Pfade) auf vorhandenem `TenantUserInvitation` + **Reassign-Workflow** (D.2, neu) + Deaktivieren/Entfernen + Last-Admin-Schutz. — M024.
11. **Konto-Löschung** (D.3) auf vorhandener `privacy.delete.*`-Hülle + `user-fk-map.ts`-Pseudonymisierung + Multi-Step/3-Sek-Countdown/Last-Admin-Block. — M025.
12. **2FA-Ergänzungen**: Trust-Device-Cookie + Pflicht-2FA-Tenant-Toggle. — M022. **Captcha** (hCaptcha) bei Login. — M020.
13. **API-Keys** (Block E): Scopes + Rate-Limit-Override + 365-Tage-Ablauf auf vorhandenem `ApiKey`-Modell/UI. — M027.
14. **Feature-Gating** (Block F): entitlements-Engine + `featureFlags`-Modell verdrahten, `requireTenantFeatureAccess`-Loader-Convention + Klartext-Boundary mit Marketing-Link. — M027.
**Querschnitt durchgängig:** Alle UI als VM + `ui-hivegrid`-Adapter (nicht Boilerplate-Routen direkt), `sidebar.config.ts`-Eintrag „Mitarbeiter & Rollen" (Gruppe Einstellungen) mit Permission-Gate, i18n-Keys, Audit auto via Middleware, Smoke-Tests + Hot-Swap-Drill (AGENTS.md DoD).
---
## Notizen / Realitäts-Check
- **EU-Sterilisation:** `apps/web/app/routes/oauth/github` + `User.githubId`/`googleId` sind noch vorhanden (Boilerplate-OAuth). Für M27 (Spec: nur Email+PW+Magic-Link+TOTP, kein Google/GitHub/MS) im Zuge des Pre-Flight-Checks (AGENTS.md) zu entfernen. `WorkspaceAuthProvider` (SAML/OIDC) ist Enterprise-SSO-Vorrat, in Phase 1 nicht beauftragt.
- **Admin-Panel-Auth** (`AdminUser`, `admin-mfa-gate.server.ts`) gehört strenggenommen zu Modul 37 (Plattform-Admin), ist aber als Fundament für `admin.hivegrid.de` direkt vorhanden.
- **Sessions cookie-basiert** ist der wichtigste Befund: Spec B.5 ist hier inkompatibel mit dem Boilerplate-Default und erzwingt einen echten Neubau (Postgres-Session-Tabelle), nicht nur Anpassung.
- **RLS fehlt komplett** — die Boilerplate setzt vollständig auf App-Level-Scoping. Spec A.4 macht RLS zur baulichen Vorgabe; das ist eine substanzielle, separat zu testende (Pen-Test-Suite, M019-Erfolgskriterium) Erweiterung.
@@ -0,0 +1,151 @@
# Boilerplate-Mapping — M28 Subscriptions / Billing
**Modul-ID:** M28
**Name:** Subscriptions / Billing
**Milestones:** M153 (Stripe-Integration EU), M154 (Plan-/Seat-Modell), M155 (Trial + Read-Only), M156 (Metering / Pay-as-you-go)
**Pflichtenheft-Block:** Block 7, Modul 28 (`_bmad-output/pflichtenheft/blocks/block7.md` §28.1–28.Y)
**Detail-Spec:** `_bmad-output/specs/M28-subscriptions-billing.md`
**Reuse-Level:** **HIGH** (Daten-Layer, Stripe-Service-Layer, Pricing-Config-Admin, Pay-as-you-go-Engine fast vollständig vorhanden; Lifecycle-State-Machine, Seat-Modell und Read-Only-Middleware fehlen)
> Verifiziert direkt gegen `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (nicht nur Inventur).
> Wichtig: Die BP-Modelle bilden den **Stripe-Spiegel** struktur-getreu ab, weichen aber in mehreren
> spec-kritischen Punkten ab (kein Status-Enum, kein Seat-Typ, andere Idempotenz-Strategie, sterilere Felder).
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/subscriptions.prisma` | Komplettes Subscription-Daten-Modell: `SubscriptionProduct`, `SubscriptionPrice`, `SubscriptionUsageBasedPrice`, `SubscriptionUsageBasedTier`, `SubscriptionFeature`, `TenantSubscription`, `TenantSubscriptionProduct`, `TenantSubscriptionProductPrice`, `TenantSubscriptionUsageRecord`, `TenantProductConfiguration`, `TenantFeatureOverride`, `CheckoutSessionStatus`, `Credit` | **anpassen** — Modellnamen 1:1 deckungsgleich mit Spec; Felder müssen erweitert werden (siehe Lücken). Als Migrations-Basis übernehmen. |
| `apps/web/app/utils/stripe.server.ts` (21 KB) | Stripe-Client + ~40 Funktionen: `createStripeCheckoutSession`, `createStripeSetupSession`, `createStripeSubscription`, `cancelStripeSubscription`, `reactivateStripeSubscription`, `createCustomerPortalSession`, `getStripeInvoices`, `getStripeUpcomingInvoice(s)`, `getStripePaymentMethods`, `createStripeCustomer`, Products/Prices CRUD, `createStripeUsageBasedPrice`, `createMeterEvent`, `listMeterEventSummaries`, `getStripeCoupon`/`PromotionCode`, Revenue-Aggregation | **1:1** — deckt fast alle Stripe-Operationen der Spec (Block C, F, H, I, K) ab. API-Version `2025-10-29.clover`. EU-Entity/Tax-Felder konfigurativ. |
| `apps/web/app/utils/services/.server/subscriptionService.ts` (23 KB, mit Tests) | `getPlanFeaturesUsage`, `getPlanFeatureUsage`, `getActiveTenantSubscriptions`, `reportUsage`, `persistCheckoutSessionStatus`, `cancelTenantSubscription`, `getMrr`, `convertToCurrency`, `clearTenantSubscriptionCache` | **anpassen** — Lifecycle-Helper als Basis; Status-Übergänge (Block B) fehlen und sind zu ergänzen. |
| `apps/web/app/utils/services/.server/subscriptionCache.server.ts` | Two-Tier-Cache (L1 in-process Map, L2 SharedStore-Pub/Sub) mit TTL-Default 5 min + Cross-Replica-Invalidation | **anpassen** — Spec verlangt 30 s TTL (Block G) statt 5 min; ansonsten 1:1 das geforderte Cache-Invalidate-Pattern. |
| `apps/web/app/utils/services/.server/pricingService.ts` (23 KB) | Pricing-Berechnung / Plan-Preis-Auflösung | **anpassen** — Basis für Setup-Fee-Differenz-Logik (Block K) und Proration. |
| `apps/web/app/utils/services/.server/tenantPlanLookup.server.ts` (+Test) | Plan-Auflösung pro Tenant | **1:1 / anpassen** — direkt für Quota-/Feature-Lookup. |
| `apps/web/app/utils/db/subscriptions/tenantSubscriptionProducts.db.server.ts` (+Test) | DB-Layer Tenant-Subscription-Products | **als-vorlage** — DB-Zugriffsmuster; in HiveGrid-Layer-Trennung (View-Model) zu überführen. |
| `apps/web/app/utils/db/stripe/checkoutSessions.db.server.ts` | Checkout-Session-Persistenz | **als-vorlage** |
| `packages/entitlements/` (Paket `@toolctrl/entitlements`) | Plan-/Feature-Gate-Engine: `evaluateEntitlement`, `evaluateProductAccess`, `featureGateRegistry`, `featureKeys`, `getFeatureGate`, `standardEntitlementPlans`, `getProductBlueprint` (`blueprints.ts`, aktuell `crm-saas`) | **anpassen** — direkt nutzbar als Feature-Gating-Querschnitt (Spec `SubscriptionFeature`/`SubscriptionProductFeature`); HiveGrid-Plan-Codes/Blueprints einzufüllen. Plan-IDs sind aktuell `free`/`pro`/`enterprise`. |
| `packages/entitlements/src/ai-quotas.ts` (+Test) | `resolveTenantAIQuota`, `getAIQuotaPlanDefaults`, `parseTenantAIQuotaOverride`, `aiQuotaCapabilityKeys` | **1:1 / anpassen** — deckt AI-Credits-Quota (Block J) konzeptionell ab. |
| `packages/entitlements/src/ai-overage.ts` (+Test) | `resolveTenantAIOverage`, `computeMarkedUpCostCents`, `roundUpToBlock`, `standardAIOverageDefaults` (Multiplier 1.5, Block-Cents) | **1:1** — Pay-as-you-go-Aufschlags-Rechnung (Block I/J + Pflichtenheft 28.8) bereits implementiert. |
| `apps/worker/src/jobs/ai-cost-aggregate*.ts`, `ai-cost-persist*.ts`, `ai-cost-stripe-report*.ts`, `ai-cost-stripe-submitter.ts`, `ai-cost-reconciliation*.ts`, `ai-cost-alert.ts` | Voller AI-Cost-Pipeline-Stack: Aggregation pro Period → Persist → Stripe-Usage-Reporting (`createMeterEvent`) → Reconciliation → Kosten-Alert (Notbremse-Kandidat 28.8.6) | **1:1 / anpassen** — deckt Metering-Reporting an Stripe (Block I) + Notbremse/Upsell-Trigger weitgehend ab. |
| `apps/worker/src/jobs/trial-expiring-trigger.ts` (+Test) | Täglicher Cron: scannt Trials mit Ablauf in Horizon (default 3 Tage), emittiert `tenant.trial_expiring`-Outbox-Event; idempotenter dispatchKey `tenant.trial_expiring.<tenantId>.<YYYY-MM-DD>` | **anpassen** — Trial-Ende-3-Tage-/1-Tag-Warnung (Block E / 28.3.5). 1-Tag-Schwelle ergänzen. |
| `apps/api/src/billing/stripe-webhook-route.ts` (+ 24 KB Test) | Stripe-Webhook-Endpoint (Hono): Signatur-Verify (`constructStripeWebhookEvent`), Metrics, transaktionaler Sub-Update + Outbox-Publish, Cache-Invalidation. Handhabt: `customer.subscription.updated/deleted`, `subscription_schedule.canceled` | **anpassen** — solide Endpoint-/Signatur-/Transaktions-/Outbox-Vorlage. Event-Coverage und Idempotenz-Strategie müssen erweitert werden (siehe Lücken). |
| `apps/web/app/components/core/settings/subscription/*` | UI: `ChangeSubscription`, `MyInvoices`, `MyPayments`, `MyPaymentMethods`, `MyUpcomingInvoice`, `MyBillingSession`, `MyPlanFeatureUsage`, `MySubscriptionFeatures`, `MyProducts`, `Plan(s)`, `PlanChangePreviewModal`, `ToggleBillingPeriod`, `CheckPlanFeatureLimit` (alle mit i18n-Tests) | **als-vorlage** — Achtung LP-8/Apple-Compliance: Pricing-/Plan-Vergleich/Upgrade-UI darf NICHT in die App. Nur Read-Only-Teile (`MyInvoices`, `MyPaymentMethods`, Usage-Anzeigen, Billing-Session-Embed) sind in HiveGrid zulässig; Plan-Wechsel/Toggle-Period gehören in Anti-Liste. |
| `apps/web/app/routes/admin/settings/pricing*.tsx` (`pricing.tsx`, `pricing.new.tsx`, `pricing.edit.$id.tsx`, `pricing.features.tsx`, `pricing.ai-overage.tsx`) | Plattform-Admin-Pricing-Konfiguration (datengetrieben, kein Code-Release) | **anpassen** — erfüllt Spec-Grundprinzip Block A (konfig-getriebene Engine) + Pflichtenheft 28.1.6. Gehört nach `admin.hivegrid.de` (M37). |
| `apps/web/app/routes/admin/accounts/subscriptions.tsx`, `subscriptions-revenue.tsx` | Plattform-Admin: alle Tenant-Subscriptions + Revenue-Sicht | **anpassen** — Spec Block N „Plattform-Admin-Sicht" (M37). |
| `apps/web/app/routes/app.$tenant/settings/subscription.tsx` (+Test) | Tenant-seitige Subscription-Settings-Route | **als-vorlage** — Route-Pattern + Loader-Muster; HiveGrid-Routes sind `/{tenant}/admin/subscription/...` (Spec Block M). |
| `packages/shared-store/` (`@toolctrl/shared-store`) | Redis-KV: `createIdempotencyStore`, `createTwoTierCache`, Rate-Limiter | **1:1** — Idempotenz (AV #8) + Status-Cache (Block G) + Cross-Replica-Invalidation. |
| `prisma/schema/outbox.prisma` + `@toolctrl/db/outbox` (`publishOutboxEvent`) | Transactional-Outbox für zuverlässige Side-Effects (Notifications, Lifecycle-Events) | **1:1** — Übergangs-Hooks (Block B) sauber als Outbox-Events. |
| `apps/worker/src/jobs/legacy-event-receiver.ts` | Outbox→BullMQ-Consumer für `subscription.ended`/`cancelled` Lifecycle-Events | **anpassen** — Vorlage für Status-Übergangs-Side-Effects (Audit/Activity/Notification). |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/subscriptions.prisma`:
| BP-Modell | Spec-Pendant | Deckung |
|---|---|---|
| `SubscriptionProduct` | `SubscriptionProduct` | Teilweise — hat `stripeId`, `order`, `title`, `active`, `model`, `public`, `badge`, `billingAddressCollection`, `hasQuantity`, `canBuyAgain`, Relation `assignsTenantTypes TenantType[]`. **Fehlt:** `code`, `tier_order`, `is_self_service_eligible`, `setup_fee_required`, `trial_default_days`, `requires_manual_activation`, `frozen_mode_price_id`, locale-`display_name`, Markdown-`description`, `created_at/updated_at`. |
| `SubscriptionPrice` | `SubscriptionPrice` | Teilweise — `stripeId`, `type`(Int), `billingPeriod`(Int), `price`(Decimal), `currency`, `trialDays`, `active`. **Fehlt:** `interval`-Enum (`month/year/one_time`), `interval_count`, `unit_amount_cents`, `tax_behavior`, `valid_from/valid_until`. |
| `SubscriptionFeature` | `SubscriptionFeature` + teilweise `SubscriptionProductFeature` | Abweichend — BP-Feature ist **direkt** an `SubscriptionProduct` gehängt (`name`, `type`, `value`, `accumulate`), kein globaler Feature-Katalog + M:N-Join. Spec verlangt globalen `SubscriptionFeature` (mit `category`-Enum) + separate `SubscriptionProductFeature` (mit `quota_value` JSON). **Umbau nötig.** |
| `SubscriptionUsageBasedPrice` | `SubscriptionUsageBasedPrice` | Gut — `unit`, `usageType`, `aggregateUsage`, `tiersMode`, `billingScheme`, Tiers. **Fehlt:** `metric_code`-Enum (`automation_trigger`/`ai_token`/`sms_outbound`), `included_amount`, `overage_pricing_strategy`. |
| `SubscriptionUsageBasedTier` | `SubscriptionUsageBasedTier` | 1:1 — `from`, `to?`, `perUnitPrice`, `flatFeePrice`. |
| `TenantSubscription` | `TenantSubscription` | **Stark abweichend** — BP hat nur `tenantId`, `stripeCustomerId`, `products[]`. **Fehlt alles Lifecycle-Relevante:** `status`-Enum, `subscription_product_id`, `stripe_subscription_id`, Period-Felder, Trial-Felder, `cancel_at_period_end`, `cancelled_at/reason`, `frozen_since`, `setup_fee_paid_at`, Dunning-Felder, `created_by_user_id`, `created_via`. In BP liegen Period/Cancel-Felder auf `TenantSubscriptionProduct`, nicht auf `TenantSubscription`. |
| `TenantSubscriptionProduct` | `TenantSubscriptionProduct` (Snapshot) | Teilweise — hat `currentPeriodStart/End`, `cancelledAt`, `endsAt`, `stripeSubscriptionId`, `quantity`, `fromCheckoutSessionId`, `customEntitlementPlanId`. **Fehlt:** `snapshot_data` (JSONB Preisstabilität), `valid_from/valid_until`. |
| `TenantSubscriptionProductPrice` | `TenantSubscriptionProductPrice` | Teilweise — verknüpft Price + UsageBasedPrice + UsageRecords. **Fehlt:** `quantity` (liegt eine Ebene höher), `is_metered`-Flag, `valid_from/valid_until`. |
| `TenantSubscriptionUsageRecord` | `TenantSubscriptionUsageRecord` | Abweichend — BP: `timestamp`(Int), `quantity`, `stripeSubscriptionItemId`. Spec: `metric_code`, `period_start/end`, `usage_amount`, `reported_to_stripe_at`, Composite-Index. **Erweitern.** |
| `CheckoutSessionStatus` | `CheckoutSessionStatus` | Teilweise — BP: `pending`(Bool), `email`, `fromUrl`, `from/createdUserId`, `from/createdTenantId`. **Fehlt:** `stripe_checkout_session_id`, `status`-Enum, `intent`-Enum, `completed_at/expires_at`, `error_message`, `redirect_url_*`. |
| `Credit` | `Credit` | Teilweise — BP: `tenantId`, `userId?`, `amount`(Int), `type`(String), `objectId?`. **Fehlt:** `credit_type`-Enum, `source`-Enum, `valid_from/valid_until`, `balance_after`, `notes`, `created_by_user_id`-Semantik. |
| `TenantProductConfiguration` | (kein direktes Spec-Pendant) | Bonus — `blueprintId` default `crm-saas`. Brauchbar als Branchen-/Blueprint-Anker (M29). |
| `TenantFeatureOverride` | (deckt `quota_value`-Override-Idee) | Bonus — Per-Tenant Feature-Override (`featureKey`/`override`/`reason`). Nutzbar für manuelle Plattform-Admin-Grants. |
**Verwandt, NICHT subscriptions.prisma:**
- `prisma/schema/accounts.prisma` → `model Tenant` hat **nur** `active: Boolean` + `deactivatedReason: String?` — **kein Status-Enum** (trial/active/past_due/cancelled/frozen). Die in Spec Block B geforderte `Tenant.status`↔`TenantSubscription.status`-Synchronisation existiert in der BP NICHT.
- `model TenantType` (accounts.prisma) — ist ein **Tenant-Typ** (von `SubscriptionProduct.assignsTenantTypes` zugewiesen), **nicht** das Büro/Monteur-User-Seat-Konzept der Spec (Block D). Kein Seat-Typ pro User vorhanden.
- `prisma/schema/portals.prisma` → eigenes gespiegeltes `PortalSubscription*`-Subsystem (Endkunden-Billing). Nicht für M28-Tenant-Billing, aber als zweites Muster vorhanden.
---
## Lücken / komplett neu zu bauen
1. **Subscription-Lifecycle-State-Machine (Block B) — fehlt komplett.**
- Kein `status`-Enum auf `TenantSubscription` und kein `Tenant.status`-Enum. BP kennt nur `Tenant.active` (Boolean).
- Keine Übergangs-Tabelle/Guards (`trial→active`, `active→past_due`, `→frozen`, `→cancelled`, Reaktivierung). BP-Webhook setzt nur `cancelledAt`/`endsAt`/Period.
- Tenant-Status-Synchronisation (M27 A.5) neu zu bauen.
2. **Seat-Modell Büro/Monteur (Block D) — fehlt komplett.**
- Kein per-User-Seat-Typ, keine Seat-Counter, keine Rolle↔Seat-Validierung, keine Quota-Enforcement (`max_buero_seats`/`max_monteur_seats`), kein Hard/Soft-Limit. `quantity` existiert nur als undifferenzierte Stripe-Item-Menge.
3. **Read-Only-/Downgrade-Middleware (Block G, AV #11) — fehlt komplett.**
- Grep nach `read.?only|past.?due|frozen|isWritable|402` in `apps/web` + `apps/api` ergibt KEINEN Billing-Status-Gate. Kein `is_writable_status()`-Helper, kein 402-Response auf Write-Endpoints, keine Worker-Job-Blockade (Automation/Notification/Webhook-Outbound), keine UI-Disable-Logik. Komplett neu, gekoppelt an Lifecycle (#1).
4. **Webhook-Event-Coverage + Idempotenz-Tabelle (Block C) — teilweise.**
- BP-Handler deckt nur `customer.subscription.updated/deleted` + `subscription_schedule.canceled`. **Fehlen:** `checkout.session.completed`, `invoice.created`, `invoice.payment_succeeded`, `invoice.payment_failed`, `customer.subscription.trial_will_end`.
- Spec verlangt **`StripeWebhookLog`-Tabelle** mit `stripe_event_id`-Unique-Constraint (Schreib-Idempotenz). BP nutzt stattdessen Outbox-`dispatchKey` (`stripe:<eventId>:...`) — funktional ähnlich, aber NICHT die geforderte Tabelle. Neu anzulegen oder Spec-Abweichung freigeben.
5. **Dunning / Past-Due-Tracking (Block F) — fehlt.**
- Keine `last_dunning_attempt_at`/`dunning_attempt_count`-Felder, keine 14-Tage-3-Versuche-Logik, keine gestaffelte Notification-Strategie. `invoice.payment_failed`-Handling fehlt (siehe #4).
6. **Frozen-Modus / User-Pause (Block H) — fehlt.**
- Kein `frozen_since`, kein `frozen_mode_price_id`, kein „PAUSIEREN"-Multi-Step-Flow, kein Stripe-Price-Wechsel auf reduzierte Gebühr, kein `frozen→past_due`-Pfad.
7. **Trial-Aktivierungs-Flow mit Vertriebs-Freigabe (Block E) — teilweise.**
- `trial-expiring-trigger.ts` deckt die Warnungen ab. **Fehlt:** `requires_manual_activation`-Flow (Vertrieb setzt `trial_start`/`trial_end`), „Trial-Anfragen"-Liste in M37, Trial-Ende→`deletion_pending`-Übergang, 1-Tag-Schwelle.
8. **AI-Credits-Saldo + In-App-Sichten (Block J) — teilweise.**
- Engine-Teile (`ai-quotas`, `ai-overage`, `Credit`-Modell) da. **Fehlt:** Saldo-Berechnung aus `Credit`-Sum mit Carry-Over/`valid_until`-Enforcement, `balance_after`, Pre-Check-Gate beim LLM-Call mit Klartext-Fehler, In-App-Sichten `/{tenant}/admin/usage/` + `/usage/ai-credits/` (Listen, Drill-Down, Trend-Chart, CSV-Export, Hochrechnung).
9. **Setup-Fee-Differenz-Logik (Block K) — fehlt.**
- `setup_fee_required`, `setup_fee_paid_at`, `one_time`-Interval-Handling, Differenz-Berechnung bei Up-Grade (`effective_setup_fee = neu - bisherig`, clamped ≥0).
10. **Layer-Trennung (AGENTS.md DoD A) — kompletter Umbau.**
- BP-Code mischt DB + UI in `apps/web/app/components/core/settings/subscription/*` und nutzt `.db.server.ts`/`.server.ts` direkt. HiveGrid verlangt: View-Models in `packages/view-models/`, UI in `packages/ui-hivegrid/` (kein Prisma-Import), Subframe via Adapter, Routes bauen VM. Alle BP-UI-Komponenten sind daher nur **als-vorlage** brauchbar, nicht 1:1.
11. **Apple-Compliance-Filter (LP-8 / 28.X.10) — neu durchzusetzen.**
- BP-UI enthält explizit Pricing/Plan-Vergleich/Upgrade/Toggle-Period (`Plans.tsx`, `Plan.tsx`, `ChangeSubscription.tsx`, `ToggleBillingPeriod.tsx`, `PlanChangePreviewModal.tsx`). Diese gehören in HiveGrid auf die Anti-Liste; in der App nur Read-Only + externer „Plan-Wechsel über hivegrid.de"-Link (`noopener noreferrer`).
12. **Querschnitt-Wiring (AGENTS.md DoD B/C) — anzudocken.**
- Sidebar-Eintrag „Subscription / Abo" (Gruppe EINSTELLUNGEN, INTEGRATION-CONTRACTS §1) + Permission-Gate, Breadcrumbs, i18n-Keys, `logActivity`, `notify()` statt direkter Mail, `withTenantScope()`/`withPermission()`, Permission-Keys `billing.read`/`tenant.admin` (Block N) in `packages/entitlements/src/permissions.ts`. In der BP nicht in dieser Form vorhanden.
13. **Demo-Buchung (Block L)** — bewusst extern (Calendly), kein Code nötig; nur `created_via=platform_admin`-Pfad.
---
## Empfohlenes Vorgehen (Reihenfolge)
**M153 — Stripe-Integration (zuerst, Fundament):**
1. `prisma/schema/subscriptions.prisma` als Migrations-Basis übernehmen; spec-Felder ergänzen (insb. `TenantSubscription.status`-Enum, fehlende Product/Price/Credit/CheckoutSession-Felder) und `Tenant.status`-Enum in `accounts.prisma` einführen.
2. `apps/web/app/utils/stripe.server.ts` 1:1 übernehmen (in HiveGrid-Domain-Layer `app/domain/billing/`); EU-Entity/Tax konfigurieren.
3. **`StripeWebhookLog`-Tabelle** neu + Webhook-Handler aus `apps/api/src/billing/stripe-webhook-route.ts` als Vorlage erweitern auf alle Pflicht-Events (Block C). Idempotenz über `stripe_event_id`-Unique. Outbox-/Transaktions-Muster der BP beibehalten.
4. Idempotenz/Cache aus `@toolctrl/shared-store` + `subscriptionCache.server.ts` (TTL auf 30 s).
**M154 — Plan-/Seat-Modell:**
5. Pricing-Config-Admin (`routes/admin/settings/pricing*.tsx`) anpassen → `admin.hivegrid.de` (datengetriebene Engine, Block A).
6. `packages/entitlements` als Feature-Gating übernehmen; globalen `SubscriptionFeature`-Katalog + `SubscriptionProductFeature`-M:N umbauen; HiveGrid-Plan-Codes/Blueprints einfüllen.
7. **Seat-Modell (Büro/Monteur) komplett neu** — neue Felder/Counter, Rolle↔Seat-Validierung, Quota-Enforcement, Stripe-`quantity`-Sync. Usage-Sicht `/{tenant}/admin/usage/`.
**M155 — Trial + Read-Only:**
8. Lifecycle-State-Machine + `Tenant.status`-Sync (Block B) neu; Übergangs-Hooks via Outbox (Audit/Activity/`notify()`).
9. **Read-Only-/Downgrade-Middleware (Block G) komplett neu** — Route-Guard + Worker-Guard + 402-API + UI-Disable; an Lifecycle gekoppelt.
10. Trial-Aktivierungs-Flow + Dunning (Block E/F): `trial-expiring-trigger.ts` erweitern (1-Tag), `requires_manual_activation`-Flow + Dunning-Counter + `invoice.payment_failed`-Handling.
11. Frozen-Modus (Block H) + Setup-Fee (Block K).
**M156 — Metering / Pay-as-you-go (vieles vorhanden):**
12. `packages/entitlements/ai-overage.ts` + `ai-quotas.ts` **1:1** übernehmen.
13. AI-Cost-Worker-Pipeline (`ai-cost-*`) übernehmen/anpassen (Stripe-Usage via `createMeterEvent`, Reconciliation, Notbremse-Alert 28.8.6).
14. AI-Credits-Saldo-Logik (`Credit`-Sum, Carry-Over, Pre-Check-Gate) + In-App-Sichten (Usage/AI-Credits, CSV-Export) neu bauen.
**Querschnitt (alle Milestones):** Layer-Trennung (View-Models + `ui-hivegrid` + Adapter), Sidebar/Permissions/Breadcrumbs/i18n, Apple-Compliance-Filter (keine Pricing/Upgrade-UI in der App).
---
## Notizen
- **Reuse-Grad HIGH** trägt v.a. von Daten-Modell, Stripe-Wrapper, Pricing-Admin und Pay-as-you-go-Engine. Die drei spec-kritischsten Bereiche — **Lifecycle-State-Machine, Seat-Modell Büro/Monteur, Read-Only-Middleware** — sind in der BP NICHT vorhanden und komplett neu (das senkt es vom theoretischen „high+" auf solides high).
- **Idempotenz-Konflikt:** Spec fordert `StripeWebhookLog`-Tabelle; BP nutzt Outbox-`dispatchKey`. Vor Bau entscheiden (Spec-Abweichung freigeben oder Tabelle bauen).
- **Apple-Compliance** ist das größte „Anti"-Risiko: die fertigen BP-UI-Komponenten (`Plans.tsx`, `ChangeSubscription.tsx`, `ToggleBillingPeriod.tsx`) verleiten zur Übernahme verbotener In-App-Pricing-UI. Nur Read-Only-Sichten + externer Link erlaubt.
- BP-API-Version `2025-10-29.clover` (`apps/web/app/utils/stripe.server.ts:35` ff.) — beim Übernehmen aktuell halten.
</content>
</invoke>
@@ -0,0 +1,97 @@
# Boilerplate-Abgleich — M29 Onboarding
- **Modul-ID:** M29 (Modul 29)
- **Name:** Onboarding
- **Milestones:** M157 (Wizard-Framework + State-Machine), M158 (SHK-Standard-Daten-Provisionierung), M159 (Branchen-Templates deklarativ), M160 (Demo-Daten + KI-Walkthrough)
- **Pflichtenheft-Block:** Block 7 (Plattform-Außenseite), Abschnitt Modul 29
- **Reuse-Level:** **low**
## Kurz-Verdikt
Die Boilerplate hat ein **vollständiges, reifes Onboarding-Subsystem** — aber es löst ein **anderes Problem** als M29. Das Boilerplate-Onboarding ist ein **Admin-konfigurierbares Produkt-Tour-/Announcement-System** (Modal/Page-Touren, Zielgruppen-Filter, Session-Tracking, Realtime-Trigger). M29 verlangt einen **branchen-getriebenen Post-Signup-Provisioning-Wizard**, der einem frischen Mandanten Pipelines, Rollen, Custom-Felder, Forms, Demo-Daten und eine Erste-Schritte-Checkliste einrichtet — aus **deklarativen YAML-Branchen-Templates**.
Die 7 Prisma-Modelle und die State-Machine-Logik (Session-Lifecycle: active → started → completed/dismissed, Step-Tracking mit seenAt/completedAt, Action-Log, Filter-Matching, Resume) sind als **konzeptionelle Vorlage und teils 1:1-Datenmodell-Basis** sehr wertvoll. Aber die fachliche Kern-Logik von M29 (Provisioning-Transaktion, deklarative Templates, Demo-Daten mit Demo-Flag, Erste-Schritte-Auto-Detection, KI-Walkthrough) existiert **nicht** und ist komplett neu zu bauen.
Querschnitt-Bausteine (Audit, i18n, Feature-Flag `onboarding`, Notifications, Tenant-Scope, Events) sind vorhanden und werden genutzt.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/onboarding.prisma` | 7 Modelle: `Onboarding`, `OnboardingFilter`, `OnboardingStep`, `OnboardingSession`, `OnboardingSessionAction`, `OnboardingSessionFilterMatch`, `OnboardingSessionStep` | **anpassen** — Modell-Namen + Grundstruktur (Session-Tracking, Step-Tracking, Action-Log, Filter-Match, `@@unique([onboardingId, userId, tenantId])`) decken Spec-Block A weitgehend. ABER: Spec verlangt zusätzliche Felder/Modelle (`industry_code`, `version`, `template_directory_path`, `OnboardingDemoProvisioning`, `OnboardingInvitationDispatch`, `OnboardingSessionStep.status`-Enum + `submitted_data`, `validation_rules`, `action_handler`, `step_type`). Felder erweitern. |
| `apps/web/app/modules/onboarding/services/OnboardingSessionService.ts` | Session-Lifecycle-State-Machine: `started`, `dismissed`, `setStep` (fromIdx/toIdx mit completedAt/seenAt), `complete`, `addActions` (Input-Dedup + Timestamps) | **als-vorlage** — exakt das resumable State-Machine-Verhalten aus 29.1.4 / M157. Logik-Muster (Step-Vor/Zurück, Action-Persistierung, Completion) übernehmen, fachlich auf 10-Step-Provisioning-Wizard ummünzen. |
| `apps/web/app/modules/onboarding/services/OnboardingService.ts` | Auto-Match-Logik: `getUserActiveOnboarding` (Erst-Login-Detection + Resume), `generateMatchingOnboardings`, `getMatchingFilters` | **als-vorlage** — deckt 29.1.2 (Auto-Redirect bei erstem Login), Filter-basiertes Onboarding-Matching (Spec `OnboardingFilter`/`OnboardingSessionFilterMatch`) und „nur eine aktive Session pro Tenant". Filter-Typ-Set muss um `industry`/`company_size` erweitert werden. |
| `apps/web/app/modules/onboarding/services/OnboardingFiltersService.ts` | Filter-Matching-Engine (`matches({userId, tenantId, filter})`) | **als-vorlage** — Operator/Filter-Auswertung; Spec braucht `equals/in/greater_than/less_than` (29.3-Branche, Größe). |
| `apps/web/app/modules/onboarding/services/step-registry/registry.server.ts` + `gating.server.ts` | Deklaratives Step-Registry mit Gating via Feature-Flag + Plan-Feature; `getVisibleOnboardingSteps`, `evaluateOnboardingStepGates` | **als-vorlage** — Muster für „Step nur sichtbar wenn Bedingung". Nützlich für „Coming soon"-Branche-Gating und optionale Steps (Logo, Demo-Daten). |
| `apps/web/app/modules/onboarding/routes/onboarding.$id.tsx` (`apps/web/app/routes/onboarding.$id.tsx`) | Route mit Loader/Action (CSRF, Owner-Check, Action-Dispatch: started/dismissed/add-actions/set-step/complete) | **als-vorlage** — Action-Dispatch-Shape + Owner-/CSRF-Guard für die `/onboarding/setup/`-Route (Spec Block I). |
| `apps/web/app/modules/onboarding/db/*.db.server.ts` (`onboarding`, `onboardingSessions`, `onboardingSessionSteps`) | DB-Layer mit `OnboardingWithDetails`/`OnboardingSessionWithDetails`-Includes, `createOnboardingSession` (mit Filter-Match-Anlage), Pagination | **anpassen** — DB-Zugriffsmuster + Include-Typen übernehmen; an erweiterte Felder/Modelle anpassen. |
| `apps/web/app/components/admin/SetupSteps.tsx` + `apps/web/app/application/dtos/setup/SetupItem.ts` | „Getting Started"-Widget: Liste von Items mit completed-Icon + CTA-Link, i18n-Key `onboarding.gettingStarted.title` | **als-vorlage** — direkte Vorlage für die Erste-Schritte-Checkliste (Block F / M158): Item mit Titel/Beschreibung/`completed`/`path`-CTA. ABER: kein Auto-Detection/Status-Tracking, keine Dismiss-Logik — neu zu bauen. |
| `apps/web/app/components/layouts/buttons/OnboardingButton.tsx`, `components/Onboarding*.tsx` (`OnboardingSession.tsx`, `OnboardingBadge.tsx`, `OnboardingSessionBadge.tsx`) | UI-Renderer für Session/Block, Trigger-Button | **als-vorlage** — UI-Mechanik (Modal/Page-Rendering, Block→Step-Mapping). HiveGrid baut UI ohnehin neu via Subframe + ui-hivegrid-Adapter; nur Verhaltensmuster ableiten. |
| `apps/web/app/modules/events/services/.server/EventsService.ts` + DTOs `OnboardingStarted/Completed/DismissedDto.ts` | Event-Emission bei Onboarding-Lifecycle | **1:1** als Wiring-Pattern — fügt sich in M001-Audit / M045-Activity / M011-Notify ein. |
| `apps/web/app/utils/db/appConfiguration.db.server.ts` (Zeile 78, 184: `onboarding.enabled`) | App-Config-Flag `onboarding.enabled` | **1:1** — Modul-Abschaltbarkeit (DoD-Feature-Flag). |
| `packages/foundation` `featureKeys` enthält `onboarding` (Inventur `foundation.md:93`) | Kanonischer Feature-Key `onboarding` für Entitlement-Gating | **1:1** — Feature-Flag-Gate aus DoD. |
| `apps/web/app/utils/db/seed/SeedService.ts` (`seedDemoProductCoreTenant`, `seedDemoTenantRoles`, `seedDemoTenantKnowledgeBase`, `seedDemoSupportTickets`, `assignTenantPlan`) | Per-Tenant-Seeding-Muster (Rollen, KB, Tickets, Plan-Zuordnung, upsert-basiert idempotent) | **als-vorlage** — bestes vorhandenes Vorbild für die SHK-Provisionierung (M158) und Demo-Daten (M160). Aber: hardcoded (kein deklaratives Template), keine Transaktion/Rollback, kein Demo-Flag, kein SHK-Inhalt → nur Struktur-Vorlage. |
| `prisma/schema/imports.prisma` (`ImportJob`) + `@toolctrl/imports` | Async-Import-Job-Infrastruktur (Status, Row-Counts, Error-Report) | **als-vorlage** — relevant für Phase-2-CSV-Bulk-Import (29.X.3, out of scope Phase 1). |
| `packages/email-templates/src/sequences/` (welcome, trial-reminder, re-activation) + `packages/mail/.../Invitation` Template | Lifecycle-/Einladungs-Mails | **als-vorlage / 1:1** — Mitarbeiter-Einladungs-Mail (29.5) läuft über M27/M24-Invitation-Flow; Welcome-Mail vorhanden. |
---
## Vorhandene Daten-Modelle (konkret)
In `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/onboarding.prisma`:
- **`Onboarding`** — `id`, `title`, `type` (modal/page), `realtime`, `active`, `canBeDismissed`, `height`; Relationen zu Filters/Steps/Sessions.
- Spec-Mapping: deckt `Onboarding` teilweise. **Fehlt:** `code`, `display_name`/`description` getrennt, `industry_code`, `version`, `template_directory_path`. (`active` ↔ `is_active`/„Coming soon").
- **`OnboardingFilter`** — `onboardingId`, `type`, `value`.
- Spec-Mapping: ↔ `OnboardingFilter`. **Fehlt:** `criterion_key`/`operator`/`criterion_value`-Struktur (Spec hat explizite Operatoren; BP hat nur `type`+`value`-String).
- **`OnboardingStep`** — `onboardingId`, `order`, `block` (JSON-String mit Block-DTO).
- Spec-Mapping: ↔ `OnboardingStep`. **Fehlt:** `code`, `display_name`, `step_type` (info/form/action/confirmation), `is_skippable`, `validation_rules`, `action_handler`. (BP kodiert UI im JSON-`block`, Spec will strukturierte Felder.)
- **`OnboardingSession`** — `onboardingId`, `userId`, `tenantId?`, `status` (active/started/completed/dismissed), `startedAt`/`completedAt`/`dismissedAt`, `createdRealtime`; `@@unique([onboardingId, userId, tenantId])`.
- Spec-Mapping: ↔ `OnboardingSession`. Sehr gute Basis. **Fehlt:** `current_step_id`, `started_by_user_id` (vs. `userId`), `payload` (JSONB-Antworten), Spec-Unique nur `(tenant_id, status='in_progress')`.
- **`OnboardingSessionAction`** — `onboardingSessionId`, `type`, `name`, `value`.
- Spec-Mapping: ↔ `OnboardingSessionAction`. **Fehlt:** `step_id`, `action_type`-Enum (step_entered/completed/skipped/data_saved/external_call), `payload`-JSON, `actor_user_id`, `created_at`-Index. (Audit/Replay-Anbindung erweitern.)
- **`OnboardingSessionFilterMatch`** — `onboardingFilterId`, `onboardingSessionId`.
- Spec-Mapping: ↔ `OnboardingSessionFilterMatch`. **Fehlt:** `matched_value`.
- **`OnboardingSessionStep`** — `onboardingSessionId`, `stepId`, `seenAt`, `completedAt`.
- Spec-Mapping: ↔ `OnboardingSessionStep`. **Fehlt:** `status`-Enum (pending/in_progress/completed/skipped), `submitted_data`.
**Nicht vorhanden (neue Modelle nötig):** `OnboardingDemoProvisioning` (Demo-Tracking, `entities_created`, `provisioning_log`, `removable_until`) und `OnboardingInvitationDispatch` (FK auf M27 `TenantUserInvitation`, `bulk_batch_id`).
**Kein Branchen-/Industry-Konzept im Schema** (`grep -niE "industry|branche|trade" prisma/schema` → leer). **Kein Demo-Flag** (`isDemo`/`is_demo_data`) auf irgendeiner Entität.
---
## Lücken / komplett neu zu bauen
1. **Branchen-getriebene deklarative Templates (M159, Spec Block C, A.3):** Es gibt **keine** YAML-/Verzeichnis-basierte Template-Engine. Keine `yaml`/`js-yaml`-Dependency (`grep` → leer). Komplett neu: Verzeichnis-Struktur `templates/onboarding/<branche>/{onboarding,pipelines,forms,custom-fields,permissions,demo-data,checklist}.yml`, Loader beim System-Start, Sync nach `Onboarding`/`OnboardingStep`/`OnboardingFilter`, Build-Validierung pro Template. Das BP-Onboarding ist DB-konfiguriert (Admin-UI), nicht template-getrieben.
2. **SHK-Smart-Setup-Provisioning-Transaktion (M158, Spec Block D):** Auto-Anlage von Pipelines, Custom-Feldern, Rollen+Permissions, Form-Templates, Marketing-Templates, Notification-Sets, Dashboards — **als Transaktion (alles oder nichts) mit Rollback + Retry + Plattform-Admin-Alert bei Fehler**. `SeedService.ts` ist nur eine grobe Struktur-Vorlage (hardcoded, keine TX, keine Branchen, keine SHK-Inhalte). Die konkreten SHK-Defaults (10 Rollen, 2 Sales-/3 Auftrags-Pipelines, SHK-Custom-Felder, 8 Form-Vorlagen) existieren nirgends.
3. **Demo-Daten-Provisioning + Demo-Flag (M160, Spec Block E):** Kein `is_demo_data`-Flag auf Entitäten, kein „Demo-Daten ausblenden"-Filter in Listen, kein Bulk-Lösch mit Multi-Step-Confirm, keine `OnboardingDemoProvisioning`-Verfolgung. SHK-Demo-Inhalte (10 Kontakte, 3 Firmen, 5 Deals, 1 Projekt mit Chat/Tasks/Foto-Checkliste, 1 Lead, 5 Dateien, Booking-Page) komplett neu.
4. **Erste-Schritte-Checkliste mit Auto-Detection (M158, Spec Block F):** `SetupSteps.tsx` liefert nur die statische Anzeige. Es fehlt: deklarative Item-Definition (`first-steps.yml`), Detection-Rules (KWP-Verbindung, Mailbox, AirCall, Booking-Page, Einladung, Automation, Form, Deal-Stage-Change), Status-Tracking/Cache, manuelles Erledigt-Markieren, dauerhaftes Ausblenden, 100%-Glückwunsch.
5. **KI-Walkthrough (M160, Spec Block H):** Existiert nicht. Muss als System-Prompt-Modus „onboarding-walkthrough" auf M18-Tenant-Assistant aufsetzen, mit Action-Boundary (AV #20: nur navigieren/erklären, kein Schreiben), Permission-aware Kontext, User-Settings-Toggle `ai_walkthrough_offered`. (Der Boilerplate-`chatbot` existiert, aber kein Walkthrough-Modus.)
6. **Vollbild-Wizard-Route `/onboarding/setup/` (M157, Spec Block B/I):** BP hat nur `onboarding.$id` (Session-by-id, modal/page-Tour) und `admin/onboarding/*` (Admin-Verwaltung). Der 10-Schritte-Vollbild-Wizard ohne Sidebar, mit den HiveGrid-spezifischen Steps (Firmendaten, Branche-Bestätigung mit „Coming soon", Größe, Logo-Upload, Smart-Setup-Vorschau mit Toggle pro Template-Gruppe, Demo-Daten-Frage, Mitarbeiter-Einladung) ist neu — inkl. UI via Subframe + ui-hivegrid-Adapter.
7. **Logo-Upload-Pipeline (Spec 29.2.5):** PNG/JPG/SVG, max 2 MB, Format-/Größen-Validierung mit Klartext-Fehlern — neu (gemeinsam mit M23 Files).
8. **Mitarbeiter-Einladung im Wizard (M160, Spec Block G):** Inline-Email+Rolle-Zeilen, Live-Validierung, Duplikat-Check, „Vertriebler"-Default, „Später"-Skip → nutzt M27/M24-Invitation-Flow; `OnboardingInvitationDispatch`-Tracking neu.
9. **Permissions `onboarding.run` / `onboarding.demo_data.manage` / `onboarding.checklist.dismiss` (Spec Block J):** Im BP-Onboarding läuft Zugriff über User-Owner-Check + `admin`-Flag, nicht über HiveGrid-Permission-Keys (M004). Neu zu definieren in `packages/entitlements/src/permissions.ts` + Bundle-Mapping.
10. **HiveGrid-Layer-Trennung (AGENTS.md DoD):** Das BP-Onboarding mischt DB-Zugriff, Server-Logik und React-Components im selben `modules/onboarding`-Ordner. Für HiveGrid muss alles auf View-Model-Layer (`packages/view-models`), Domain-Layer (`app/domain`), ui-hivegrid + Subframe-Adapter umstrukturiert werden. Kein 1:1-Übernehmen der Datei-Struktur möglich.
---
## Empfohlenes Vorgehen
**Reihenfolge (BP-Vorlage zuerst, dann Neues):**
1. **Datenmodell zuerst (Basis für alle 4 Milestones):** `onboarding.prisma` aus BP als Start kopieren, dann gemäß Spec Block A erweitern: Step-Felder (`code`, `step_type`, `is_skippable`, `validation_rules`, `action_handler`), Session (`current_step_id`, `payload`), Filter (`criterion_key`/`operator`/`criterion_value`), Action (`action_type`-Enum, `payload`, `actor_user_id`). Zwei neue Modelle `OnboardingDemoProvisioning` + `OnboardingInvitationDispatch`. Industry-Felder (`industry_code`, `version`, `template_directory_path`). Forward-Only-Migration mit Inverse-SQL.
2. **M157 Wizard-Framework:** Die State-Machine aus `OnboardingSessionService.ts` (started/setStep/complete/dismissed + Resume-Logik aus `OnboardingService.getUserActiveOnboarding`) als Vorlage in HiveGrid-Domain-Layer portieren. Neue Vollbild-Route `/onboarding/setup/` + `/onboarding/setup/step/{code}/`. View-Model + Subframe-UI. Erst-Login-Detection (29.1.2) aus BP-`generateMatchingOnboardings` ableiten.
3. **M159 Branchen-Templates (Fundament für M158):** Deklarative YAML-Engine **komplett neu** (yaml-Dependency hinzufügen, Verzeichnis-Loader, Sync-Service, Build-Validierung). Phase 1 nur `shk` aktiv, andere als `is_active=false` „Coming soon". Das ist der größte Neubau-Block — kein BP-Vorbild.
4. **M158 SHK-Provisioning:** `SeedService.ts`-Muster (per-Tenant upsert, Rollen/KB/Tickets) als Struktur-Vorlage, aber auf Transaktion + Rollback + Retry umbauen und aus M159-Templates speisen. Erste-Schritte-Checkliste: `SetupSteps.tsx`/`SetupItem` als UI-Vorlage, Detection-Rules + Status-Tracking neu.
5. **M160 Demo-Daten + KI-Walkthrough:** Demo-Flag-Spalte auf relevanten Entitäten + Listen-Filter + Bulk-Lösch neu. Demo-Seeding aus YAML-Template (M159). KI-Walkthrough als neuer System-Prompt-Modus auf M18-Assistant mit Action-Boundary. Mitarbeiter-Einladung über M27/M24-Flow + `OnboardingInvitationDispatch`.
6. **Querschnitt durchgängig:** Feature-Key `onboarding` (foundation) + `appConfiguration.onboarding.enabled` 1:1 nutzen. Events (`EventsService` + Onboarding-DTOs) als Wiring-Pattern → M001-Audit / M045-Activity / M011-Notify. Permission-Keys (`onboarding.*`) neu in M004-Registry. i18n-Keys (BP hat bereits `onboarding.*`-Keys als Namensraum-Vorlage).
**Wichtig:** Das BP-Onboarding NICHT als fertiges Modul „aktivieren" — es ist ein Tour-System, nicht der M29-Provisioning-Wizard. Es dient als **Daten-Modell-Basis + State-Machine-Vorlage + Wiring-Muster**, nicht als lauffähige Lösung.
@@ -0,0 +1,98 @@
# Boilerplate-Abgleich — Modul M30: i18n / Mehrsprachigkeit
- **Modul-ID:** M30 (Spec `_bmad-output/specs/M30-i18n.md`)
- **Name:** i18n / Mehrsprachigkeit
- **Zugehörige Milestones:** M028 (User/Tenant Sprach-Settings + Auflösungs-Reihenfolge), M029 (Sprach-Wechsler + Fallback-Hinweise). Querschnitt-Vorbedingung: M003 (i18n-Pflicht-Wiring).
- **Achtung Numerik-Stolperfalle:** Das Repo-Milestone-Verzeichnis `docs/milestones/M030-hell-dunkel-modus` ist NICHT dieses Modul (das ist Hell/Dunkel-Modus). Modul-Spec „M30" = Milestones M028+M029.
- **Pflichtenheft-Block:** Block 1, Modul 30 (`_bmad-output/pflichtenheft/blocks/block1.md` Abschnitte 30.1–30.6)
- **Reuse-Level:** **HIGH** — vollständige i18n-Library + App-Wiring + CI-Gates bereits vorhanden; HiveGrid füllt vor allem Inhalte (Locale-Keys, TR/PL) ein und ergänzt zwei Datenmodell-Felder + zwei Resolver-Schritte.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/i18n/` | Eigenständiges `@toolctrl/i18n`-Paket: Locale-Config, ICU-MessageFormat-Plurale, SSR-sichere Intl-Formatter (Zahl/Währung/Datum/RelativeTime/Liste), RTL-Erkennung, `useTranslate`-Factory | **1:1** (Paket nur umbenennen `@toolctrl/i18n`→`@hivegrid/i18n`; Logik unverändert) |
| `…/packages/i18n/src/index.ts` | `defaultLocale="de"`, `supportedLocales=["de","en"]`, `i18nNamespaces`, `i18nConfig`, `isSupportedLocale`, `getDirection`, `isRTL` | **anpassen** — `supportedLocales` auf `["de","en","tr","pl"]` erweitern; Namespaces auf HiveGrid-Module mappen |
| `…/packages/i18n/src/icu/plural.ts` | `formatIcu`, `createIcuFormatter` (FormatJS/CLDR-Plural-Regeln, deckt PL 3-Form-Plurale ab) | **1:1** — erfüllt Spec A.1.3 (ICU-Plural) komplett |
| `…/packages/i18n/src/intl/{number,currency,date,list}.ts` | Locale-explizite Intl-Wrapper, gecacht, SSR-safe | **1:1** — erfüllt Spec A.1.4 (Intl-Formate) |
| `…/packages/i18n/src/useTranslate.ts` | `createUseTranslate(deps)` — react-i18next injiziert (kein harter Dep), automatische ICU-Erkennung | **1:1** |
| `…/apps/web/app/locale/i18next.server.ts` | Server-Loader: `remixI18Next` (remix-i18next), `i18nCookie` (`_i18n`, 30 Tage), `getTranslations(request, ns)`, fs-Backend pro `{{lng}}/{{ns}}.json` | **anpassen** — erfüllt D.3 (Sprache pro Request im Loader) + Cookie-Persistenz (D.4); Resolution-Order erweitern (siehe Lücken) |
| `…/apps/web/app/locale/i18next.global.server.ts` | Globale i18next-Instanz für SSR (verhindert Flash/Hydration-Mismatch, lädt alle Locales synchron vorab) | **1:1** — erfüllt D.3 „SSR rendert sofort korrekt ohne Flash-of-DE" |
| `…/apps/web/app/locale/mail-translator.server.ts` | `getMailTranslator(locale)`, `getMailTranslatorFromRequest(request)`, `resolveMailLocale` (Fallback auf `defaultLocale`), `mail`-Namespace | **anpassen** — Basis für Block F (Outbound-Email i18n); Empfänger-Auflösung D.2 ergänzen (User/Contact/Tenant-Default) |
| `…/apps/web/app/components/ui/selectors/LocaleSelector.tsx` | Sprach-Dropdown, submitted an `/preferences` (`action=setLocale`), iteriert `i18nConfig.supportedLngs` | **als-vorlage** — Public-Page-Switcher (G.3) + Header-Switcher (D.4); UI in HiveGrid-Design neu bauen (Subframe), Logik übernehmen |
| `…/apps/web/app/routes/preferences.tsx` | Root-Action `setLocale`, schreibt Locale-Cookie, Reload-frei | **anpassen** — erfüllt D.4 (Live-Wechsel ohne Reload); zusätzlich `User.locale` in DB persistieren bei eingeloggtem User |
| `…/apps/web/app/modules/users/components/UserProfileSettings.tsx` (Picker referenziert in `…/routes/app.$tenant/settings/profile.locale-picker.test.ts`) | Locale-Picker im User-Profil, `i18nConfig.supportedLngs`, `changedLocale()`, `setLocale`→`/preferences` | **als-vorlage** — Basis für G.1 (`/{tenant}/settings/profile/`); Zeitzone+Datumsformat-Picker fehlen noch |
| `…/scripts/i18n-check.ts` | Locale-Parity-Checker: Key-Divergenz pro Namespace, fehlende/leere Files, **Waisen-Keys** (`unexpected-locale-dir`), **fehlende Source-Keys** (`t("…")` ohne Locale-Eintrag), leere Übersetzungen | **1:1** — erfüllt B.3 (Vollständigkeits-Check, Waisen-Keys, Master=DE) nahezu komplett |
| `…/scripts/verify-hardcoded-strings.mjs` (+ `.test.mjs`) | Build-Lint gegen hartkodierte User-facing Strings über `apps/packages/prisma/server`, mit Allowlist (`reviewedPathPatterns`) | **1:1 / anpassen** — erfüllt A.1.5 (Lint-Regel im Build) + Allowlist-Mechanik (offener Spec-Punkt „Lint-Regel-Allowlist-Spec") |
| `…/scripts/i18n-audit.mjs` + `verify-i18n-hardcoded-baseline.mjs` | Baseline-Scan hartcodierter DE/EN-Strings (zählt, erzwingt nicht — Migrations-Hilfe) | **als-vorlage** — nützlich beim schrittweisen Härten der Lint-Regel |
| `package.json` Script `verify:i18n` | `tsx scripts/i18n-check.ts && node scripts/verify-hardcoded-strings.mjs && eslint --max-warnings=0 packages/ui-*` | **1:1** — fertiges CI-Gate für DoD-Punkt 10 (i18n-Keys Pflicht) |
| `…/apps/web/app/modules/i18n/locale-coherence.test.ts` | Cross-Language-Copy-Leak-Test (DE-Wörter im EN-Catalog etc.) | **als-vorlage** — Inhalt ist boilerplate-spezifisch (Tenant→Konto-Wording), Struktur als Vorlage für HiveGrid-Glossar-Tests |
| `…/apps/web/app/modules/i18n/autogenerated-locale-prune.test.ts` | Prune-Test: Locale-Keys ohne Source-Referenz markieren | **anpassen** — ergänzt Waisen-Key-Erkennung (B.3) |
| `…/apps/web/app/utils/i18n/translateLabel.ts` (+ `.test.ts`) | Helper zum Übersetzen von Label-Keys | **als-vorlage** |
| `…/apps/web/public/locales/{de,en}/*.json` (9 Namespaces: translations, auth, billing, common, crm, emailMarketing, errors, mail, settings) | Befüllte DE+EN-Locale-Files | **als-vorlage** — Struktur/Konvention übernehmen, Inhalte sind ToolCTRL-spezifisch und werden durch HiveGrid-Keys ersetzt |
| `package.json` deps | `i18next ^23`, `react-i18next ^15`, `remix-i18next ^7`, `i18next-fs-backend`, `i18next-http-backend`, `i18next-browser-languagedetector`, `intl-messageformat ^10` | **1:1** — kompletter Stack vorhanden, keine neuen Libs nötig (klärt Spec-offenen-Punkt „i18n-Library-Wahl" → react-i18next ist gesetzt) |
---
## Vorhandene Daten-Modelle
| Modell / Feld | Pfad | Status gegen Spec |
| --- | --- | --- |
| `User.locale` (`String?`) | `…/prisma/schema/accounts.prisma:16` | **vorhanden** — deckt C.1 `language` ab (als freier String, nicht Enum `de\|en\|tr\|pl`). Reicht funktional, ggf. Enum-/Validierung in App-Layer ergänzen |
| `User.lightOrDarkMode` (`String?`) | `…/prisma/schema/accounts.prisma:17` | vorhanden (gehört zu M030 Hell/Dunkel, nicht i18n — nur Kontext) |
| `Tenant` (Modell, Felder `theme`, `themeConfig`) | `…/prisma/schema/accounts.prisma:129` | Tenant existiert, **aber KEIN `default_language`/`locale`-Feld** → siehe Lücken (C.2) |
| `Portal.locale` (`String?`) | `…/prisma/schema/portals.prisma:67` | vorhanden (Customer-Portal-Locale; relevant für Public-Portal-Sprachauflösung) |
| `KnowledgeBase.defaultLanguage` / `.languages` / `Article.language` | `…/prisma/schema/knowledgeBase.prisma:12,16,37,73` | vorhanden — Basis für Help-Center-Mehrsprachigkeit (G.3, Phase 2 / Modul 38) |
| FeatureFlag-Filter-Typ `language.is` | `…/prisma/schema/featureFlags.prisma:37` | vorhanden — Sprache als Targeting-Dimension nutzbar |
**Datenmodell-Fazit:** `User`-Sprache ist da; `Tenant`-Default-Sprache, `User.timezone` und `User.date_format_preference` sind NICHT vorhanden.
---
## Lücken / komplett neu zu bauen
1. **`Tenant.default_language` fehlt** (Spec C.2). `Tenant` (`…/prisma/schema/accounts.prisma:129`) hat nur `theme`/`themeConfig`, kein Sprach-Default. → Neues Feld + Forward-Only-Migration. Blockt M028 (Mandanten-Default in Auflösungs-Reihenfolge).
2. **`User.timezone` und `User.date_format_preference` fehlen** (Spec C.1). Nirgends in `prisma/schema/*.prisma` ein `timezone`/`dateFormat`-Feld (grep leer). → Zwei neue `User`-Felder. Profil-Picker für Zeitzone/Datumsformat (G.1) gibt es noch nicht (nur Locale-Picker vorhanden).
3. **Resolution-Order unvollständig** (Spec D.1 / Pflichtenheft 30.2.4). Boilerplate-`remixI18Next` löst Cookie → Browser-`Accept-Language` → Fallback `de`. Es fehlt der **`Tenant.default_language`-Schritt** (User > **Tenant** > Browser > DE) und das Lesen von `User.locale` aus DB nach Login. → Resolver-Funktion `resolveLocale(user, tenant, browser, default)` in `app/locale/**` ergänzen (M028 Slice-Hinweis nennt exakt diese Signatur).
4. **Outbound-Empfänger-Auflösung D.2 fehlt** (Pflichtenheft 30.2.5). `mail-translator.server.ts` löst nur eine übergebene Locale; die Kette „User.language > Contact.language > Tenant.default_language > de" muss neu gebaut werden. Setzt `Contact.language` voraus (Modul 1 — im aktuellen Schema kein CRM-`Contact`-Modell mit `language` gefunden).
5. **TR/PL-Locales fehlen** (Spec B.4 / Pflichtenheft 30.1.6). Nur `de`+`en` in `…/apps/web/public/locales/`. Phase-1-Pflicht ist nur DE befüllt — aber `supportedLocales` muss `tr`/`pl` als Ziel-Sprachen kennen (für „Coming soon"-Anzeige G.1 und Fallback-Hinweise H/I). Der Parity-Checker würde leere `tr`/`pl`-Files als Divergenz melden → Strenge anpassen (Spec B.4: andere Locales dürfen Phase 1 teilbefüllt sein, Fallback auf DE).
6. **`errors.*`-Namespace-Struktur** (Spec B.2 / LP-10). Boilerplate hat zwar einen `errors`-Namespace, aber die geforderte Sub-Key-Struktur `errors.<x>.headline / .body / .action_label` ist HiveGrid-spezifisch und muss als Konvention etabliert/befüllt werden (koppelt an M002 Error-Catalog).
7. **Fallback-Debug-Marker (Dev) + Klartext-Hinweise** (Spec B.4, H, I.). „Lokalisierung für [Sprache] noch nicht vollständig — Fallback auf Deutsch" (Dev), „Sprache geändert." etc. — als Locale-Keys + Dev-Mode-Marker neu. remix-i18next macht silenten Fallback (Prod ok), Dev-Marker fehlt.
8. **Settings-Routen für HiveGrid-URL-Schema** (Spec G.1/G.2). Boilerplate-Profil-Route liegt unter `app.$tenant/settings/profile`; HiveGrid-Pattern ist `/{tenant}/settings/profile/` und `/{tenant}/admin/general/` (Tenant-Default-Sprache, Permission `tenant.admin`). Tenant-Default-Picker existiert noch gar nicht.
9. **Public-Page-Sprach-Switcher mit Cookie** (Spec G.3 / M029 / Pflichtenheft 30.4.2). `LocaleSelector.tsx` existiert als Footer-Switcher, aber dedizierter Public-Page-Switcher (Help `/help/{lang}/…`, Booking, Forms) mit `httpOnly:false, samesite:lax`-Cookie (M029-Slice-Hinweis) ist neu. URL-Sprachsegment `/help/{lang}/{slug}` (Integration-Contracts §3) noch nicht verdrahtet.
10. **`.server.ts`-Memory-Blocker prüfen.** Boilerplate nutzt `i18next.server.ts` / `i18next.global.server.ts`. Laut User-Memory (S03) ist `.server.ts`-**Re-Export** inkompatibel mit RR7-Client-Build. Diese Dateien sind server-only Logik (kein Client-Re-Export) → vermutlich unkritisch, aber bei Übernahme verifizieren, dass keine Client-Komponente daraus importiert (Component-Extraktion-Regel beachten).
11. **Layer-Trennung (AGENTS.md).** Boilerplate-Locale-Logik liegt in `apps/web/app/locale`. HiveGrid-DoD verlangt VM-Layer + `packages/ui-hivegrid`-Adapter; Locale-Switcher als reusable Component in `packages/ui-hivegrid` (M029-Hinweis) — Adapter neu, Logik aus Boilerplate.
**Explizit NICHT in Phase 1 (Spec 30.5 / Block I.):** DeepL-Pipeline, Auto-Chat-Übersetzung, mehrsprachige Mandanten-Inhalte, mehrsprachiges Help-Center. Boilerplate liefert dafür kein Fundament (außer KnowledgeBase-Sprach-Felder) — korrekt, da out-of-scope.
---
## Empfohlenes Vorgehen
**Phase A — Foundation übernehmen (1:1, schnell):**
1. `packages/i18n` als `@hivegrid/i18n` übernehmen (Plurale, Intl-Formatter, `useTranslate`, ICU) — unverändert.
2. CI-Gate `verify:i18n` (`i18n-check.ts` + `verify-hardcoded-strings.mjs` + ESLint) übernehmen → erfüllt direkt DoD-Punkt 10 + Spec A.1.5/B.3.
3. App-Wiring übernehmen: `i18next.server.ts`, `i18next.global.server.ts` (SSR-Flash-Schutz), `preferences.tsx`-Action (`setLocale` + Cookie). `.server.ts`-Import-Pfade gegen RR7-Client-Build verifizieren (Memory S03).
4. react-i18next-Stack als gesetzte Library-Wahl dokumentieren (schließt Spec-offenen-Punkt).
**Phase B — Datenmodell ergänzen (M028 Vorbedingung):**
5. Migration: `Tenant.default_language`, `User.timezone`, `User.date_format_preference` (Forward-Only + Inverse-SQL-Kommentar). `User.locale` bleibt.
6. `supportedLocales` → `["de","en","tr","pl"]`; `de` als Master. Parity-Checker so konfigurieren, dass teilbefüllte `tr`/`pl` Phase 1 nicht hart blocken (Spec B.4).
**Phase C — Resolver + Outbound (M028 Kern):**
7. `resolveLocale(user, tenant, browser, default)` neu — Tenant-Default-Schritt in die Kette einfügen (D.1).
8. Outbound-Empfänger-Auflösung D.2 in `mail-translator.server.ts`-Erweiterung (User > Contact > Tenant > de). Setzt `Contact.language` aus Modul 1 voraus (Abhängigkeit prüfen).
**Phase D — UI/Settings (M028 G.1/G.2 + M029):**
9. User-Profil-Picker (`/{tenant}/settings/profile/`): Locale-Picker (aus Boilerplate-Vorlage) + neue Zeitzone-/Datumsformat-Picker; „Coming soon" für tr/pl. Reload-free via `/preferences`.
10. Tenant-General-Picker (`/{tenant}/admin/general/`) für `Tenant.default_language`, Permission-Gate `tenant.admin` (M004 `withPermission`).
11. Public-Page-Switcher mit Cookie (`samesite:lax`, nicht-httpOnly) als reusable Component in `packages/ui-hivegrid` (M029); URL-Sprachsegment `/help/{lang}/…` verdrahten.
12. Klartext-Hinweise + Dev-Fallback-Marker als Locale-Keys; `errors.*`-Sub-Key-Struktur (headline/body/action_label) mit M002 koppeln.
**Phase E — Layer-Konformität + Tests:**
13. Locale-Switcher + Picker via VM-Layer + `ui-hivegrid`-Adapter (AGENTS.md A.1–A.5); keine `useLoaderData` in UI-Components.
14. Tests: VM-Builder-Unit-Tests, Smoke-Tests (Sprach-Wechsel live, Public-Booking-Cookie, unvollständiges Test-Locale → 30.6.1-Hinweis), Hot-Swap-Drill, Visual-Snapshot. Parity-/Prune-Tests aus Boilerplate adaptieren.
**Reihenfolge-Kern:** Erst alles aus BP übernehmen (Phase A) → dann die 3 fehlenden DB-Felder + tr/pl (B) → dann die 2 fehlenden Resolver-Schritte (C) → erst danach UI/Settings (D) → Layer/Tests (E).
@@ -0,0 +1,122 @@
# Boilerplate-Abgleich — M31 Branding / Theme
| Feld | Wert |
|------|------|
| **Modul-ID** | M31 |
| **Name** | Branding / Theme |
| **Milestones** | M030 (Hell/Dunkel-Modus + Capacitor-Status-Bar) — Phase 1. (Spec-Quelle `_bmad-output/specs/M31-branding.md`; LP-9. Phase-2-Features E.1-E.6 ohne eigenes Milestone in `docs/milestones/`.) |
| **Block** | Block 1, Abschnitt 31.1 (`_bmad-output/pflichtenheft/blocks/block1.md`) |
| **Reuse-Level Phase 1** | **medium** — solide Light/Dark-Basis vorhanden, aber binär statt drei-modig; "system"-Modus + Live-Reaktivität fehlen |
| **Reuse-Level Phase 2** | **medium-high** — Tenant-Theme-Engine (Farben/CSS-Vars), System-Branding-Felder (Logo/Favicon) und Mail-Brand-Tokens existieren als starke Vorlage |
> **WICHTIG zur Milestone-Benennung:** Das Milestone-Verzeichnis `docs/milestones/M031-feature-flag-schalter-lifecycle/` gehört NICHT zu diesem Modul (das ist Feature-Flags). Das fachlich passende Milestone für M31 Branding/Theme Phase 1 ist **`docs/milestones/M030-hell-dunkel-modus/`**.
> **Hinweis zur PLAN.md-Annahme:** `M030/PLAN.md` nennt „`next-themes` bereits in Boilerplate-Deps". Das ist **falsch verifiziert** — `next-themes` taucht in der Boilerplate nur in `apps/web/app/utils/build/buildWarningTriage.ts` (Build-Warnungs-Triage) auf, NICHT als aktive Theme-Lib. Die reale Boilerplate nutzt ein **eigenes Session/Cookie-basiertes Dark-Mode-System** (siehe unten). Slice-Planung muss das korrigieren.
---
## Was das Modul fachlich braucht (aus Spec)
**Phase 1 (M030 / minimal):**
- A: `User.theme_preference` Enum `system | light | dark`, Default `system`
- B: User-Settings-Route `/{tenant}/settings/profile/` mit 3-Optionen-Picker, sofortige Anwendung ohne Reload
- C: Theme-Auflösung (User-Pref → `prefers-color-scheme` → Light-Fallback), Live-Reaktivität bei `system` (matchMedia-Listener), SSR-No-Flash via Cookie/Header, Anwendung in Web (`dark:`-Class) + Capacitor (Status-Bar/Splash)
- D: keine Permissions in Phase 1
**Phase 2 (E.1-E.6, später):** TenantBranding-Tabelle (Logo, primary/accent-color, display-name), `/{tenant}/admin/branding/`, Logo-Upload, Farb-Picker mit Live-Preview, Branding in Email/Portal/Login/Splash, White-Label (custom_domain, custom fonts, theme_variables JSONB), Permissions `branding.admin` + `branding.white_label` (Enterprise-Gate via M27).
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/accounts.prisma:17` | `User.lightOrDarkMode String?` — Per-User Hell/Dunkel-Präferenz | **anpassen** — Feld existiert, ist aber binär (`light`/`dark`, nullable). Muss zu 3-Wert-Enum `system\|light\|dark` mit Default `system` erweitert/migriert werden |
| `apps/web/app/root.tsx:97-100` | SSR-Anwendung der `dark`-Klasse auf `<html>` aus `userSession.lightOrDarkMode` (gated über `DARK_MODE_IN_APP`) | **als-vorlage** — No-Flash-Mechanik via Session vorhanden; muss um `system`-Auflösung (`prefers-color-scheme`) + Cookie-Header-Lesung erweitert werden |
| `apps/web/app/root.tsx:184-213` | Action `toggleLightOrDarkMode` (+ `setTheme`, `setLocale`): persistiert in User-DB + Session, feuert `EventsService.create` Audit-Event `user.preferences.updated` | **als-vorlage** — Persist-Pfad + Audit-Wiring vorhanden; Toggle→3-Wert-Set umbauen |
| `apps/web/app/routes/preferences.tsx` | Dedizierte `/preferences`-Action-Route, an die Toggle/Selector posten | **anpassen** — Endpoint-Pattern wiederverwenden; Action für 3-Wert-Preference ergänzen |
| `apps/web/app/utils/theme/userThemePreference.server.ts` | `LIGHT_OR_DARK_MODES`, `normalizeLightOrDarkMode`, `nextLightOrDarkMode`, `persistUserLightOrDarkMode(userId, …)` | **anpassen** — Normalisierung/Persist als Basis; Enum um `system` erweitern, Auflösungs-Helfer (`resolveEffectiveTheme`) neu ergänzen |
| `apps/web/app/components/ui/toggles/DarkModeToggle.tsx` (`DarkModeToggle`, `DarkModeSvgs`) | Binär-Toggle-Button mit i18n-Label + Analytics-Event | **als-vorlage** — für 2-Wert; für Phase-1-Spec (3 Optionen) eher Picker (s. nächste Zeile) |
| `apps/web/app/components/ui/selectors/ThemeSelector.tsx` | Dropdown/Select-Picker, postet `setTheme` an `/preferences` mit Analytics | **als-vorlage** — Picker-Pattern (Dropdown + fetcher.submit) direkt für System/Hell/Dunkel-Auswahl übernehmbar; Optionen-Quelle austauschen |
| `apps/web/app/components/layouts/sidebars/shadcn/nav-user.tsx:152-157` | Theme-Toggle bereits in User-Menü der App-Shell verdrahtet (`onThemeToggle`, gated über `DARK_MODE_IN_APP`) | **als-vorlage** — Einbau-Ort in Shell vorhanden; auf Picker/3-Wert anpassen |
| `apps/web/app/application/Constants.ts:10` | `DARK_MODE_IN_APP = true` — Schalter ob App-Bereich Dark-Mode bekommt | **1:1** als Feature-Gate-Vorbild (Spec D verlangt Feature-Flag-Fähigkeit) |
| `apps/web/app/application/enums/shared/Theme.ts` | `enum Theme { LIGHT, DARK }` | **anpassen** — um `SYSTEM` erweitern |
| `apps/web/app/locale/.../translations.json` (`components.themeToggle.modeLabel.light/dark`, `settings.theme.*`, `shared.theme`) | Vorhandene i18n-Keys de+en für Theme-Labels | **anpassen** — `system`-Label ergänzen; Klartext aus Spec B.1 einsetzen |
| `apps/mobile/package.json:25` (`@capacitor/status-bar` 7.0.1), `@capacitor/splash-screen` 7.0.1 | Capacitor Status-Bar- + Splash-Plugins als Dependency installiert | **als-vorlage** — Plugins vorhanden, aber **keine theme-aware Nutzung** (kein `StatusBar.setStyle`-Aufruf in `apps/mobile/src`) → Spec C.4 muss neu gebaut werden |
### Phase-2-relevante Vorlagen (Tenant-Branding / White-Label)
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/accounts.prisma:187-188` | `Tenant.theme String?` + `Tenant.themeConfig String?` (serialisierter JSON-String mit Farben inkl. `darkColors`, `sidebar*`) | **als-vorlage** für Phase-2-`TenantBranding` (Farb-Override pro Tenant) |
| `apps/web/app/utils/theme/ThemeConfig.ts` (`parseThemeConfig`, `ThemeConfig`) | Parst Tenant-`themeConfig` → CSS-Variablen (alle Farb-Slots inkl. dark, sidebar, radius, fontFamily) | **als-vorlage** für Phase-2-Live-Theming / `theme_variables` JSONB (E.5) |
| `apps/web/app/utils/theme/defaultThemes.ts` (`themeConfigurations`, `defaultThemes`, `defaultTheme="blue"`) | ~20 vordefinierte Farbschemata (light+dark) als CSS-Var-Sets | **als-vorlage** für Farb-Picker-Presets (E.1) |
| `apps/web/app/themes.css` (~86 KB) | `.theme-{name}` + `.dark.theme-{name}` Klassen | **als-vorlage** für Phase-2-CSS-Var-Theming |
| `apps/web/app/routes/app.$tenant/settings/theme.tsx` + `apps/web/app/components/core/tenants/forms/UpdateTenantFormTheme.tsx` | Tenant-Theme-Verwaltungs-Route (`update-theme`-Action, Permission-gated `app.settings.account.view/update`, Live-Preview via `themePreviewStore`) | **als-vorlage** für `/{tenant}/admin/branding/` (E.1) — Route-/Form-/Permission-Pattern direkt adaptierbar |
| `apps/web/app/stores/themePreviewStore.ts` (`useThemePreviewStore`) | Client-Store für Live-Preview-Override im Shell-Layout | **als-vorlage** für „Preview vor Live-Schalten" (E.6) |
| `apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx` | Liest Tenant-`themeConfig` + Dark-Mode → injiziert `--sidebar*` CSS-Variablen in Shell | **als-vorlage** für Anwendung von Tenant-Branding in Sidebar/Header (E.1) |
| `prisma/schema/core.prisma:6,23-27` (`AppConfiguration.theme`, `brandingLogo`, `brandingLogoDarkMode`, `brandingIcon`, `brandingIconDarkMode`, `brandingFavicon`) | **System-weite** (nicht tenant-bezogene) Branding-Felder | **als-vorlage** für Feld-Shape der Phase-2-`TenantBranding`-Tabelle (Logo + Dark-Logo + Icon + Favicon) |
| `apps/web/app/utils/db/appConfiguration.db.server.ts:90,196,251-292` | Load/Persist + Mapping `branding.logo/logoDarkMode/icon/iconDarkMode/favicon` | **als-vorlage** für DB-Service-Layer Phase 2 |
| `apps/web/app/root.tsx:127-135` | Favicon/Branding-Logo aus `appConfiguration.branding` ins `<head>` injiziert | **als-vorlage** für Tenant-Branding-Anwendung (E.1) |
| `packages/brand/src/index.ts` (`@toolctrl/brand`) | Brand-Tokens (productName, legal/support-Links, assets, **mail.colors**), `createBrandTokens`, `resolveTransactionalBrandTokens`, `brandCssVariables` | **als-vorlage** für E.2 (Email-Branding mit Logo+Primärfarbe) — Mail-Color-Token-Resolution + CSS-Var-Export bereits fertig |
| `prisma/schema/portals.prisma:14-15` (`themeColor`, `themeScheme`) + `apps/web/app/modules/portals/db/portals.db.server.ts:176-209` | Per-Portal `themeColor`/`themeScheme` (separates Customer-Portal-Theming) | **als-vorlage** für E.3 Custom-Login/Portal-Branding (eigenständiges Konzept, nicht 1:1) |
---
## Vorhandene Daten-Modelle
| Modell / Feld | Pfad | Deckung |
|---|---|---|
| `User.lightOrDarkMode String?` | `prisma/schema/accounts.prisma:17` | Phase 1 A.1 — **teilweise** (binär statt 3-Wert-Enum, nullable statt Default `system`) |
| `Tenant.theme String?` | `prisma/schema/accounts.prisma:187` | Phase 2 E.1 — Tenant-Farbschema-Auswahl |
| `Tenant.themeConfig String?` | `prisma/schema/accounts.prisma:188` | Phase 2 E.1/E.5 — serialisierte Tenant-Theme-Vars (Whitelabel-Vorlage) |
| `AppConfiguration.theme / brandingLogo / brandingLogoDarkMode / brandingIcon / brandingIconDarkMode / brandingFavicon` | `prisma/schema/core.prisma:6,23-27` | Phase 2 E.1 — **System-Level** Branding-Feld-Shape (Vorlage für TenantBranding) |
| `Portal.themeColor / themeScheme` | `prisma/schema/portals.prisma:14-15` | Phase 2 E.3 — Customer-Portal-Theming (separat) |
**Existiert NICHT (muss in Phase 2 neu angelegt werden):**
- Keine `TenantBranding`-Tabelle (kein `model TenantBranding/Branding/TenantTheme` in `prisma/schema/*.prisma`).
- Keine `logoFileId`/`primaryColor`/`accentColor`/`custom_domain`/`theme_variables`-Felder als eigene Tenant-Branding-Entität.
- Branding ist heute **system-weit** (`AppConfiguration`), NICHT tenant-scoped.
---
## Lücken / komplett neu zu bauen
### Phase 1 (M030)
1. **3-Wert-Theme-Preference statt binär** — `User.lightOrDarkMode` ist `light`/`dark`. Spec verlangt Enum `system | light | dark` mit Default `system`. → Feld erweitern/migrieren (Forward-Only-Migration), `Theme`-Enum + Normalisierungs-Helfer um `system` ergänzen.
2. **`system`-Auflösung über `prefers-color-scheme`** — existiert NICHT (`grep prefers-color-scheme` = 0 Treffer in apps/packages). Spec C.1 Schritt 3 + Live-Listener C.2 (`matchMedia('(prefers-color-scheme: dark)')`) komplett neu.
3. **Live-Reaktivität bei `system`** — kein Client-Listener für OS-Theme-Wechsel während offener Session (C.2) vorhanden.
4. **SSR-Cookie für No-Flash bei `system`** — heute kommt der Modus aus der **Server-Session** (nur eingeloggt). Für `system`/nicht-eingeloggt + No-Flash braucht es Cookie/Header-Lesung von `prefers-color-scheme` server-seitig (C.3). Neu.
5. **3-Optionen-Picker an `/{tenant}/settings/profile/`** — Picker-Komponente existiert als Vorlage (`ThemeSelector`/`DarkModeToggle`), aber für 3 Optionen mit Spec-Klartext (B.1) neu zusammenzubauen; Einbau in `settings/profile` (nicht nur User-Menü).
6. **Capacitor Status-Bar / Splash theme-aware** — Plugins (`@capacitor/status-bar`, `@capacitor/splash-screen`) sind installiert, aber **kein** `StatusBar.setStyle(...)`-Aufruf in `apps/mobile/src` (C.4). Native-Hook komplett neu.
7. **i18n-Key `system`** — `components.themeToggle.modeLabel` hat nur `light`/`dark`; `system` + Spec-Klartexte fehlen.
### Phase 2 (E.1-E.6) — alles als Vorlage vorhanden, aber neu zu bauen
- `TenantBranding`-Tabelle (Felder per `AppConfiguration`-Shape) — neu.
- `/{tenant}/admin/branding/`-Route — `settings/theme.tsx`-Pattern adaptieren.
- Logo-Upload (PNG/SVG) via Files-Modul (M23/Scaleway) — neu verdrahten.
- Permissions `branding.admin` (über `tenant.admin`) + `branding.white_label` (Enterprise-Gate via M27) — neu.
- White-Label: custom_domain (Caddy-Cert), custom fonts, `theme_variables` JSONB, hide-hivegrid-branding — neu (ThemeConfig-Parser als Vars-Vorlage).
- Email-Branding (E.2): `@toolctrl/brand` mail-tokens als Basis, tenant-scoped erweitern.
---
## Empfohlenes Vorgehen (Phase 1 zuerst)
1. **Daten-Layer:** `User.lightOrDarkMode` → 3-Wert-Preference erweitern. Forward-Only-Migration mit Inverse-SQL-Kommentar; Default `system`; bestehende `null`-Werte → `system`. (`accounts.prisma:17`)
2. **Auflösungs-Helfer neu:** `resolveEffectiveTheme(pref, prefersColorSchemeHeader/Cookie)` aufbauend auf `userThemePreference.server.ts`-Normalisierung. Reihenfolge nach Spec C.1.
3. **SSR-No-Flash erweitern:** `root.tsx:97-100` umbauen — `dark`-Klasse zusätzlich aus aufgelöstem `system`-Wert (Cookie/Header) setzen, nicht nur aus Session. Cookie-Name (offener Spec-Punkt) festlegen.
4. **Client-Reaktivität:** `matchMedia`-Listener für `system`-Modus (neu) — bei OS-Wechsel `dark`-Klasse live toggeln (C.2), Cookie aktualisieren.
5. **UI-Picker:** `ThemeSelector.tsx`/`DarkModeToggle.tsx` als Vorlage → 3-Optionen-Picker mit Spec-Klartext; posten an `/preferences` (vorhandene Action erweitern). Einbau in `settings/profile` + optional User-Menü (`nav-user.tsx`).
6. **Audit/Events:** vorhandenes `user.preferences.updated`-Event (`root.tsx:197`) für neuen 3-Wert weiterverwenden.
7. **i18n:** `system`-Label + Klartexte (de zuerst, AV #4 — alle Strings extern).
8. **Capacitor (C.4):** Native-Hook neu — `@capacitor/status-bar` `StatusBar.setStyle(Style.Dark/Light)` + Splash an aufgelösten Modus koppeln (`apps/mobile/src`). Soft-dependency auf M168.
9. **Feature-Flag:** Modul über Flag abschaltbar machen (DoD); `DARK_MODE_IN_APP`-Konstante als Vorbild.
10. **Phase 2** erst nach eigener Detail-Spec; dann `settings/theme.tsx` + `AppConfiguration`-Branding-Shape + `@toolctrl/brand` als Startpunkte.
---
## Notiz zu Layer-Disziplin (AGENTS.md / INTEGRATION-CONTRACTS)
- Die Boilerplate-Vorlagen liegen in `apps/web` (RR7-Routen, Loader+Action+Component gemischt). HiveGrid-DoD verlangt: Loader baut View-Model, UI-Component (`packages/ui-hivegrid/**`) nur VM+Actions, keine Prisma-/Server-Imports im UI-Paket, Subframe via Adapter. → Vorlagen als Referenz für Logik, **UI-Komponente neu** in `packages/ui-hivegrid` (Subframe-Design pflicht, Memory `feedback_subframe_mandatory`).
- Sidebar/Settings-Wiring: `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` ist Single-Source (INTEGRATION-CONTRACTS §1); Mandant-Settings unter `app.hivegrid.de/settings/<modul>/...` (§ Route-Tabelle). Phase 1 ist eine Profil-Settings-Sektion, kein eigener Sidebar-Top-Eintrag — explizit dokumentieren (DoD-Ausnahme).
@@ -0,0 +1,104 @@
# Boilerplate-Abgleich — Modul M32 (Feature-Flags / Admin-UI)
- **Modul-ID:** M32
- **Name:** Feature-Flags (Plattform-Admin-UI)
- **Milestones:** M031 (Schalter-Definition + Lifecycle), M032 (Filter-Editor + Einzel-Ausnahme), M033 (Massen-Funktionen + Statistik + Audit-Historie)
- **Block:** Block 1 · Modul 32 (Pflichtenheft `block1.md` §32.1-32.9)
- **LP:** LP-9 (Spec-Tiefe), LP-10 (Klartext-Diagnostik); ist selbst die Umsetzung von AV #7 (Feature-Flag-Hülle) und AV #6 (Audit-Default)
- **Reuse-Level:** **medium** — sehr starke, getestete Querschnitt-/Engine-Basis (Paket `@toolctrl/feature-flags`) vorhanden; das fachliche **Datenmodell der Spec** (Lifecycle, Tenant-Override, Filter mit Priority/Criteria/Value, Owner, Audit-Diff) und die **konkrete Admin-UI** müssen aber nennenswert ergänzt/neu gebaut werden.
> Verifiziert direkt in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (nicht nur Inventur). Hinweis: HiveGrid hat noch **kein** Prisma-Schema (`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/prisma` enthält nur `init-db.sql`), keine `packages/ui-hivegrid`, kein `app/routes`. Die Boilerplate-Artefakte sind daher als Vorlage/zu portieren zu betrachten, nicht 1:1-Import in ein bestehendes HiveGrid-Paket.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `packages/feature-flags/src/evaluate.ts` | `evaluateFlag(name, ctx, opts)` — DB-freie Eval-Engine via `FlagLoader`-Callback, mit Zeitfenster, Parent-Dependency (Zyklus-Schutz `maxDepth=8`), Variant-Bucketing. `EvaluateFlagResult.reason` (`flag-not-found`/`disabled`/…/`matched`) | **anpassen** — Fundament für `tenantHasFlag`. Spec-Auswertungsreihenfolge (Override → Filter nach `priority` → `default_value`) ist NICHT die Paket-Logik; muss als eigene Resolver-Schicht oben drauf oder als neuer Rule-/Loader-Aufbau ergänzt werden. |
| `packages/feature-flags/src/targeting/evaluator.ts` + `targeting/types.ts` | Reiner Regel-Evaluator + Rule-Union (`allowlist`/`percentage`/`plan-tier`/`role-based`/`time-based`/`composite`) | **als-vorlage** — Pattern für deterministische, I/O-freie, total-typsichere Regel-Auswertung. HiveGrid-Filter-Criteria (`tenant_size`, `tenant_industry`, `tenant_status`, `subscription_product_id`, `tenant_created_*`, `tenant_id_in/not_in`) sind andere Leaf-Typen → analog ergänzen. AND-Verknüpfung + Exhaustiveness-Check direkt übernehmbar. |
| `packages/feature-flags/src/targeting/percentage.ts` | `computeBucket`, `isInRolloutBucket` (sticky Hash-Bucketing) | **als-vorlage** — in Phase 1 nicht benötigt (Prozent-Rollout = Phase 2), aber für M032/Phase-2 vorhanden. |
| `packages/feature-flags/src/cache.ts` | `createFlagEvalCache`, `buildCacheKey`, `hashContext`, `FEATURE_FLAGS_INVALIDATION_CHANNEL` | **anpassen** — deckt das Spec-Caching (Block E: Request-scoped, kein wiederholtes DB-Roundtrip) ab. Cache-Key müsste um Resolver-Inputs (TenantOverride/Filter-Set) erweitert werden; Cross-Replica-Invalidierung bei Admin-Save bereits gelöst. |
| `packages/feature-flags/src/publisher.ts` | `publishFeatureFlagInvalidationOnce/ViaStore` (Cross-Process-Invalidierung via shared-store) | **1:1** — bei jeder Flag-/Filter-/Override-Mutation aus Admin-Action aufrufbar. |
| `packages/feature-flags/src/client/context.tsx` | `FeatureFlagProvider`, `useFeatureFlag`, `useFeatureFlagEnabled`, `useFeatureFlagVariant` (SSR-Hydration) | **1:1 / anpassen** — Phase 1 hat kein Tenant-User-UI für Flags, aber das Hydration-Pattern ist für flag-gegatete UI (AV #7) generell nutzbar (deckt INTEGRATION-CONTRACTS §2 `feature_flag?`-Gate ab). |
| `packages/foundation/src/flags.ts` | `defineFlag`, `featureFlag`, `selectFlagRecord` (leichtgewichtige Auflösung user > tenant > global, override) | **als-vorlage** — die `selectFlagRecord`-Präzedenz (User→Tenant→Global) ist konzeptuell nah an der Spec-Reihenfolge (Override→…→Default). Für ein einfaches `tenantHasFlag` ggf. direkt erweiterbar; berücksichtigt aber keine `priority`-sortierten Filter. |
| `packages/foundation/src/audit.ts` | `auditEvent(input, client)`, `withAuditMiddleware(handler, buildEvent, client)` | **1:1** — erfüllt Block G (Audit-Logging mit Vorher/Nachher). Wrappt jede mutierende Flag-/Filter-/Override-Action. Schreibt nach `AuditEvent` (`core.prisma`). |
| `packages/foundation/src/permissions.ts` | `requirePermission`, `withPermission`, `withTenantScope`, `withOwnerCheck` | **1:1** — für Block H (`admin.feature_flags.read/write/lifecycle`). Liefert bei Fehlschlag `CatalogError(notFound)` → 404 statt 403 (deckt DoD „Permission-Denied → 404" / INTEGRATION-CONTRACTS A.5.3). |
| `packages/foundation/src/errors.ts` | `CatalogError`, `foundationErrors`, `catalogRegistry`, `toPinoLogObject` | **1:1** — Klartext-Fehler mit `i18nKey` für Block I (Lookup-auf-unbekannten-Key, Vergangenheits-`expires_at` usw.). |
| `packages/view-models/src/index.ts` | `VMState`, `VMStatus`, `ActionCallbacks`, `RegistryGate`, `SidebarRegistryItem`, `ready/empty`, `assertI18nLabel` | **1:1** — Loader-baut-VM-Disziplin (DoD „Loader baut VM; UI nur VM+Actions"), Empty-/Loading-/Error-States, Sidebar-Registry-Gate. |
| `packages/i18n/src/*` | `useTranslate`-Factory, Intl-Formatter, ICU, Namespaces, `assertI18nKey` | **1:1** — alle UI-Texte als i18n-Keys (DoD/INTEGRATION-CONTRACTS §10). |
| `packages/url/src/canonical.ts` | `adminPath`/`adminUrl` (host-aware) | **1:1** — alle Routen liegen auf `admin.hivegrid.de` (Block B). |
| `prisma/schema/core.prisma` → `AuditEvent` (Z.55) | Append-only Audit-Event mit `actorType`, `action`, `targetType/Id`, `metadata`, `previousHash`/`eventHash` (Hash-Chain), `dataSensitivity`, `regulatoryScope[]` | **1:1** — Ziel-Tabelle für Block G. Diff (`oldValue`/`newValue`) als `metadata` ablegbar. |
| `prisma/schema/core.prisma` → `IdempotencyKey` (Z.84) | `@@unique([scope, key])` | **1:1** — für idempotente Bulk-Override-Actions (M033). |
| `apps/web/app/routes/admin/feature-flags/*` (`feature-flags.tsx`, `index.tsx`, `flags.tsx`, `flags/$id.tsx`, `flags/new.tsx`, `settings.tsx`, `engine.tsx`) | Bestehende Plattform-Admin-Routen-Struktur (Liste/Detail/New, Sidebar-Icon-Layout, Permission-Gate `admin.featureFlags.view/manage`) | **als-vorlage** — Routen-Aufteilung und Admin-Gating als Blaupause. UI deckt jedoch nur einfache An/Aus + analytics-orientierte Filter ab, **nicht** Lifecycle/Tenant-Override/Priority/Statistik/Audit-Historie. |
| `apps/web/app/modules/featureFlags/db/featureFlags.db.server.ts` | `getAllFeatureFlags`, `getFeatureFlag`, `create/update/deleteFeatureFlag`, Cache-Invalidierung | **als-vorlage** — DB-Server-Layer-Muster (`.db.server.ts`). Muss um Lifecycle/Owner/TargetModule/Archiv/Tenant-Override/Filter-Priority erweitert werden. |
| `apps/web/app/modules/featureFlags/components/FeatureFlagForm.tsx`, `FeatureFlagTracker.tsx` | Anlege-/Edit-Form + Analytics-Tracker-Component | **als-vorlage** — Form-Struktur wiederverwendbar; HiveGrid-Felder/UI (Lifecycle-Dropdown, Owner, Modul-Tag, Default-Toggle) ergänzen. |
| `apps/web/app/utils/services/.server/featureFlagEvaluator.server.ts`, `featureFlagCache.server.ts`, `featureFlagsRequest.server.ts` | Server-Bridge zwischen Prisma-`FeatureFlag` und Paket-`evaluateFlag` (OR-Lookup name/id, L2-Cache, Memo 60s) | **anpassen** — Vorlage für die HiveGrid-`tenantHasFlag`-Server-Bridge; Resolution-Order/Loader an Spec-Modell anpassen. |
| `apps/web/app/components/layouts/icons/IconFeatureFlags.tsx` | Sidebar-Icon | **1:1** — Icon übernehmbar. |
| `apps/web/app/application/sidebar/AdminSidebar.tsx` (Z.206-215) | Admin-Sidebar-Registrierung der Feature-Flags-Gruppe inkl. Sub-Items + Permission-Gate | **als-vorlage** — Muster für die HiveGrid-Sidebar (`packages/ui-hivegrid/src/app-shell/sidebar.config.ts`, INTEGRATION-CONTRACTS §2). |
| `packages/shared-store/*` | `createTwoTierCache`, Pub/Sub | **1:1** — Infrastruktur, die `cache.ts`/`publisher.ts` benötigen. |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
- **`FeatureFlag`** — `featureFlags.prisma:1`
Felder: `id`, `createdAt`, `updatedAt`, `key String?`, `scope` (default `global`), `tenantId?`, `userId?`, `name`, `description`, `enabled`, sowie v2-Targeting-Felder `rules Json?`, `variants Json[]`, `enabledFrom?`, `enabledUntil?`, `parentFlagId?` (Self-Relation `FeatureFlagDependency`). Relationen: `audits`, `events` (Analytics), `filters`.
Indizes: `@@unique([name, description])`, `[key, scope]`, `[tenantId, key]`, `[userId, key]`, `[parentFlagId]`.
- **`FeatureFlagFilter`** — `featureFlags.prisma:32`
Felder: `id`, `createdAt`, `featureFlagId`, `type String`, `value String?`, `action String?` (onDelete: Cascade).
- **`FeatureFlagAudit`** — `featureFlags.prisma:44`
Append-only: `id`, `flagId`, `actorUserId?`, `action` (create/update/delete/toggle), `oldValue Json?`, `newValue Json?`, `createdAt`. Indizes `[flagId, createdAt]`, `[actorUserId, createdAt]`.
- **`AuditEvent`** — `core.prisma:55` (Querschnitt-Audit, Hash-Chain, tenant-aware).
- **`IdempotencyKey`** — `core.prisma:84`.
- **`Tenant`** — `accounts.prisma` (für Filter-Criteria relevant: `slug`, `name`, `active`, `createdAt`, `subscription`/`productConfiguration`/`featureOverrides`). **Achtung:** Es gibt **kein** `tenant_size`-, `tenant_industry`- oder `tenant_status`(trial/active/past_due/frozen/suspended)-Feld am Boilerplate-`Tenant` — nur `active Boolean` + `deactivatedReason`. Die Spec-Filter-Criteria brauchen also entweder zusätzliche Tenant-Felder (HiveGrid-Tenant-Modell, Modul 37) oder eine Ableitung (z.B. MA-Zahl aus HR-Hub).
---
## Lücken / komplett neu zu bauen
### Datenmodell (größte Lücke)
Das Boilerplate-Schema folgt einem anderen Konzept (An/Aus + Targeting-Rules-Tree pro Flag, Filter = analytics-/session-/percentage-Match). Die Spec verlangt ein **dreiteiliges Modell mit Tenant-Override und priorisierten Filtern**. Konkret fehlt / weicht ab:
- **`FeatureFlag`** — fehlende Spec-Felder: `label`, `default_value` (es gibt nur `enabled`), `lifecycle_stage` Enum (`beta|rollout|ga|deprecated`), `owner_admin_user_id`, `created_by_admin_user_id`, `target_module`, `archived_at` (Soft-Delete). `key` ist `String?` und nur via `[name, description]` unique — Spec verlangt `key` **global unique + non-null + nach Anlage nicht editierbar**.
- **`FeatureFlagFilter`** — fehlende Spec-Felder komplett: `name`, `priority Int`, `value Boolean`, `criteria JSONB` (strukturiertes Schema), `active Boolean`, `created_by_admin_user_id`. Boilerplate-Filter (`type`+`value String`+`action`) ist semantisch ein anderes Konstrukt.
- **`TenantFeatureFlag` (Tenant-Override)** — **existiert nicht**. Komplett neu: `feature_flag_id`, `tenant_id`, `value Boolean`, `set_by_admin_user_id`, `note?`, `expires_at?`, `@@unique([feature_flag_id, tenant_id])`, Indizes `[tenant_id, feature_flag_id]` + `expires_at`.
### Logik
- **Auswertungs-Reihenfolge der Spec** (Override → aktive Filter nach `priority` desc, bei Gleichstand ältester → `default_value`) — neu zu implementieren. Die Paket-Engine (`evaluate.ts`) macht Zeitfenster + Parent-Dependency + Rule-Tree, **nicht** die priorisierte Override/Filter/Default-Kaskade.
- **`tenantHasFlag(tenantId, key)`** (Block E) — neue Convenience-API mit: wirft bei unbekanntem `key` in Dev/Staging (Schema-Drift-Schutz), loggt im Prod; Boolean-Only; Request-scoped-Cache. Vorlage: `featureFlagEvaluator.server.ts`, aber andere Resolution.
- **Filter-Criteria-Matcher** für `tenant_size/industry/status/subscription_product_id/created_*/id_in/id_not_in` — neue Leaf-Evaluatoren (Pattern aus `targeting/evaluator.ts`).
- **Live-Vorschau „X Tenants matchen"** (Block D, §32.5.4) — neue Query gegen Tenant-Tabelle (Spec: Read-Replica). Komplett neu.
- **Effektive-Auswertungs-Statistik** „X aktiv / Y nicht" (Block C, §32.5.3, M033) — neue Aggregation über alle Tenants. Komplett neu.
- **Bulk-Override** „12 Tenants gleichzeitig" (Block C, §32.5.6, M033) — neue idempotente Action (Vorlage `IdempotencyKey`/`withIdempotency`). Komplett neu.
- **Lifecycle-Wechsel-Workflow** mit Bestätigungs-Dialog + Edge-Case-Warnungen (Block F, §32.5.7) + **Archivierung/Reaktivierung** (§32.5.8). Komplett neu (kein Lifecycle-Konzept in BP).
- **Expires-At-Cron** (Tenant-Override-Auto-Reset) — neuer Worker-Job. Komplett neu.
- **Audit-Diff-History pro Flag im Detail-View** (Block G/§32.7) — `FeatureFlagAudit` existiert als Tabelle, aber UI + Befüllung über alle Spec-Aktionen (Filter-, Override-, Lifecycle-, Archiv-Änderungen mit Diff) neu zu verdrahten; alternativ `AuditEvent` (Querschnitt M21) nutzen.
### UI (HiveGrid-spezifisch, komplett neu in `packages/ui-hivegrid` + `app/routes`)
- Listen-View mit Spalten/Filter/Suche/Sortierung/„Archivierte anzeigen"/Quick-Actions (Lifecycle, Archiv) — BP-`flags.tsx` deckt nur Teil ab.
- Detail-View mit Sektionen Stammdaten/Filter/Tenant-Overrides/Statistik/Audit, Inline-Edit, Filter-Editor mit Criteria-Builder + Live-Vorschau, Tenant-Override-Editor mit Tenant-Autocomplete + Expires-At, Bulk-Override-UI, Lifecycle-Confirm-Dialog.
- Alle als View-Model (Loader) + reine UI-Component (kein Prisma-Import in `packages/ui-hivegrid/**`), Subframe-Output via Adapter (DoD).
- Sidebar-Eintrag in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` + Breadcrumbs + Smoke-Test (`e2e/smoke/`) — Infrastruktur existiert in HiveGrid noch nicht.
### Permissions
- BP nutzt `admin.featureFlags.view` / `admin.featureFlags.manage`. Spec verlangt 3 atomare Permissions (`admin.feature_flags.read/write/lifecycle`) + 4 Bundles (`none/viewer/operator/owner`). Mapping/Definition neu (final mit Modul 37 abzustimmen — offener Spec-Punkt).
### Plattform-Admin-Fundament (Vorbedingung, außerhalb M32)
- `admin.hivegrid.de`-Subdomain-App-Shell, Plattform-Admin-Auth (M034), Admin-User-Modell, `AdminAuditLog`/Cross-Tenant-Audit (M037). In Boilerplate liegt Admin als Bereich **innerhalb** `apps/web` — HiveGrid plant separate Admin-App-Surface (INTEGRATION-CONTRACTS §1: „separate Sidebar-Struktur M034-M041"). Diese Vorbedingungen sind nicht Teil von M32 selbst, aber blockierend.
---
## Empfohlenes Vorgehen (Reihenfolge)
1. **Querschnitt 1:1 übernehmen (kein Neubau):** `@toolctrl/foundation` (audit, permissions, errors), `@toolctrl/view-models`, `@toolctrl/i18n`, `@toolctrl/url`, `@toolctrl/shared-store`, `AuditEvent`/`IdempotencyKey` (core.prisma). Das ist das stabile Fundament für DoD-Wiring.
2. **Engine-Paket als Basis ziehen, Resolver anpassen:** `@toolctrl/feature-flags` (cache, publisher, client, percentage, targeting-Pattern) übernehmen; darüber einen **HiveGrid-Resolver** bauen, der die Spec-Reihenfolge (Override → priorisierte Filter → default) implementiert. `tenantHasFlag` als neue Convenience-API mit Schema-Drift-Schutz + Request-Cache (Vorlage: `featureFlagEvaluator.server.ts`).
3. **Datenmodell neu/erweitert (M031-Fundament):** HiveGrid-Prisma-Schema anlegen. `FeatureFlag` um Spec-Felder erweitern (label, default_value, lifecycle_stage, owner/created_by, target_module, archived_at, key unique non-null), `FeatureFlagFilter` um (name, priority, value Boolean, criteria JSONB, active, created_by), **`TenantFeatureFlag` neu**. Forward-Only-Migration mit Inverse-SQL-Kommentar. Entscheiden: bestehende BP-`FeatureFlagAudit` nutzen oder Querschnitt-`AuditEvent` (Empfehlung: `AuditEvent` für plattformweite Durchsuchbarkeit, §32.7.2).
4. **M031 — Schalter-Definition + Lifecycle:** DB-Server-Layer (`.db.server.ts`, Vorlage BP), Permissions (3 atomar + 4 Bundles), Routen Liste/Detail/New/Edit auf `admin.hivegrid.de` (Vorlage BP-Routen-Struktur), Sidebar-Registry, Lifecycle-Wechsel mit Confirm + Audit. Form-Component aus BP `FeatureFlagForm.tsx` als Vorlage.
5. **M032 — Filter-Editor + Einzel-Ausnahme:** Criteria-Builder-UI + neue Leaf-Matcher (Pattern `targeting/evaluator.ts`), Live-Vorschau-Query gegen Tenant-Tabelle, Tenant-Override-Editor mit Autocomplete + Expires-At, priorisierte Auswertung + Edge-Case-Klartext (Block D). **Vorab klären:** welche Tenant-Felder (`tenant_size/industry/status`) das HiveGrid-Tenant-Modell (M37) bereitstellt — BP-`Tenant` hat sie nicht.
6. **M033 — Massen + Statistik + Audit:** Bulk-Override (idempotent via `withIdempotency`), Wirkungs-Statistik-Aggregation, Audit-History-Sektion im Detail-View, Archiv-/Reaktivierungs-Flow, Expires-At-Cron-Worker, Klartext-Hinweise (§32.9 / Block I).
7. **Querschnitt-Wiring + DoD:** `publishFeatureFlagInvalidationOnce` bei jeder Mutation, i18n-Keys durchgängig, Smoke-Tests pro Route, VM-Unit-Tests mit Zod, Visual-Regression. Permission-Denied → 404.
**Kurzfazit:** Das Querschnitt- und Engine-Gerüst (Paket + foundation) ist exzellent und großteils 1:1/als-Vorlage nutzbar — daher nicht „low". Aber das **fachliche Kernmodell der Spec (Lifecycle + Tenant-Override + priorisierte Criteria-Filter + Owner/Audit-Diff + Statistik/Bulk)** und die **komplette Admin-UI** sind in der Boilerplate nicht vorhanden bzw. konzeptuell abweichend → **medium**.
@@ -0,0 +1,120 @@
# Boilerplate-Abgleich: M33a — Apps-Engine / Adapter-Layer
| Feld | Wert |
|---|---|
| **Modul-ID** | M33a (Detail-Spec `_bmad-output/specs/M33a-apps-engine.md`) |
| **Name** | Apps-Engine / Adapter-Layer |
| **Milestones** | M008 (Adapter-Interface + State-Machine), M009 (Setup-Wizard + Sync-Log), M010 (Probe-Scheduler + Webhook-Sturm-Schutz) |
| **Block** | Block 4 — USP-Säulen (`_bmad-output/pflichtenheft/blocks/block4.md` Modul 33a) |
| **LPs** | LP-9 (Apps-Engine-Foundation), LP-10 (Klartext-Diagnostik), LP-11 (Adapter-Pattern für alle Integrationen) |
| **Reuse-Level** | **medium** |
## Reuse-Verdict (kurz)
Das **Daten-Modell ist fast 1:1 vorhanden** (`prisma/schema/appsEngine.prisma`: `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`) — exakt die fünf Entitäten aus Spec Block B. **Aber:** Diese Modelle sind in der Boilerplate **schema-only** — es gibt **keine** Domänen-Logik, **kein** Adapter-Interface, **keine** State-Machine, **keinen** Setup-Wizard, **keine** Settings-UI, **keinen** Probe-Scheduler und **keinen** Webhook-Receiver dafür. Verifiziert per Grep: in `apps/web/app`, `apps/worker/src`, `apps/api/src` und allen `packages/*` (außer dem generierten Prisma-Client) existiert **kein** Code, der `DataConnection`/`AppSyncRun`/`sample-data-sync` verwendet.
Das eigentliche Engineering (M008-M010) muss neu gebaut werden — aber auf einem **sehr starken Querschnitt-Fundament**: AES-256-GCM-Credential-Encryption (`CryptoApi`), BullMQ-Queue mit Idempotenz + plan-basierten Prioritäten, Webhook-Signatur-Validierung (Stripe/MailerSend als HMAC-Vorlage), ein periodischer Worker-Scheduler (`metrics-scheduler`), eine fertige Connection-Management-Admin-Route als Vorlage (`marketing-integrations.tsx` inkl. Encryption-at-rest + Secret-Masking) und das Adapter-Registry-Pattern aus `@toolctrl/marketing-outbound`. Der WASM-`plugin-runtime` deckt die **Phase-2-Marketplace**-Foundation ab (M33b/M33c), ist für Phase 1 aber nicht der Kern.
> Wichtige Begriffs-Abgrenzung (auch in der Inventur `docs/boilerplate-inventory/integrations-ki.md` §4 betont): Es gibt in der Boilerplate **zwei** „Apps-Engine"-Bedeutungen. (1) Die **Data-Sync-Engine** (`appsEngine.prisma`, `App`/`DataConnection`/`AppSyncRun`) = das, was M33a Phase 1 will. (2) Das **WASM-Plugin-System** (`plugin-runtime`/`plugin-sdk`/`plugins.prisma`) = M33a Phase 2 (Drittanbieter-Marketplace). Nicht verwechseln.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/appsEngine.prisma` | `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` — die fünf Spec-B-Entitäten | **anpassen** — Felder/Enums an Spec angleichen (siehe „Lücken" unten) |
| `apps/web/app/utils/api/.server/CryptoApi.ts` | AES-256-GCM Verschlüsselung (`encrypt`/`decrypt`, versioniert `v1:iv:tag:ct`, `CRYPTO_SECRET`) | **1:1** für `DataConnection.credentials` „verschlüsselt at-rest" (Spec B, 33a.9.3 „Plattform-Schlüssel") |
| `apps/web/app/routes/admin/marketing-integrations.tsx` | Komplette Connection-Management-Admin-Route: Liste, Create/Toggle/Delete, Permission-Gate (`verifyUserHasPermission`), Secret-Masking, `lastDeliveredAt`/`lastError`-Anzeige, i18n | **als-vorlage** für die Settings-UI `/settings/integrationen/` (Spec F) |
| `apps/web/app/utils/leads/marketingIntegrations.db.server.ts` | Encryption-at-rest DB-Layer: `SENSITIVE_KEYS`, `encryptSensitive`/`decryptSensitive`, `maskConfig` über `CryptoApi`, Round-Trip | **als-vorlage** für `DataConnection`-Persistenz mit verschlüsselten Credentials |
| `packages/marketing-outbound/src/index.ts` + `src/types.ts` | Adapter-Interface + Registry-Pattern (`adapterRegistry`, `resolveAdapter(type)`, `MarketingOutboundAdapter<TConfig>` mit `parseConfig`/`send`), `adapterFetch()` (Timeout + SSRF-Allowlist, nur HTTPS, kein RFC1918) | **als-vorlage** für das Adapter-Interface der Apps-Engine (Spec A: `connect`/`syncPull`/`syncPush`/`handleWebhook`/`validateConnection`) + sicheres Outbound-Fetch |
| `packages/queue/*` (`names.ts`, `payloads.ts`, `producers.ts`, `priority.ts`, `runtime.ts`) | BullMQ-Wrapper: typisierte Jobs, **`buildIdempotentJobId()`** (Idempotenz 33a.4.4), `resolveJobPriorityForTenant()` (plan-basiert), `createQueue`/`createWorker` | **1:1** für Sync-Mechanik (Pull/Push/Webhook/Manual), Idempotenz-Keys, Sync-Lock |
| `apps/worker/src/metrics-scheduler.ts` | Periodischer Poller-Pattern (30s/60s-Kadenzen, best-effort, started aus Worker-Entrypoint) | **als-vorlage** für den **Probe-Scheduler** (M010: aktiv 5min / eingeschränkt 1min / defekt 15min) |
| `apps/api/src/webhooks/mailersend-signature.ts` | HMAC-Signatur-Validierung mit `timingSafeEqual`, Timestamp-Toleranz, typisierte Failure-Reasons | **als-vorlage** für Webhook-Signatur-Validierung pro App (Spec E.3, offener Punkt der Spec) |
| `apps/api/src/billing/stripe-webhook-route.ts` | Inbound-Webhook-Route mit Signatur-Konstruktion, Outbox-Publish in DB-Transaktion, Metrics, Error-Envelope | **als-vorlage** für den Webhook-Receiver `app.hivegrid.de/api/v1/webhooks/{app_key}/{tenant_id}/{connection_id}` (Spec E.3) |
| `apps/api/src/webhookDeliveryQueue.ts` + `WebhookDeliveryJob` (`@toolctrl/queue`) | Outbound-Webhook-Delivery über Queue (`buildWebhookDeliveryJob`, signierte/retried Zustellung) | **anpassen** für Push-Sync / signierte Outbound-Webhooks (Spec E.2) |
| `packages/storage/src/index.ts` (`StorageAdapter`, `createS3StorageAdapter`) + `signed/` | Scaleway-S3-Adapter + Signed-URLs | **als-vorlage** für den `kwpsync.exe`-Download im Setup-Wizard (Spec D, connection_type `windows_client`) |
| `apps/web/app/utils/integrations/githubService.ts` | Beispiel eines konkreten externen-Service-Adapters (OAuth/Token-Handling-Muster) | **als-vorlage** für die App-spezifischen Adapter (eigene Module: KWP/Gmail/Stripe) |
| `packages/plugin-runtime/*` + `packages/plugin-sdk/*` + `prisma/schema/plugins.prisma` | WASM-Sandbox, Capability-Gateway (deny-by-default), Manifest+Ed25519-Signatur, Hook-Registry, Audit-Chain, Crash-Tracker; `Plugin`/`TenantPluginCapabilityGrant`/`PluginInvocation` | **als-vorlage** ausschließlich für **Phase 2** (M33b Community-Marketplace mit Sandboxing/Review, Spec Block I) — **nicht** Phase-1-Kern |
| `packages/plugins/src/manifest-schema.ts` (`FeatureManifest`, `validateFeatureManifestShape`) | Feature-/App-Manifest-Schema (Surfaces/Workers/Provider/Permissions/Audit) | **als-vorlage** für das Manifest-Format der Adapter-Registry (Spec C `manifest.ts`) |
### Querschnitt, das M33a wie jedes Modul mitnimmt (separate Foundation-Module M001-M011)
- **Audit:** automatisch via M001-Prisma-Middleware (AGENTS.md §C.13); externe Webhook-Aufrufe manuell via `auditEvent` (INTEGRATION-CONTRACTS §6). Deckt AV #6 (Audit für Connection-Änderungen).
- **Notifications:** via `notify()` (M011, INTEGRATION-CONTRACTS §7) — für `degraded`/`broken`-Alerts (Spec G, 33a.3.5). Realtime/In-App über `@toolctrl/realtime` (SSE).
- **Mail:** `@toolctrl/mail` (MailerSend, EU) für Email-Benachrichtigungen.
- **i18n:** M003-Build-Lint; pro-App `i18n/de.json` Klartext-Übersetzungen (Spec C/G).
- **Feature-Flags:** M006 — pro App `phase`/`requires_subscription_feature` + Feature-Flag (Spec C Tenant-Sicht).
- **Permissions:** M004 `withTenantScope()` + `withPermission()`; `verifyUserHasPermission` als bestehendes Boilerplate-Muster.
---
## Vorhandene Daten-Modelle
**Quelle:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/appsEngine.prisma` (generierter Client: `packages/db/generated/prisma/client/models/{App,DataConnection,AppSyncRun,AppSyncRunLog,AppSyncItem}.ts`).
| Boilerplate-Modell | Deckt Spec-Entität | Vorhandene Felder (Auszug) | Bewertung |
|---|---|---|---|
| `App` | App (Spec B) | `id`, `tenantId`, `type`, `config` (JSON), `icon`, `isActive`, `installedByUserId`, `syncRuns[]`, `@@unique([tenantId, type])` | Teilweise. **In BP tenant-scoped** (`tenantId`), Spec will App **plattform-weit** (Code-Registry-Spiegel). Es fehlen `key`/`name`/`description`/`category`/`connection_type`/`connection_schema`/`capabilities[]`/`phase`/`requires_subscription_feature`/`documentation_url`. |
| `DataConnection` | DataConnection (Spec B) | `id`, `tenantId`, `name`, `type`, `config` (Kommentar „Encrypted JSON credentials"), `description` | Solide Basis. **Keine FK zu `App`** in BP (Spec will `app_id`), kein `connection_status`-Enum, keine `last_health_check_*`/`last_sync_at`/`next_sync_at`/`last_error`/`metadata`/`created_by_user_id`. Multi-Connection-pro-App-pro-Tenant ist mit `name` schon angelegt. |
| `AppSyncRun` | AppSyncRun (Spec B) | `id`, `appId`(FK), `tenantId`, `taskKey`/`taskName`, `status` (pending/running/completed/partial/failed/cancelled/reverted), `executionMode` (manual/scheduled/webhook), `startedAt`/`completedAt`, `duration`, `itemsProcessed/Created/Updated/Failed`, `error`, `createdByUserId`, `logs[]`, `syncItems[]` | **Sehr gute Übereinstimmung.** FK zeigt auf `App`, Spec will FK auf `DataConnection` (`data_connection_id`). `kind` (pull/push/webhook/health_check/manual_resync) vs. BP `executionMode` (manual/scheduled/webhook) — angleichen. `summary_text` (Klartext) fehlt; `itemsSucceeded` als `itemsProcessed - itemsFailed` ableitbar. |
| `AppSyncRunLog` | AppSyncRunLog (Spec B) | `id`, `syncRunId`(FK), `type` (info/success/warning/error), `message`, `metadata` | Gute Basis. `severity` der Spec (`debug/info/warn/error/critical`) ⊃ BP-`type`; `timestamp` fehlt (nur `createdAt`); `tech_details` = `metadata`. |
| `AppSyncItem` | AppSyncItem (Spec B) | `id`, `syncRunId`(FK), `objectType`, `sourceId`, `destinationId`, `status` (synced/failed/skipped/pending/reverted), `action`, `sourceData`/`destinationData` (JSON), `error`, **`rolledBackData`/`rolledBackAt`** | **Sehr gute Übereinstimmung, sogar mehr** (Rollback-Felder, die die Spec nicht explizit fordert). Spec `operation` (create/update/delete/upsert/noop) vs. BP `action` (created/updated/deleted/skipped) — angleichen. `entityType`/`entityId` (HiveGrid-Entität) = BP `objectType`/`destinationId`. |
**Phase-2-Modelle (Marketplace) — vorhanden in `prisma/schema/plugins.prisma`:** `Plugin`, `TenantPluginCapabilityGrant`, `PluginUserConfig`, `PluginInvocation`, `PluginCapabilityUse` (mit per-Tenant Hash-Chain). Deckt die Spec-B-Phase-2-Entitäten (`CommunityApp`, `CommunityAppInstall`) konzeptionell ab, aber mit anderem Namensschema. **Nicht** für Phase 1 verwenden.
**Nicht vorhanden:** kein `App`-Registry-Drift-Tracking-Modell, keine Webhook-Rate-Limit-/Anomalie-State-Tabelle, kein Schema-Drift-Sentinel-State.
---
## Lücken / komplett neu zu bauen
### M008 — Adapter-Interface + State-Machine (neu)
1. **Adapter-Interface** (`app/integrations/{app-key}/index.ts`-Konvention, Spec A/C): `connect`/`disconnect`/`refreshTokens`/`validateConnection`/`syncPull`/`syncPush`/`handleWebhook` + `capabilities[]`/`triggers[]`/`actions[]` + `connection_schema`. Vorlage: `marketing-outbound`-Adapter-Registry, aber das konkrete Interface existiert nicht.
2. **5-Status-State-Machine** `pending → active → degraded → broken → revoked` (Spec G, 33a.3.1) mit Audit-Eintrag pro Übergang + Klartext-Hinweis pro Status. Existiert **nicht** (BP `DataConnection` hat keinen Status-Enum). `connection_status`-Feld + Enum neu.
3. **Adapter-Registry / Build-Time-Scan** von `app/integrations/` + DB-Sync der Manifests + Drift-Check (Spec C). Existiert **nicht** (Manifest-Schema-Vorlage in `@toolctrl/plugins`).
4. **Dummy-App** als Referenz-Implementierung (M008-Erfolgskriterium). Neu.
### M009 — Setup-Wizard + Sync-Log (neu)
5. **Generischer Setup-Wizard** pro Connection-Type (OAuth2 / API-Key / Username-Password / Windows-Client), Form-Generator aus `connection_schema` (Spec D, 33a.2). UI komplett neu (Vorlage: `marketing-integrations.tsx` für die Listen-/CRUD-Hülle).
6. **OAuth2-Redirect-Flow + Token-Refresh-Worker** (Spec D). Kein generischer OAuth-Client in BP (`authProviders.server.ts` ist Auth-Login, nicht App-Connection-OAuth; `@ai-sdk/openai`/`remix-auth-google` per EU-Constraint verboten). Neu.
7. **Sync-Log-UI** mit Filter (Status/Operation/Datum) + Detail-Schublade + Klartext-`summary_text` (Spec F, 33a.4). Neu.
8. **Disconnect-Flow** mit Multi-Step-Confirm + Cleanup (Webhook-Subscriptions kündigen, Tokens revoken) + `status=revoked` statt Hard-Delete (Spec D, 33a.7.4). Neu.
### M010 — Probe-Scheduler + Webhook-Sturm-Schutz (neu)
9. **Probe-Scheduler** mit status-adaptiver Frequenz (active 5min / degraded 1min / broken 15min, Spec G/33a.3.4). Vorlage: `metrics-scheduler.ts` (Poller-Pattern) + `@toolctrl/queue` Repeatable-Jobs — die konkrete Logik neu.
10. **Webhook-Sturm-Schutz** (Hard-Limit Events/Stunde pro Mandant, Default 1000) + Verwerfen-mit-Notification (Spec E, 33a.5.1, AV A.16.1). Rate-Limiter-Vorlage existiert in `@toolctrl/ai/guards` (`createFixedWindowAIRateLimiter`), aber nicht für Webhooks. Neu.
11. **Anomalie-Erkennung** (10x normales Volumen → Pause + Klartext, Spec E, 33a.5.2, AV A.16.2): Rolling-Window-Average + Threshold. Neu.
12. **Schema-Drift-Sentinel** (`validateSchema()`, Spec E/33a.6): Pause + Plattform-Admin-Alert (KWP-spezifisch in M092). Neu.
13. **Webhook-Receiver-Route** `api/v1/webhooks/{app_key}/{tenant_id}/{connection_id}` + per-App-Signatur-Validierung (Spec E.3). Routen-/HMAC-Vorlage in `stripe-webhook-route.ts` + `mailersend-signature.ts`, der generische Multi-App-Receiver neu.
### Querschnitt / Wiring (neu pro Modul, aber Foundation vorhanden)
14. **Sidebar-Eintrag** `Einstellungen → Integrationen (Apps)` (INTEGRATION-CONTRACTS §1, Route `app.hivegrid.de/settings/integrationen/`). Neu in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (Datei selbst existiert in HiveGrid noch nicht — Repo ist Greenfield).
15. **6 Permissions** `integrations.read/connect/disconnect/manual_sync/view_logs/admin` (Spec H) — in `packages/entitlements/src/permissions.ts` + Default-Rollen-Mapping (GF/Vertriebsleiter/Büro). Permission-Pattern existiert (`permissions-seed.server.ts`), die Keys neu.
16. **View-Model-Layer** (`packages/view-models/**`) + UI-Adapter (`packages/ui-hivegrid/src/adapters/`) — gemäß AGENTS.md Code-Layer-Trennung. Diese Pakete existieren in der Boilerplate **noch nicht** (sind HiveGrid-Eigenbau laut AGENTS.md „Du erweiterst, was fehlt").
17. **Klartext-Fehler-Catalog-Einträge** (M002) pro Fehler-Code + Lösungs-Hinweis (Spec G/33a.10). Neu.
### Repo-Realität (wichtig)
18. **Das `HiveGrid-Cloud`-Repo enthält aktuell NUR Planungs-Artefakte** (`_bmad`, `_bmad-output`, `docs`, `prisma`, `AGENTS.md`) — **kein** `apps/`, `packages/`, kein `package.json`. Verifiziert per `ls`. Die Boilerplate muss erst als Codebase ins Repo gezogen werden (AGENTS.md: „Die Boilerplate IST deine Codebase"). Bis dahin gibt es nichts zu erweitern — der Pre-Flight-Check aus AGENTS.md (`package.json`/`apps/`/`packages/` vorhanden) schlägt fehl.
---
## Empfohlenes Vorgehen
**Reihenfolge (zuerst BP übernehmen, dann neu bauen):**
1. **Voraussetzung:** Boilerplate als Codebase ins HiveGrid-Repo bringen + EU-Sterilisations-Check (AGENTS.md Pre-Flight). Vorher kann M008 nicht starten.
2. **Daten-Layer (BP anpassen):** `prisma/schema/appsEngine.prisma` als Basis nehmen und an Spec B angleichen:
- `App`: plattform-weit machen (oder zweigeteiltes Modell App-Definition vs. installierte App klären), Felder `key/name/description/category/connection_type/connection_schema/capabilities/phase/requires_subscription_feature/documentation_url` ergänzen.
- `DataConnection`: FK `app_id`, `connection_status`-Enum (5 Status), `last_health_check_*`/`last_sync_at`/`next_sync_at`/`last_error`/`metadata`/`created_by_user_id`. Credentials über `CryptoApi` (1:1) verschlüsseln — Vorlage `marketingIntegrations.db.server.ts`.
- `AppSyncRun`/`AppSyncRunLog`/`AppSyncItem`: FK-Ziel auf `DataConnection`, `kind`/`severity`/`operation`/`summary_text` angleichen. Forward-Only-Migration mit Inverse-SQL-Kommentar (AGENTS.md §F.28).
3. **M008 (Adapter-Interface + State-Machine):** Adapter-Interface nach Vorbild `@toolctrl/marketing-outbound` (Registry + `parseConfig`/`send` → erweitern zu `connect`/`sync*`/`handleWebhook`/`validateConnection`). Outbound-Calls über `adapterFetch()` (SSRF-/Timeout-Guard). State-Machine als Enum-Transitions mit Audit pro Wechsel (M001-Middleware deckt DB-Audit, externe Calls via `auditEvent`). Dummy-App als Referenz. Manifest-Schema nach Vorbild `@toolctrl/plugins`.
4. **M009 (Setup-Wizard + Sync-Log):** Settings-Route nach Vorbild `marketing-integrations.tsx` (Liste/CRUD/Permission-Gate/Secret-Masking/i18n) → erweitern zum Wizard + Sync-Log-UI. View-Model-Layer + UI-Adapter neu (AGENTS.md Code-Layer-Disziplin). Jobs über `@toolctrl/queue` mit `buildIdempotentJobId` (Idempotenz 33a.4.4) + `resolveJobPriorityForTenant`.
5. **M010 (Probe-Scheduler + Schutz):** Probe-Scheduler nach Vorbild `metrics-scheduler.ts` + Queue-Repeatable-Jobs, status-adaptive Frequenz. Webhook-Receiver-Route nach Vorbild `stripe-webhook-route.ts`, Signatur nach `mailersend-signature.ts`. Rate-Limiter + Anomalie-Detector + Schema-Drift-Sentinel neu. Notifications strikt über `notify()` (M011).
6. **Phase 2 (separat, M33b/M33c):** Erst nach Geerkens-Launch. WASM-`plugin-runtime`/`plugin-sdk`/`plugins.prisma` als Foundation für den Drittanbieter-Marketplace (Sandboxing/Capability-Consent/Signatur/Audit-Chain). Achtung: in der BP sind in Prod nur `log`/`audit`-Capabilities freigeschaltet (`PLUGIN_AVAILABLE_HOST_CAPABILITY_NAMES`).
**Querschnitt nicht vergessen (DoD-Block):** Sidebar-Eintrag (Einstellungen-Gruppe), 6 Permissions, i18n-Keys, Feature-Flag, Klartext-Catalog, Smoke-Tests + Hot-Swap-Drill + Visual-Snapshot, Permission-Denied → 404.
@@ -0,0 +1,119 @@
# Boilerplate-Abgleich: M34 — Public-API & Webhooks
| Feld | Wert |
|---|---|
| **Modul-ID** | M34 |
| **Name** | Public-API & Webhooks |
| **Milestones** | M161 (OpenAPI + Read-Endpoints), M162 (API-Key-Auth + Scopes + Rate-Limit), M163 (Webhooks ein-/ausgehend, signiert) |
| **Pflichtenheft-Block** | Block 7, Modul 34 (`_bmad-output/pflichtenheft/blocks/block7.md` Z. 264-311) |
| **Reuse-Level** | **medium** |
## Kurzfazit
Die Boilerplate bringt ein **echtes, dediziertes Public-API-Fundament** mit: eine eigenständige Hono-App (`apps/api`) mit OpenAPI-Generierung, Service-Token-/Tenant-API-Key-Auth, Scope-Autorisierung, Rate-Limit-Bausteinen (429 + `Retry-After`), Error-Envelope, Request-ID-Korrelation, Idempotenz, API-Request-Logging (`ApiKeyLog` mit den richtigen Indizes), und im Worker eine generische signierte Webhook-Auslieferung mit Backoff (`deliver-webhook`, 5 Versuche). Das deckt das **Querschnitts-Gerüst** der drei Milestones zu großen Teilen ab.
ABER: Die fachliche Substanz von M34 fehlt komplett. Die existierenden API-Endpoints sind **generisch** (`/v1/entities/:entity/rows`, EntityBuilder-Rows) — es gibt **keine** typisierten HiveGrid-Read-Endpoints (`/api/v1/contacts`, `deals`, `projects`, `leads` …), weil die HiveGrid-Domänenentitäten selbst noch nicht existieren (`app.prisma` ist leerer Platzhalter). Cursor-Pagination, Sparse Fieldsets, Embed-Relations und Scope-basiertes Field-Redact sind **nicht** vorhanden (nur page/pageSize-Pagination). Das gesamte M34-Datenmodell (`WebhookSubscription`, `WebhookDelivery`, `WebhookDeliveryAttempt`, `IncomingWebhookIngestion`, `IntegrationApiRequest`) existiert **nicht** in der Boilerplate. Das vorhandene Webhook-Modell ist `Event`/`EventWebhookAttempt` (Legacy) bzw. form-submission-gebunden — kein Subscription-Modell mit Event-Types, Auto-Disable und HMAC-Secret-pro-Subscription. Swagger-UI mit „Try it out" fehlt (nur Roh-JSON-Viewer unter `/v1/docs`).
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `apps/api/src/app.ts` | Hono-App-Komposition (`new Hono<ApiEnv>()`), Middleware-Kette, `register*Routes(app)`-Muster, listener-frei für Tests | 1:1 (App-Host) — neue HiveGrid-Read-Routes via eigenes `registerHiveGridReadRoutes(app)` einhängen |
| `apps/api/src/server.ts` | HTTP-Listener-Entry (`API_PORT`/`PORT`/`3001`) | 1:1 |
| `apps/api/src/openapi.ts` (+ `.test.ts`) | OpenAPI-Contract-Bausteine: Error-Envelope-Schema (`code`/`message`/`requestId`), Rate-Limit-`429`-Response mit `Retry-After`, `apiErrorResponse()`-Helper, `createOpenApiDocument()` | als-vorlage / anpassen — Envelope 1:1; HiveGrid-Endpoint-Schemas (contacts/deals/…) müssen ergänzt werden |
| `apps/api/src/routes/system-routes.ts` | `GET /v1/openapi.json` + `GET /v1/docs` (Doku-Seite) | anpassen — `/openapi.json` 1:1; `/v1/docs` ist NUR Roh-JSON-Viewer → für „Try it out" durch echte Swagger-UI (`swagger-ui-dist`) ersetzen |
| `apps/api/src/auth.ts` | `extractBearerToken`, `extractApiKeyFromRequest`, `isValidServiceToken`, `createServicePrincipal`, Typ `ServicePrincipal` | 1:1 — Bearer/Key-Extraktion direkt nutzbar; Format `Authorization: Bearer hg_<...>` deckungsgleich mit Spec B.1 |
| `apps/api/src/auth/scope.ts` (+ `.test.ts`) | `authorizeApiScope()`, `resolveApiTenantScope()`, deny-Reasons (`api_key_inactive`/`expired`/`tenant_deactivated`/`tenant_mismatch`/…), `ApiScopedPrincipal`-Union | als-vorlage — Tenant-Scope-Resolution + Key-Lifecycle 1:1; HiveGrid-Scopes (`read_only`/`read_full`/`webhook_inbound`/`automation_trigger`) müssen ergänzt werden (BP-Scopes sind read/create/update/delete pro Entity) |
| `apps/api/src/auth/permission.ts`, `login-rate-limit.ts` | Permission-Wiring + Token-/Window-Rate-Limit-Logik (IP-/Account-Scope, `retryAfterSeconds`) | als-vorlage — Rate-Limit-Algorithmus + 429-Shape übernehmen, auf Per-Key/Per-Tenant/Per-Slug erweitern (Redis-Counter) |
| `apps/api/src/routes/shared.ts` | `createLoginRateLimitResponse()` (429 + `Retry-After` + `rate_limited`-Envelope), `authenticateServiceCredentialRequest()`, JSON-Body-Parsing, Idempotenz-Helfer | als-vorlage — 429-Antwort-Shape und Auth-Helfer direkt als Muster |
| `apps/api/src/middleware/error-envelope.ts` | `apiError(c, status, code, message)`, `createErrorHandler`/`createNotFoundHandler` | 1:1 — deckt M34 Antwort-Format `{error:{code,message,details}}` (34.1.7) ab |
| `apps/api/src/middleware/request-id.ts`, `audit-context.ts`, `body-limit.ts`, `metrics.ts`, `sentryTracing.ts` | Standard-API-Middleware-Stack (Request-Korrelation, Audit-Kontext, Body-Limit, Metrik, Tracing) | 1:1 |
| `apps/api/src/route-access-inventory.ts` (+ `.test.ts`) | `routeAccessInventory` + 11 Auth-Klassen inkl. `tenant-api-key`, `service-or-tenant-api-key`, `webhook-signature`, `optional-api-key-validation`, `public-docs` | als-vorlage — neue HiveGrid-Routes müssen hier mit Auth-Klasse eingetragen werden (CI-Gate `verify:api-inventory`/`verify:openapi-security`) |
| `apps/api/src/idempotency/store.ts`, `shared-store-client.ts` | HTTP-Idempotenz-Cache (für Webhook-Empfang + Event-Ingestion-Idempotenz) | 1:1 |
| `apps/api/src/usage/usage-route.ts` | Vollständiger API-Key-Request-Flow als Referenz: Key auflösen → `ApiKeyLog` anlegen → Tenant-Deactivated/Expired/Inactive prüfen → Usage/402 → Log-Status setzen | als-vorlage — exaktes Muster für „Loader prüft Key-Existenz, Scope, Tenant, Aktiv-Status" (Spec B) + Request-Logging |
| `apps/api/src/webhooks/mailersend-signature.ts` (+ `.test.ts`) | HMAC-SHA256-Signatur-Verifikation mit `timingSafeEqual` (Constant-Time-Compare), Timestamp-Toleranz, typisierte Failure-Reasons | als-vorlage — direkt das Muster für M34 eingehende `X-HiveGrid-Signature: sha256=<hex>`-Verifikation (Spec B.2) |
| `packages/marketing-outbound/src/adapters/custom-webhook.ts` | Ausgehender Webhook-POST mit `X-Marketing-Signature: sha256=<hmac(body)>`, SSRF-Guard (`adapterFetch`, HTTPS-only, kein RFC1918) | als-vorlage — exaktes Muster für M34 ausgehende HMAC-signierte Deliveries (Spec E, Signatur + SSRF-Schutz) |
| `apps/worker/src/jobs/form-submission-webhook-delivery.ts` (+ `.test.ts`) | Outbox→Webhook-Delivery-Bridge auf `deliver-webhook`-Job, Tenant-Mismatch-Validierung | als-vorlage — Muster für „BullMQ-Job pro Webhook-Versand" (M163-Hinweis) |
| `packages/queue/src/payloads.ts` → `WebhookDeliveryJob` | Typisierter `webhook.deliver`-Job (`url`/`method`/`headers`/`body`/`eventName`/`metadata`) | 1:1 — direkt für ausgehende Webhook-Deliveries |
| `packages/queue/src/producers.ts` (`buildRetryJobOptions`) | `deliver-webhook`: **5 Versuche, exponentielles Backoff** + Idempotenz via `buildIdempotentJobId()` | anpassen — 5x deckt Spec E ab; Backoff-Stufen (1m/5m/30m/2h/12h) müssen exakt gesetzt werden (BP-Default ist `delay: 2_000` exponentiell) |
| `apps/api/src/webhookDeliveryQueue.ts` | `enqueueJob()`-Wrapper für Webhook-Auslieferung mit Idempotenz-Key + TenantId | als-vorlage |
| `packages/db/src/event-webhook-attempts.server.ts` | Repository-Muster für Webhook-Attempt-Persistenz (tenant-scoped find/update) | als-vorlage — Muster für neue `WebhookDelivery`/`WebhookDeliveryAttempt`-Repos |
| `packages/db/src/api-keys.server.ts` | API-Key-Repository: `findLegacyApiKeyByKey`, Key-Hashing (`keyHash`/`keyPrefix`/`keyLastFour`), `ApiKeyLog`-CRUD, Usage-Aggregation | als-vorlage / anpassen — Key-Hashing + Logging 1:1; HiveGrid-Scope-Spalte ergänzen (BP hat per-Entity-Rechte, kein Scope-Enum) |
| `packages/db/src/outbox.ts` (`publishOutboxEvent`) + `apps/worker/src/outbox/event-router.ts` | Transaktionales Outbox + Event-Routing (`webhook.`-Prefix → `outbox.webhook`-Queue, longest-prefix-wins) | 1:1 — für ausgehende Webhook-Events (`contact.created` etc.) als Dispatch-Mechanismus |
| `packages/db/src/audit-events.server.ts` + `AuditEvent` (Hash-Kette) | Auditierung von Key-Anlage, Webhook-Setup, Inbound-Events (DoD C.13, AV #6) | 1:1 |
| `apps/api/Dockerfile`-Target + `.gitea/workflows/ci.yml` `api`-Job | Build-/CI-Fundament: `verify:openapi-security` → typecheck → `vitest apps/api/src` → build | 1:1 |
| `infra/grafana/api-latency.json` + `infra/prometheus/` | API-Latenz-/Queue-Health-Dashboards (Metering-Vorbereitung Phase 2) | 1:1 |
---
## Vorhandene Daten-Modelle (Prisma)
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`.
| Modell | Datei | Deckt M34-Bedarf ab? |
|---|---|---|
| `ApiKey` | `core.prisma` (Z. 100-126) | **Teilweise.** Gehashte Keys (`keyHash`/`keyPrefix`/`keyLastFour`/`keyVersion`), `active`, `expires`, `@@unique([tenantId, alias])`. **Fehlt:** Scope-Spalte (BP nutzt `ApiKeyEntity`-Join mit create/read/update/delete pro Entity, NICHT die M34-Scopes `read_only`/`read_full`/`webhook_inbound`/`automation_trigger`) und Per-Key-Rate-Limit-Override-Feld. Spec B verweist explizit auf „API-Key-Verwaltung aus M27 Block E" → Scope-Modell gehört zu M27. |
| `ApiKeyLog` | `core.prisma` (Z. 128-151) | **Gut.** Deckt M34 `IntegrationApiRequest` weitgehend: `endpoint`, `method`, `params`, `status`, `duration`, `error`, `ip`, `tenantId`, `apiKeyId` + passende Indizes inkl. `(apiKeyId, tenantId, createdAt DESC)` und `(tenantId, createdAt)`. **Fehlt ggü. Spec A:** `route_pattern` (statt voll-aufgelöstem `endpoint`), `query_params` als JSONB (BP: `params` String), `request_body_size_bytes`/`response_size_bytes`, `user_agent`, Retention-Logik (90/180 Tage). Entweder `ApiKeyLog` erweitern oder eigenes `IntegrationApiRequest` bauen. |
| `Event` + `EventWebhookAttempt` | `core.prisma` (Z. 152-178) | **Schwach / Legacy.** `Event` (name/data/resource) + `EventWebhookAttempt` (endpoint/success/status/message/body). KEIN Subscription-Modell, keine Event-Types-Liste, kein HMAC-Secret-pro-Subscription, kein Auto-Disable-Counter, kein Idempotenz-`event_id`. Nur als grobe Vorlage für `WebhookDelivery`/`WebhookDeliveryAttempt` tauglich. |
| `EntityWebhook` + `EntityWebhookLog` | `entityBuilder.prisma` (Z. 206-224) | **Nicht passend.** Pro-Entity-Action-Webhook im EntityBuilder (entityId/action/method/endpoint). Kein Tenant-Subscription-Modell, kein Secret, kein Status-Enum/Retry. |
| `Form` + `FormSubmission` | `formWidget.prisma` | **Teil-Vorlage für eingehenden Lead-Push.** `Form` (`key @unique`, `definition` JSON, `fieldMapping`, `allowedOrigins[]`, Anti-Spam-`config`), `FormSubmission` (`payload` JSON, `ipHash`, `status` received/processed/failed/spam). Deckt das Slug-/Mapping-/Status-Muster von M34 `IncomingWebhookIngestion` konzeptionell ab, ist aber Form-Widget-gebunden, nicht Webhook-Slug-gebunden mit 3 Auth-Methoden. |
| `App` / `DataConnection` / `AppSyncRun` | `appsEngine.prisma` | **Randnah.** Externe Datensync-Engine (rest-api/oauth2/webhook, Rollback). Nicht für M34-Public-API, eher Phase-2-Inbound-Connectors. |
| `Lead` / `LeadEvent` | `marketingLeads.prisma` | **Beachten — Konflikt.** BP-`Lead` ist **operator-scoped (KEIN tenantId)**, M34 Lead-Push erzeugt **tenant-scoped** Leads (Modul 2/M042). M34-Webhook muss auf den HiveGrid-CRM-Lead schreiben, nicht auf diesen Marketing-Lead. |
| `OutboxEvent` | `outbox.prisma` | **1:1.** Transaktionaler Event-Auslöser für ausgehende Webhooks. |
| `IdempotencyKey` | `core.prisma` | **1:1.** HTTP-Idempotenz für Webhook-Empfang/Event-Ingestion. |
| `FeatureFlag` | `featureFlags.prisma` | **1:1.** DoD-Pflicht „Feature-Flag-fähig" (M006). |
### Komplett fehlende M34-Modelle (in `prisma/schema/` NICHT vorhanden — verifiziert)
`WebhookSubscription`, `WebhookDelivery`, `WebhookDeliveryAttempt`, `IncomingWebhookIngestion`, `IntegrationApiRequest` — **keiner dieser Namen existiert** im Schema. Anlageort: `prisma/schema/app.prisma` (aktuell leerer Platzhalter `// custom database models`).
---
## Lücken / komplett neu zu bauen
1. **HiveGrid-Domänenentitäten als Voraussetzung.** Die typisierten Read-Endpoints (`/api/v1/contacts|companies|deals|projects|tasks|leads`) setzen voraus, dass diese Module (M042-M074) existieren. `app.prisma` ist leer → es gibt nichts zum Lesen. M161 hängt hart an den Daten-Modulen (PLAN: „Vorbedingung Daten-Module M042-M074").
2. **Typisierte Read-API-Endpoints.** BP bietet nur generische EntityBuilder-Row-Endpoints (`/v1/entities/:entity/rows`). Die HiveGrid-Endpoints müssen neu gebaut werden (eigenes Route-Modul `register*Routes`).
3. **Cursor-Pagination.** BP hat nur `page`/`pageSize` (offset-basiert, `pagination/rows.ts`). Spec verlangt opaque base64-Cursor + `meta.next_cursor` → neu.
4. **Sparse Fieldsets (`fields=`), Embed-Relations (`embed=`, Tiefe 1), erweiterte Filter** (Multi-Value-OR, Date-Range `*_gte/_lte`, `custom.{key}`, `q`-Volltext), **Sortierung (`sort=-feld`)** — keiner dieser Mechanismen existiert generisch. Neu.
5. **M34-Scope-Modell** (`read_only`/`read_full`/`webhook_inbound`/`automation_trigger`) + **Field-Redact** sensibler Felder bei `read_only` (nicht 403, sondern Feld-Auslassung). BP-Scope ist entity-CRUD-basiert. Neu (kommt fachlich aus M27 Block E, hier konkretisiert).
6. **Rate-Limiting Per-Key / Per-Tenant / Per-Slug** mit Token-Bucket + Redis-Counter und Headern `X-RateLimit-Limit/Remaining/Reset`. BP hat nur Login-Rate-Limit (IP/Account) und `Retry-After` im 429. Die generischen `X-RateLimit-*`-Header existieren NICHT (nur in OpenAPI-Schema beschrieben). Neu — Algorithmus von `login-rate-limit.ts` als Vorlage.
7. **`IntegrationApiRequest`-Modell** (oder Erweiterung von `ApiKeyLog`) mit `route_pattern`, `query_params` JSONB, Größen-Feldern, `user_agent` + Retention-Job (90/180 Tage). Neu.
8. **Webhook-Subscription-Modell + UI.** `WebhookSubscription` (Event-Types[], HMAC-Secret, Auto-Disable-Counter, Stats), `WebhookDelivery` (Status-Enum pending/delivered/failed/exhausted/discarded), `WebhookDeliveryAttempt`. Komplett neu. Inkl. Subscription-Verwaltungs-UI unter `/{tenant}/admin/webhooks/`, Delivery-Stats-View, Test-Funktion (`test.ping`), Replay (Phase-2-Out-of-Scope). Auto-Disable nach 10 konsekutiven Fehlern + `notify()` (M011).
9. **Eingehende Webhook-Slugs.** `IncomingWebhookIngestion` + Slug-Verwaltung mit 3 Auth-Methoden (API-Key / HMAC / URL-Token mit Klartext-Warnung), `payload_mapping`, Auto-Lead-Anlage + Duplikat-Check (Email-Match → Activity statt neuem Lead), Default-Tags/Assignee. HMAC-Verify-Muster aus `mailersend-signature.ts` übernehmbar, Rest neu.
10. **Backoff-Stufen exakt.** BP `deliver-webhook` = 5 Versuche exponentiell `delay 2000` — Spec verlangt feste Stufen 1m/5m/30m/2h/12h. Job-Options anpassen/custom-Backoff.
11. **Event-Type-Katalog + Payload-Envelope** (`event_id`/`event_type`/`tenant_id`/`occurred_at`/`data`/`previous_data`) mit Mapping auf die ~30 HiveGrid-Events (`contact.created` … `call.missed`). Neu — Trigger-Punkte in jedem Quell-Modul.
12. **Allgemeine Event-Ingestion** `POST /api/v1/integrations/events` → Automation-Engine-Trigger (M075/M017 `external_event`). Verdrahtung neu.
13. **Swagger-UI mit „Try it out".** BP `/v1/docs` ist nur ein Roh-JSON-`<pre>`-Viewer (kein interaktives Swagger-UI, kein API-Key-Eingabefeld). `swagger-ui-dist` einbinden (M161-Hinweis nennt es als Boilerplate-Dep — als Paket vorhanden, aber NICHT als Route verdrahtet). Neu.
14. **Versionierung/Deprecation-Header** (`Sunset`, `Deprecation: true`, Stability-Tags). Nicht vorhanden. Neu (leichtgewichtig).
15. **402-bei-Frozen-Tenant für Schreib** (Spec 34.1.10) — da Phase 1 read-only ist, primär ein Webhook-Inbound-403-Pfad (frozen → eingehende Webhooks verworfen). BP-`usage-route.ts` hat das 402-Muster bereits (`payment_required`) als Vorlage.
16. **UI-Layer komplett** (DoD A-E): View-Models, Adapter, Sidebar-Eintrag (`packages/ui-hivegrid/src/app-shell/sidebar.config.ts`), Routes, i18n-Keys, Empty/Loading-States, Visual-Regression, Hot-Swap, Smoke-Tests. Reihenfolge & Wiring per `docs/INTEGRATION-CONTRACTS.md`. Nichts davon HiveGrid-spezifisch vorhanden.
---
## Empfohlenes Vorgehen
**Voraussetzung prüfen:** M27 (API-Keys + Scope-Definition) und die Daten-Module M042-M074 müssen stehen — sonst gibt es keine Scopes und keine Entitäten zum Lesen. Ohne diese ist M161 nicht sinnvoll baubar.
### M161 — Read-API + OpenAPI (zuerst aus BP übernehmen)
1. **App-Host 1:1 nutzen:** `apps/api/src/app.ts` + Middleware-Stack + `error-envelope.ts` + Request-ID stehen. Nur ein neues Route-Modul `registerHiveGridReadRoutes(app)` registrieren.
2. **Auth-Flow als Vorlage:** `usage-route.ts` + `auth.ts` + `auth/scope.ts` als Blueprint für „Key auflösen → loggen → Tenant/Active/Expired prüfen". `extractBearerToken`/`extractApiKeyFromRequest` 1:1.
3. **NEU bauen:** typisierte Endpoints, Cursor-Pagination, Filter/Sort/Fields/Embed-Parser, Response-Builder `{data, meta}`.
4. **OpenAPI:** `openapi.ts`-Envelope + `createOpenApiDocument()` erweitern; `swagger-ui-dist` als echte Route ergänzen (BP `/v1/docs` ersetzen).
5. **Route-Access-Inventar** (`route-access-inventory.ts`) für jede neue Route pflegen → sonst CI-Gate `verify:openapi-security`/`verify:api-inventory` rot.
### M162 — Scopes + Field-Redact + Rate-Limit
1. **Scope-Modell** an `ApiKey` koppeln (kommt aus M27); `authorizeApiScope`-Muster für `read_only`/`read_full` adaptieren.
2. **Field-Redact** im Response-Builder (sensible Felder bei `read_only` weglassen) — neu, im VM/Serializer.
3. **Rate-Limit:** Algorithmus aus `auth/login-rate-limit.ts` + Redis-Counter (`@toolctrl/queue` `resolveRedisConnectionOptions`) auf Per-Key/Per-Tenant/Per-Slug ausweiten; `X-RateLimit-*`-Header + 429-Shape aus `routes/shared.ts` übernehmen.
4. **Request-Logging:** `ApiKeyLog` erweitern oder `IntegrationApiRequest` neu + Retention-Cron (Muster: `apps/worker/src/jobs/audit-retention.ts`).
### M163 — Webhooks (signiert)
1. **Neue Prisma-Modelle** in `app.prisma`: `WebhookSubscription`, `WebhookDelivery`, `WebhookDeliveryAttempt`, `IncomingWebhookIngestion` (Forward-Only-Migration mit Inverse-SQL, DoD F.28). DSGVO: neue User-FKs in `packages/db/src/dsgvo/user-fk-map.ts` eintragen (sonst CI rot).
2. **Eingehende Webhooks:** HMAC-Verify aus `webhooks/mailersend-signature.ts` (Constant-Time) übernehmen; Slug-/Mapping-/Auth-Logik neu; Idempotenz via `IdempotencyKey`; Auto-Lead-Anlage auf HiveGrid-CRM-Lead (nicht Marketing-`Lead`) + Activity via `logActivity`.
3. **Ausgehende Webhooks:** Outbox (`publishOutboxEvent`) → `webhook.`-Prefix-Routing → `deliver-webhook`-Job (5 Versuche). HMAC-Sign-/SSRF-Muster aus `marketing-outbound/custom-webhook.ts`. Backoff-Stufen auf 1m/5m/30m/2h/12h anpassen. Auto-Disable nach 10 Fehlern + `notify()` (M011). Delivery-/Attempt-Persistenz à la `event-webhook-attempts.server.ts`.
4. **Event-Ingestion** `POST /v1/integrations/events` → Automation-Trigger (M075/M017).
5. **UI** für Subscriptions/Slugs/Logs (DoD A-E) zuletzt: Subframe → Adapter → View-Model → Route → Sidebar + Permission-Gate + i18n + Tests.
### Querschnitt nicht nachbauen (DoD): Audit (`AuditEvent`/`auditEvent`), Outbox, Idempotenz, FeatureFlag, Notifications (`notify`), Tenant-Scope — alles in BP vorhanden und Pflicht-Wiring.
@@ -0,0 +1,124 @@
# Boilerplate-Abgleich — M35 DSGVO-Export / Account-Löschung
| Feld | Wert |
|---|---|
| **Modul-ID** | M35 |
| **Name** | DSGVO-Export / Account-Löschung / Tenant-Daten-Portabilität |
| **Milestones** | M164 (Daten-Export), M165 (Lösch-Workflow), M166 (AVV/Auskunft) |
| **Block** | Block 7 — Plattform-Außenseite |
| **Reuse-Level** | **medium** |
## Zusammenfassung
Die Boilerplate hat ein **vollständiges, getestetes USER-Level-DSGVO-Subsystem** (Phase 10 Task #68):
Personal-Data-Export-Worker, Lösch-Cascade-Worker, Grace-Period-Cron, Pseudonymisierung, eine
zentrale `USER_FK_MAP` über alle User-FKs, ein Selbst-Service-Privacy-Hub im Web (Export/Delete/Reactivate
mit Email-Confirm-Token + 30-Tage-Grace), CLI-Commands und ein generisches Streaming-Export-Framework
(`packages/exports`: CSV/JSON/XLSX/PDF + S3-Multipart-Sink + Row-Caps + Audit-PDF). Das deckt **M165
(Account-Löschung) und einen Großteil von M164 (User-Daten-Export)** als hochwertige Vorlage ab.
**Komplett fehlend** ist die gesamte **TENANT-Ebene**: Tenant-Voll-Export (`scope=tenant_full`),
Tenant-Lösch-Workflow + Hard-Delete-Cron (Storage/Embeddings/Queues/Webhooks/DB in FK-Reihenfolge),
Tenant-Lifecycle-Status (`deletion_pending`/`deleted`/`frozen`/`past_due` als Enum), **AVV-Vertrag**
(PDF-Generator, `AvvAcceptance`, Re-Akzeptanz-Flow), **Subprozessoren-Liste** (`Subprocessor`-Modell +
UI + Widerspruchs-Frist) und **ZIP-mit-Binär-Dateien**-Bundling (Boilerplate exportiert nur ein
JSON-Bundle, keine `.zip` mit Original-Files). Die HiveGrid-spezifischen DSGVO-Modelle (`GdprExportJob`,
`TenantDeletionRequest`, `AvvAcceptance`, `Subprocessor`) existieren nicht.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `packages/exports/src/index.ts` (+ `csv/`, `json/`, `pdf/`, `xlsx/`, `types.ts`, `limits.ts`, `sinks/s3-multipart.ts`, `format-caps.ts`, `spreadsheet-safety.ts`, `audit-pdf.ts`) | Streaming-Export-Framework: Format-Serializer (Stream + Buffer), `createS3MultipartUploadSink` (8 MB Parts, Auto-Abort), Plan-/Format-Row-Caps, Injection-Safety, Compliance-Audit-PDF-Renderer | **1:1** als Fundament für beide Export-Scopes |
| `apps/worker/src/jobs/dsgvo-export.ts` | User-Personal-Data-Export-Worker: iteriert `USER_FK_MAP.includeInExport`, streamt JSON-Bundle zu S3, mintet Signed-URL, sendet Ready-Email, schreibt `AuditEvent` (action=EXPORT_PERSONAL_DATA, scope=gdpr, sensitivity=pii). Host-agnostisch (DI über `DsgvoExportDependencies`) | **anpassen** — Basis für M164 User-Export; ZIP-statt-JSON + README/manifest.json + Binär-Files ergänzen |
| `apps/worker/src/jobs/dsgvo-deletion.ts` | User-Lösch-Cascade: pro `USER_FK_MAP`-Eintrag `hard-delete`/`pseudonymize`/`retain-tombstone`, User-Row löschen oder pseudonymisieren, Audit. Idempotent, DI-fähig | **anpassen** — deckt M165 Account-Löschung (35.2.4 „PII überschrieben, Audit behält User-ID") direkt ab |
| `apps/worker/src/jobs/dsgvo-grace-cron.ts` | 24h-Cron: scannt `User.pendingDeletion && scheduledDeletionAt<=now`, dispatcht Lösch-Jobs. Idempotenter `upsertJobScheduler` | **als-vorlage** — Muster 1:1 übertragbar auf Tenant-Hard-Delete-Cron (35.3.4) |
| `packages/db/src/dsgvo/user-fk-map.ts` | Zentrale Karte ALLER Modelle mit User-FK + Cascade-Strategie + `includeInExport`. CI-Test (`user-fk-map.test.ts`) erzwingt Vollständigkeit gegen Schema | **anpassen** — Pflicht-Referenz; jedes neue HiveGrid-Modell mit User-FK muss ergänzt werden. Vorlage für eine analoge `TENANT_FK_MAP` (Tenant-Hard-Delete) |
| `packages/db/src/dsgvo/pseudonymize.ts` | Deterministische Pseudonymisierungs-Helfer (`pseudonymize`, `buildUserPseudonymizationUpdate`) | **1:1** für 35.2.4 Anonymisierungs-Strategie |
| `apps/web/app/routes/app.$tenant/settings/privacy.tsx` + `privacy.delete.confirm.$token.tsx` + `privacy.delete-mail.test.tsx` | Selbst-Service-Privacy-Hub: Export-Anstoß, Lösch-Anforderung mit Confirm-Phrase, Email-Confirm-Link, Reactivate, CSRF, Audit pro Intent. Route liegt bereits unter `app.$tenant/settings/privacy` | **als-vorlage** — entspricht Spec-Route `/{tenant}/settings/account/delete` + `.../data-export`; Multi-Step-Flow (35.2.3) + 1.5-Export-Angebot ergänzen. **Achtung:** verstößt noch gegen HiveGrid-Layer-Trennung (Prisma im Loader, kein VM, Inline-Styles statt i18n-VM) → muss in VM/`ui-hivegrid`/Adapter umgebaut werden |
| `apps/web/app/utils/dsgvo/deletionToken.server.ts` | HMAC-signierter Lösch-Confirm-Token (24h, fail-closed, eigene Version gegen Replay) | **1:1** für 35.2.5 24h-Reverse-Window (Magic-Link gegen Auth-Bypass) |
| `packages/storage/src/signed/index.ts` | S3-Signed-URL-Adapter (PUT/GET, Expiry-Clamp, Key-Validierung, Secret-Redaction) | **1:1** für 7-Tage-Download-Window-Signed-URLs (35.1.5) |
| `prisma/schema/imports.prisma` (`ExportJob`-Modell, Migration `20260508000000_export_jobs` + `..._export_job_hard_delete`) | `ExportJob`: tenantId, requestedByUserId, exportType, format, status (`ExportJobStatus`), requestId, artifactBucket/Key, rowCount, `expiresAt`/`deletedAt`/`hardDeletedAt` (Retention), error-Felder, Timestamps. Indizes inkl. `(expiresAt)` für Cleanup-Cron | **anpassen** — sehr nah an Spec-`GdprExportJob`; es fehlen `scope`-Enum, `target_user_id`, `progress_percent`, `download_count`, `last_downloaded_at`, `result_size_bytes` |
| `apps/worker/src/jobs/export.ts` | Generischer Export-Job: Plan-Resolution, Row-Cap-Enforcement, Format-Streamer-Registry, Progress-Publish via SharedStore, S3-Multipart. Liest `ExportJob`-Queue-Payload | **als-vorlage** — Progress-Update-Muster (alle N Rows, 35.1.4) + Tenant-Plan-Auflösung direkt übernehmbar |
| `packages/queue/src/payloads.ts` | Queue-Payloads: `CleanupJob.task` enthält bereits `'expired-export-artifacts'` + `'dsgvo-grace-period-scan'`; `ExportJob` (`kind: "export.run"`); `queueNames.exports` | **anpassen** — Cleanup-Task für ZIP-Ablauf (7 Tage) bereits vorgesehen; neue Tenant-Lösch-/Export-Tasks ergänzen |
| `apps/worker/src/jobs/dsgvo-verify.ts` + `audit-retention.ts` | Verify-/Retention-Muster für DSGVO-Jobs | **als-vorlage** |
| `packages/cli/src/commands/dsgvo/{export,delete,verify,reactivate,index}.ts` + `commands/tenant/anonymize.ts` | Operator-CLI für DSGVO-Aktionen (für Plattform-Admin-initiierte Löschung, 35.3.5) | **als-vorlage** für M37-Plattform-Admin-Pfad (`admin_initiated`, `suspended_violation`) |
| `apps/web/app/routes/app.$tenant/settings.tsx` + `settings/account.tsx` | Tenant-Settings-Shell + Account-Settings-Page-Muster | **als-vorlage** für Privacy-Hub-Routes `/{tenant}/admin/privacy/*` und `/{tenant}/settings/account/*` |
| `packages/db/src/audit-events.server.ts` (`createAuditEvent`) | Audit-Schreiber mit `regulatoryScope`/`dataSensitivity` | **1:1** — entspricht Querschnitt AV #6 (alle Privacy-Aktionen geloggt) |
---
## Vorhandene Daten-Modelle (konkret)
| Modell | Pfad | Deckt M35-Bedarf |
|---|---|---|
| `ExportJob` (+ Enum `ExportJobStatus`) | `prisma/schema/imports.prisma` | ~70 % von `GdprExportJob`: Retention (`expiresAt`/`deletedAt`/`hardDeletedAt`), `requestId`, `artifactBucket/Key`, `rowCount`, Status, Indizes. **Fehlt:** `scope`-Enum (user_self/tenant_full), `target_user_id`, `progress_percent`, `download_count`, `last_downloaded_at`, `result_size_bytes`, FK auf `File` |
| `User` (DSGVO-Felder) | `prisma/schema/accounts.prisma` (Z. 33-38, 95) | `pendingDeletion`, `scheduledDeletionAt`, `deletionRequestedAt`, `pseudonymized`, `pseudonymizedAt`, `deletionRequestId` (unique) + Index `user_pending_deletion_due_idx`. **Deckt 35.2 Account-Löschung-State vollständig** |
| `Tenant` | `prisma/schema/accounts.prisma` (Z. 129-200) | Nur `active: Boolean` + `deactivatedReason: String?`. **KEIN Lifecycle-Status-Enum** (frozen/past_due/deletion_pending/deleted). Kein Grace-Period-Feld |
| `ImportJob` (+ Enum) | `prisma/schema/imports.prisma` | Nur Import-Seite — als Form-Vorlage für `GdprExportJob`-Felder nutzbar |
| `AuditEvent` | `prisma/schema/core.prisma` (logisch, via `user-fk-map`) | `actorId`/`regulatoryScope`/`dataSensitivity` — Plattform-Audit-Metadata nach Hard-Delete (35.3.4) bereits vorgesehen |
**Nicht vorhanden (komplett neu):** `GdprExportJob` (HiveGrid-spezifisch mit `scope`), `TenantDeletionRequest`,
`AvvAcceptance`, `Subprocessor`.
---
## Lücken / komplett neu zu bauen
### Daten-Layer (neu)
- **`TenantDeletionRequest`-Modell** — reason-Enum (voluntary/non_payment/suspended_violation/admin_initiated), `grace_period_ends_at`, status, cancel-Felder, Unique-Constraint „max 1 aktive". Cron-Index `(grace_period_ends_at, status)`.
- **`AvvAcceptance`-Modell** — version, IP/User-Agent, Signer-Name/Rolle, `pdf_file_id`, Unique `(tenant_id, avv_version)`.
- **`Subprocessor`-Modell** — plattform-global (kein RLS), name/purpose/country/is_eu_eea/data_categories[]/dpa_url/active_since/archived_at.
- **Tenant-Lifecycle-Status** — Enum (`active|frozen|past_due|deletion_pending|deleted`) + `grace_period_ends_at` auf `Tenant` (oder via `TenantDeletionRequest`). Aktuell nur Boolean `active`.
- **`GdprExportJob`-Erweiterung** — `scope`-Enum, `target_user_id`, `progress_percent`, `download_count`, `last_downloaded_at`, `result_size_bytes`, FK auf `File` (Modul 23).
### Domänen-Logik / Worker (neu)
- **Tenant-Voll-Export-Worker** (`scope=tenant_full`) — aggregiert ALLE tenant-scoped Entitäten je JSONL-File (CRM/Deals/Projects/HR/… laut Spec Block D) + Original-Files. Es gibt KEINE `TENANT_FK_MAP`-Analogie zur `USER_FK_MAP`.
- **ZIP-mit-Binär-Bundling** — Boilerplate streamt nur ein flaches JSON-Bundle. Es gibt **keine** `archiver`/`yazl`/`jszip`-Nutzung. Spec verlangt ZIP mit README.md, manifest.json, Unterordnern, JSONL + Original-Binär-Files + `schema/` + Multi-Part-ZIP.
- **Tenant-Hard-Delete-Cron + Cascade** — FK-konforme Reihenfolge inkl. Storage rekursiv, Embeddings (pgvector), Worker-Queues purgen, Webhook-Subscriptions, Redis-Cache (`tenant:{id}:*`). User-Cascade existiert, Tenant-Cascade nicht.
- **AVV-PDF-Generator** — dynamisches PDF mit Tenant-Stamm + Subprozessor-Snapshot. `@react-pdf/renderer` ist verfügbar (für Audit-PDF), aber kein AVV-Template.
- **AVV-Re-Akzeptanz-Cron** (14-Tage → Read-Only) + Subprozessor-Widerspruchs-Frist-Cron (14-Tage).
- **Rate-Limit-Logik** — max 3 user_self/24h, max 1 tenant_full aktiv (Spec-Constraint; nicht in Boilerplate).
- **Resume/Checkpoint-Mode** für großen Tenant-Export (Block D Edge-Case) — nicht vorhanden.
### UI (neu / Umbau)
- **Privacy-Hub Tenant-Admin** (`/{tenant}/admin/privacy/*`: export, deletion, subprocessors, avv) — existiert nicht.
- **Multi-Step-Tenant-Kündigung** (5 Steps mit Slug-Confirm-Phrase, Stripe-Hinweis) — nur einfacher User-Delete vorhanden.
- **Subprozessoren-Tabelle** (Filter EU/alle, Suche, CSV/PDF-Export, Drittland-Klartext-Warnung) — neu.
- **AVV-Download + Akzeptanz-History** + Re-Akzeptanz-Modal — neu.
- **Bestehende `privacy.tsx`** muss auf HiveGrid-Layer-Trennung umgebaut werden (VM-Builder, `packages/ui-hivegrid`, Subframe-Adapter, i18n-Keys statt Inline-Strings/Tailwind) — siehe AGENTS.md Anti-Patterns.
### Querschnitt-Wiring (neu)
- **Permissions** `privacy.user_export.self`, `privacy.tenant_export`, `privacy.tenant_deletion`, `privacy.subprocessors.read`, `privacy.avv.read`, `privacy.avv.accept` — nicht im `permissions-seed.server.ts` (nur „account deletion"-Bezug im Admin-Role-Kommentar). Neu in `packages/entitlements`.
- **Sidebar-Eintrag** „DSGVO / Datenschutz" Gruppe EINSTELLUNGEN (INTEGRATION-CONTRACTS §1 → M164-M166) in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` — neu (HiveGrid-Sidebar-Config existiert in Boilerplate nicht, nur ToolCTRL-`application/sidebar`).
- **Notifications via M011 `notify()`** — Boilerplate-Worker rufen `sendEmailMailerSend`/`sendExportReadyEmail` direkt; muss auf HiveGrid-`notify()`-Service umgestellt werden.
- **Mail-Templates** für Export-Ready / Lösch-Bestätigung / AVV-Re-Akzeptanz / Subprozessor-Notification — keine dedizierten DSGVO-Templates in `packages/email-templates` gefunden.
- **Privacy-Manifest (Apple)** — Block I; gehört zu Modul 36, Inhalt-Quelle hier. Keinerlei Boilerplate-Asset.
---
## Empfohlenes Vorgehen
**Phase 1 — Fundament aus BP übernehmen (1:1 / leichte Anpassung):**
1. `packages/exports` als Export-Framework übernehmen (Streamer + S3-Multipart-Sink + Row-Caps + Audit-PDF). Basis für beide Scopes.
2. `packages/storage/src/signed` (Signed-URL) + `utils/dsgvo/deletionToken.server.ts` (Confirm-Token) + `packages/db/src/dsgvo/pseudonymize.ts` 1:1 übernehmen.
3. `ExportJob`-Modell aus `imports.prisma` zu HiveGrid-`GdprExportJob` erweitern (`scope`, `target_user_id`, `progress_percent`, `download_count`, `result_size_bytes`, `File`-FK). Forward-Only-Migration.
**Phase 2 — M165 Account-Löschung (höchste BP-Deckung):**
4. `dsgvo-deletion.ts` + `dsgvo-grace-cron.ts` + `user-fk-map.ts` als Cascade-Basis nutzen; `USER_FK_MAP` um alle neuen HiveGrid-Modelle ergänzen (CI-Test erzwingt das).
5. `privacy.tsx`-Route auf HiveGrid-Layer-Trennung umbauen (VM + `ui-hivegrid` + Subframe-Adapter + i18n) und Multi-Step + Step-1.5-Export-Angebot ergänzen.
**Phase 3 — M164 User-Export, dann Tenant-Export (neu auf BP-Fundament):**
6. `dsgvo-export.ts` zu ZIP-Bundle ausbauen: ZIP-Lib (`archiver`/`yazl`) einführen, README.md/manifest.json + Unterordner-Struktur (Spec Block C) + Original-Binär-Files aus Storage. Progress-Muster aus `export.ts`.
7. Tenant-Voll-Export NEU bauen: `TENANT_FK_MAP`-Analogie + JSONL-pro-Entität + Files + Multi-Part-ZIP + Resume-Checkpoint.
**Phase 4 — M165 Tenant-Lösch-Workflow (neu):**
8. `TenantDeletionRequest`-Modell + Tenant-Lifecycle-Status-Enum + Multi-Step-Kündigung (Slug-Confirm-Phrase, Stripe-Hinweis aus M153) + 30-Tage-Grace-Banner + Cancel.
9. Tenant-Hard-Delete-Cron (Cron-Muster aus `dsgvo-grace-cron.ts`): Storage rekursiv → Embeddings → Queues → Webhooks → DB (FK-Reihenfolge) → Redis-Cache → Plattform-Audit-Metadata.
**Phase 5 — M166 AVV + Subprozessoren (komplett neu):**
10. `AvvAcceptance` + `Subprocessor`-Modelle, AVV-PDF-Generator (`@react-pdf/renderer` ist da), Signup-Checkbox-Hook (M157), Re-Akzeptanz-Cron, Subprozessoren-Tabelle-UI + Widerspruchs-Frist-Cron + Notification-Templates.
**Querschnitt durchgängig:** Permissions in `entitlements` definieren, Sidebar-Eintrag (Gruppe EINSTELLUNGEN), `notify()` statt Direkt-Email, Mail-Templates, alle Aktionen auditieren (BP-`createAuditEvent` ist da).
@@ -0,0 +1,122 @@
# Boilerplate-Abgleich — M36 Mobile-App (Capacitor)
- **Modul-ID:** M36
- **Name:** Mobile-App (Capacitor-Wrapper für iOS + Android)
- **Zugehörige Milestones:** M167 (Capacitor-Setup + Build-Pipeline), M168 (Native-Features Push/Face-ID/Kamera + Universal Links), M169 (Native Tab-Bar + Mobile-First-Routes), M170 (Offline-Modus Phase-1-Pflicht), M171 (App-Store-Compliance + Force-Update)
- **Pflichtenheft-Block:** Block 7 (Plattform-Außenseite), Pflichtenheft-Modul 36
- **Reuse-Level:** **medium**
## Kurzfazit
Die Boilerplate liefert ein **vollständiges, getestetes Capacitor-7-Wrapper-Grundgerüst** (`apps/mobile`) inkl. der serverseitigen Push-Pipeline — das ist genau das Fundament, das M36 braucht und das normalerweise teuer zu bauen ist. **Stark abgedeckt:** Capacitor-Setup (M167), Push-End-to-End (M168 Teil C.1, M22-Dependency), Session-Persistenz, Sentry, Native-Permission-Strings (Info.plist + AndroidManifest), Shell-Mobile-Registry (Tab-Bar-Datenmodell). **Komplett fehlend:** der gesamte **Offline-Modus** (M170 — IndexedDB-Cache, OfflineSyncQueue, Sync-on-Reconnect, Konflikt-Resolution), **Biometrie/Face-ID** (M168 C.2), **Kamera-Plugin + lokales Resize** (M168 C.3), **Apple-Compliance-Schicht** (M171 — Pricing-Hide-Flag, Demo-Account, Privacy-Manifest, Submission-Playbook), **Universal-Links** (AASA/assetlinks Files), **Force-Update / Web-Bundle-Version-Check** und die Prisma-Modelle `MobileAppSession` + Biometrie-Felder.
Wichtig: Die Boilerplate kennt `de.toolctrl.app` als App-ID und `ToolCtrl` als Namen — beim Übernehmen müssen App-ID, Name, Bundle-IDs, Permission-Strings und alle Klartexte auf HiveGrid umgestellt werden. Außerdem ist die Boilerplate-Auth **token-basiert ohne eigene DB-Session-Tabelle**, während M36 (über M27) eine zentrale `Session`-Tabelle voraussetzt — das ist eine Lücke, die in M27 zu schließen ist, nicht in M36.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `apps/mobile/` (gesamtes Workspace) | Capacitor-7-Wrapper-Skeleton: `package.json`, `capacitor.config.ts`, `ios/`, `android/`, `src/`, `tsconfig.json`, `.gitignore` | **als-vorlage** — Struktur 1:1, aber App-ID/Name/Strings auf HiveGrid umstellen |
| `apps/mobile/capacitor.config.ts` | Config mit `webDir: "../web/build/client"`, `readLiveReloadUrl()` (Live-Reload via `MOBILE_LIVE_RELOAD_URL`), Plugin-Config (Splash/StatusBar/Push/Preferences-Suite) | **anpassen** — `appId`/`appName` ändern, Plugins ergänzen (Camera, Network, Biometric) |
| `apps/mobile/src/index.ts` | `bootstrapMobileShell()` — idempotenter Boot: Sentry-Init + Auth-Rehydrate + opt-in Push-Registration; test-seam-fähig | **anpassen** — Boot-Schritte um Offline-Pre-Cache + Biometrie-Rehydrate erweitern |
| `apps/mobile/src/auth.ts` | Session-Persistenz-Adapter (`SessionStorage`-Interface, `MobileSession`-Typ, `rehydrateAuth`/`persistSession`/`clearSession`, `createMobileApiClient`); Capacitor-Preferences + localStorage-Fallback | **anpassen** — Achtung: Preferences ist NICHT verschlüsselt; für Biometrie-Secret muss OS-Keychain-Adapter ergänzt werden (Spec A.2-Constraint) |
| `apps/mobile/src/pushRegistration.ts` | `registerPushNotifications()` — kompletter APNs/FCM-Flow: Permission-Check → Token holen (mit Timeout) → `POST /v1/devices/register`; graceful skip-reasons | **anpassen** — Endpoint-Pfad auf HiveGrid-Konvention (`/api/v1/notifications/mobile-device`), Pre-Prompt-UI ergänzen (Spec C.1) |
| `apps/mobile/src/sentry.ts` | `initMobileSentry()` (Sentry-Capacitor, spiegelt Web-Sentry, platform-Tag) | **1:1** (nur DSN/Projekt-Config) |
| `apps/mobile/ios/App/App/Info.plist` | Permission-Strings: `NSCameraUsageDescription`, `NSFaceIDUsageDescription`, `NSPhotoLibraryUsageDescription`, `UIBackgroundModes: remote-notification`, ATS strict | **anpassen** — Klartexte auf HiveGrid-Wortlaut (Spec C.2/C.3 Pflicht-Strings), Universal-Links-Entitlement + `PrivacyInfo.xcprivacy` ergänzen (fehlen) |
| `apps/mobile/android/app/src/main/AndroidManifest.xml` | Permissions: `INTERNET`, `ACCESS_NETWORK_STATE`, `POST_NOTIFICATIONS` (API 33+), `USE_BIOMETRIC`, `CAMERA`; Custom-URL-Scheme `toolctrl://`-Intent-Filter; FileProvider | **anpassen** — Scheme auf `hivegrid://`, App-Links-Intent-Filter für `app.hivegrid.de` ergänzen, `READ_MEDIA_IMAGES` ergänzen |
| `apps/worker/src/jobs/push-notification.ts` | **Push-Fan-out-Worker** — APNs/FCM/WebPush-Versand pro DeviceToken, provider-pluggable (firebase-admin + node-apn injectable), Auto-Revoke bei `Unregistered`/`InvalidRegistration`/`BadDeviceToken`; ENV: `FCM_SERVICE_ACCOUNT_JSON`, `APNS_KEY/KEY_ID/TEAM_ID/BUNDLE_ID` | **anpassen** — gehört zu M22-Push-Pipeline; M36 ist Konsument. EU-Stack-Vorgabe (Novu, LP-13) prüfen — Boilerplate nutzt direkt FCM/APNs |
| `apps/api/src/routes/devices-routes.ts` | `POST /v1/devices/register` + `/v1/devices/revoke` mit Validierung, Upsert-by-token (idempotent), Klartext-Fehler-Envelope | **anpassen** — Pfad/Auth auf HiveGrid (Self-Scope statt service-credential), `tenant_id`-Multi-Registrierung pro Tenant (Spec A.1) sicherstellen |
| `packages/db/src/device-tokens.server.ts` | `registerDeviceToken`/`revokeDeviceToken`/`parseDevicePlatform`/`parsePushProvider` (188 Zeilen Domänen-Logik) | **anpassen** — RLS/Tenant-Scope nach HiveGrid-Konvention |
| `prisma/schema/notifications.prisma` → `DeviceToken` | Modell für APNs/FCM/WebPush-Token (`token @unique`, `pushProvider`, `appVersion`, `lastSeenAt`, `revokedAt`, User+Tenant-Relation, Indizes) | **als-vorlage** — deckt M36-Block-A.1 (`NotificationDevice`-Konsum) konzeptionell ab; in HiveGrid als M22-Entität spec'd |
| `apps/web/app/lib/pwa/registerServiceWorker.ts` + `apps/web/public/sw.js` | PWA-Service-Worker-Registrierung + minimaler SW (cache-first für `/assets/`, network-first für `/api`/`/app`/`/admin`, Offline-Fallback) | **als-vorlage** — solides Fundament für M170-Offline, aber **kein** Workbox, **keine** IndexedDB/Queue-Integration; muss massiv erweitert werden |
| Shell-Registry: `MobileRegistryItem`, `createMobileRegistry()` (`packages/foundation` / `packages/ui-shell`, siehe Inventur `foundation.md:77`, `ui-shell.md:59/90`) | Typ + Builder für Mobile-Tab-Bar-Einträge (priority-sortiert, `RegistryGate` für Permission+Flag) | **anpassen** — Datenmodell für M169-Tab-Bar vorhanden; eigentliche native Tab-Bar-Rendering + UI-Modus-Logik (Baustelle/Büro) fehlt |
| `apps/web/public/.well-known/` | Verzeichnis existiert (aktuell `security.txt`, `pgp-key.txt`) | **als-vorlage** — Ablageort für `apple-app-site-association` + `assetlinks.json` (Spec I.1) — Dateien selbst fehlen |
| `packages/api-client-ts` | TS-SDK (`createToolctrlClient`, refresh-aware Bearer via `getToken`-Callback) — vom Mobile-Wrapper konsumiert | **1:1** (HiveGrid-eigene SDK-Variante) |
| `docs/operations/capacitor.md` + `docs/improvement-plan/08-mobile-cli-storybook-sdk/capacitor.md` | Build/Signing/Submission-Runbook + Spec/Deviation-Log | **als-vorlage** — Operator-Runbook übernehmen, Submission-Strategie (Spec K) ergänzen |
| `package.json` `test:mobile` + `.gitea/workflows/ci.yml` (Schritt `test:mobile`) | CI-Gate für Mobile-Unit-Tests bereits verdrahtet | **1:1** (Pattern) — native Build-Pipeline (Tag `mobile-vX.Y.Z` → TestFlight/Play, Spec B.3) fehlt |
| `apps/mobile/src/*.test.ts` (auth/push/sentry/index/capacitor-config) | Vitest-Tests als Test-Pattern für Mobile-Layer | **als-vorlage** |
---
## Vorhandene Daten-Modelle
| Modell | Pfad | Deckt M36-Spec ab |
|---|---|---|
| `DeviceToken` | `prisma/schema/notifications.prisma:66` | Block A.1 (`NotificationDevice`-Konsum): `token @unique`, `pushProvider` (fcm/apns/webpush), `platform`, `appVersion`, `lastSeenAt`, `revokedAt`, User+Tenant-Relation. **Lücke:** pro-Tenant-Mehrfachregistrierung (mehrere Einträge gleicher Token + verschiedene `tenant_id`) ist nicht durch `token @unique` abgedeckt — Constraint muss in HiveGrid auf `(token, tenantId)` o.ä. angepasst werden (Spec A.1). |
| `NotificationDelivery`, `UserNotificationPreference` | `prisma/schema/notifications.prisma:14/41` | Notification-Querschnitt (M22) — Channels nur `IN_APP`/`EMAIL`, **kein** `PUSH`-Channel im Preference-Enum (siehe Lücken). |
| `User`, `Tenant`, `TenantUser` | `prisma/schema/accounts.prisma:1/129/286` | Auth-/Tenant-Basis, an die Device-Token + Mobile-Session hängen. |
**Nicht vorhanden (M36-Spec-Modelle fehlen komplett):**
- `MobileAppSession` (Spec A.2) — Device-Kind, biometric_enabled/kind, os_version, app_version, web_bundle_version, last_foreground_at, last_sync_at. **Voraussetzung-Lücke:** Es gibt in der Boilerplate gar keine zentrale Prisma-`Session`-Tabelle (Auth ist token/JWT-basiert, keine `model Session`), auf die `MobileAppSession.session_id` als FK verweisen könnte. Diese zentrale `Session`-Tabelle muss in M27 entstehen.
- `OfflineSyncQueue` (Spec A.3) — ist laut Spec ohnehin client-seitig in IndexedDB (kein Cloud-Modell), aber die client-seitige Implementierung fehlt vollständig.
- Biometrie-Felder/-Speicher (Spec A.2-Constraint, OS-Keychain) — Capacitor-Preferences-Adapter vorhanden, aber **unverschlüsselt**; Keychain-Adapter fehlt.
---
## Lücken / komplett neu zu bauen
### Offline-Modus (M170, Spec Block D + E) — **größte Lücke, Phase-1-Pflicht**
- **Kein IndexedDB / Dexie.js** im gesamten Repo (verifiziert: kein `dexie`, kein `indexeddb`-Store-Code).
- **Kein Read-Cache** (Spec A.4 — `cache.assigned_projects` etc.) und kein Pre-Cache-beim-Login-Flow (Spec D.2).
- **OfflineSyncQueue** (Spec A.3/D.4) — Queue-Entität, Stati (`pending/syncing/synced/failed/conflict`), Binary-Blob-Storage für Fotos, Aufbewahrungs-/Cleanup-Logik (Spec E.6).
- **Sync-on-Reconnect** (Spec E) — Trigger (Network-Wechsel/Foreground/Force-Sync/periodisch), Sync-Reihenfolge (Read-Refresh → Queue-Drain mit Idempotency-Key → Read-Refresh), Backoff-Retry, Konflikt-Erkennung (409), Last-Write-Wins + Konflikt-Resolution-UI (Spec E.3/E.4).
- **Network-Status-Detection** — `@capacitor/network`-Plugin **nicht installiert**.
- **Service-Worker** vorhanden, aber minimal (kein Workbox, keine Offline-Queue-Integration, keine Offline-Fallback-Page für nicht-gecachte Routen).
- **Idempotenz** — HiveGrid hat M007 (Idempotenz-Wrapper) zur Wiederverwendung; Boilerplate-Wrapper hat in `devices-routes` nur Upsert-by-token, kein generischer Idempotency-Key-Mechanismus.
### Native-Features (M168, Spec Block C)
- **Biometrie / Face-ID / Touch-ID (C.2)** — kein Biometric-Plugin installiert (kein `capacitor-biometric-auth` o.ä.); kein OS-Keychain-Secret-Adapter; kein Setup-/Login-Flow; kein 2FA-Interaktions-Wiring.
- **Kamera (C.3)** — `@capacitor/camera` **nicht installiert**; kein Foto-Capture/Galerie-Flow, kein lokales Resize (max 2400×2400, JPEG-85), keine Offline-Foto→Queue-Anbindung.
- **Push-Pre-Prompt-UI (C.1)** — Backend-Flow vorhanden, aber die User-Pre-Prompt-Erklärung VOR System-Dialog (Apple-Compliance) fehlt im Web-Code.
- **Push-Empfangs-Handling** — Token-Registrierung vorhanden, aber Vordergrund-In-App-Banner + Klick→Deeplink-Routing fehlen.
### Routing / Deeplinks (M168/M169, Spec Block I)
- **Universal Links (iOS) / App Links (Android)** — `apple-app-site-association` + `assetlinks.json` Dateien fehlen; nur Custom-Scheme (`toolctrl://`) im AndroidManifest vorhanden.
- **Deeplink-Routing-Logik** — Auth-Status-Check, Deeplink-Park-bei-Login, Tenant-Switch-Prompt, Permission-Mismatch-Fallback (Spec I.3) fehlen.
- **Native Tab-Bar (M169, Spec I.5)** — Datenmodell (`MobileRegistryItem`) vorhanden, aber kein Tab-Bar-Rendering, keine UI-Modus-Logik (Baustelle/Büro, Default-Tabs pro Modus), kein persistierter UI-Modus pro Gerät.
- **Mobile-First-Routes** (M169) — neue Routen `/{tenant}/settings/security/biometric/`, `/settings/mobile/`, `/settings/mobile/storage/`, `/settings/mobile/queue/` fehlen komplett.
### Apple/Google-Compliance (M171, Spec Block F + K)
- **Pricing-UI-Hide-Flag** (`IS_MOBILE_APP=true` / `PRICING_UI=false`) — nicht vorhanden; keine Verdrahtung in M28-Subscription-UI.
- **Privacy-Manifest** (`PrivacyInfo.xcprivacy`) — fehlt; kein Master-Listen-generierter Build-Step; Android Data-Safety-Form ebenfalls.
- **Reviewer-Demo-Account** (`apple-review`-Tenant) — fehlt; gehört zu M37-Plattform-Admin-Pflege.
- **Force-Update / Web-Bundle-Version-Check** (Spec B.3/J) — kein `/api/v1/mobile/version-check`-Endpoint, kein `min_supported_app_version`-Server-State, kein Force-Update-Modal, kein Web-Bundle-Hot-Update mit Atomic-Swap. (Vorhandener `version-check.ts` ist Plugin-Runtime-intern, nicht mobile.)
- **Submission-Playbook + Reject-Recovery** (Spec K) — Doku fehlt (Operator-Runbook `capacitor.md` ist Build-fokussiert, nicht Submission-Strategie).
- **SIWA-Backup-Implementation** (Spec F.2) — nicht vorbereitet.
### Account-Löschung in App (M171, Spec Block G — Verweis M35)
- Lokal-Cleanup bei App-Löschung (IndexedDB leeren, Keychain entfernen, Push-Token revoke) — Push-Revoke-Endpoint vorhanden, IndexedDB+Keychain-Cleanup hängt an noch zu bauenden Offline/Biometrie-Schichten.
### Native-Build-Pipeline (M167, Spec B.3)
- CI-Tag `mobile-vX.Y.Z` → Multi-Pipeline (Web-Build → iOS-TestFlight + Android-Play) fehlt; nur `test:mobile`-Unit-Gate vorhanden. Echte Builds/Signing sind laut Boilerplate-Doku bewusst Operator-Tasks.
### Querschnitt-Wiring (HiveGrid-spezifisch)
- Klartext-Strings (Spec L) als i18n-Keys (M002/M003), Audit-Einträge für Mobile-Aktionen (Biometrie-Setup, Account-Löschung, Konflikt-Resolution — Spec O AV#6), Feature-Flag-Schaltbarkeit (M006), Permission-Snapshot-Cache offline (Spec H.2/M.4) — alles neu zu verdrahten.
---
## Empfohlenes Vorgehen
**Phase 1 — Fundament aus Boilerplate übernehmen (schnell, hoher Hebel):**
1. **`apps/mobile`-Workspace klonen** als HiveGrid-Mobile-App-Vorlage; App-ID (`de.hivegrid.app`), Name, Bundle-IDs, Custom-Scheme (`hivegrid://`) und alle Permission-Strings/Klartexte umstellen. (M167)
2. **Capacitor-Config + Live-Reload + CI-`test:mobile`-Gate** 1:1 übernehmen. (M167)
3. **Push-Pipeline übernehmen:** `devices-routes.ts` + `device-tokens.server.ts` + `DeviceToken`-Modell + Worker `push-notification.ts` — auf HiveGrid-Auth (Self-Scope), Tenant-pro-Token-Constraint und EU-Stack (Novu/LP-13 prüfen) anpassen. Verdrahtung gehört primär zu M22, M36 konsumiert. (M168 C.1)
4. **Sentry-Mobile + Auth-Rehydrate** übernehmen (`sentry.ts`, `auth.ts`-Adapter-Pattern). (M167)
**Phase 2 — Native-Features ergänzen (neu, plugin-getrieben):**
5. **`@capacitor/camera` installieren** + Foto-Flow + lokales Resize; Anbindung an M52-Foto-Upload. (M168 C.3)
6. **Biometric-Plugin + OS-Keychain-Secret-Adapter** (ersetzt/ergänzt den unverschlüsselten Preferences-Adapter); Setup-/Login-Flow mit 2FA-Pflicht (M22). (M168 C.2)
7. **Universal-Links/App-Links:** AASA + `assetlinks.json` in `apps/web/public/.well-known/`, iOS-Entitlement + Android-Intent-Filter, Deeplink-Routing-Logik. (M168/M169 Block I)
**Phase 3 — Offline-Modus neu bauen (größter Aufwand, Phase-1-Pflicht):**
8. **`@capacitor/network` + IndexedDB (Dexie.js)** einführen; Read-Cache-Stores (Spec A.4) + Pre-Cache-beim-Login.
9. **OfflineSyncQueue** (client-seitig) + Sync-Engine mit Idempotency-Key (M007 wiederverwenden) + Backoff + Konflikt-Erkennung + LWW-Resolution-UI.
10. **Service-Worker erweitern** (vorhandene `sw.js`/`registerServiceWorker.ts` als Basis → Workbox-Strategie + Offline-Fallback). (M170 gesamt)
**Phase 4 — Compliance + Mobile-UI:**
11. **Native Tab-Bar** auf vorhandenem `MobileRegistryItem`/`createMobileRegistry` aufsetzen; UI-Modus-Logik (Baustelle/Büro) + Mobile-First-Routes + neue Settings-Routen. (M169)
12. **Pricing-Hide-Build-Flag** (`IS_MOBILE_APP`), Verdrahtung in M28-UI; Privacy-Manifest-Build-Step (Master-Liste M35/M37); Force-Update + `version-check`-Endpoint; Demo-Account (M37); Submission-Playbook-Doku. (M171)
**Reihenfolge-Logik:** Erst das geschenkte Boilerplate-Fundament (Schritte 1-4) übernehmen — das eliminiert das Capacitor-/Push-Risiko sofort. Danach die echten Neubauten (Offline > Biometrie/Kamera > Compliance), bei denen die Boilerplate nur Vorlagen/Querschnitt liefert.
@@ -0,0 +1,149 @@
# Boilerplate-Mapping: M37 — Plattform-Admin
**Modul-ID:** M37 (Detail-Spec) / Milestones **M034–M041** (Block 1, Pflichtenheft 37.x)
**Name:** Plattform-Admin (`admin.hivegrid.de`)
**Reuse-Level:** **medium**
> Verifiziert direkt gegen `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (Schema, Routes, Services). Inventur-Dateien als Ausgangspunkt, alle Aussagen mit eigenem Grep/Read gegengeprueft.
---
## Kernbefund (zuerst lesen)
Die Boilerplate enthaelt eine **substanzielle, fertige Admin-Welt** (eigene Admin-Subdomain-Routing-Schicht, Admin-Sidebar, Admin-Login inkl. SSO + MFA-Step-up, RBAC, tamper-evidenter Audit-Trail, Impersonation-Infrastruktur, Lead-Inbox, Support-Tickets, Subscription-/Metrics-/Dashboard-Routen). Damit sind **Themenblöcke E, F, G(lese), H, I, L, M, O** zu grossen Teilen aus Vorhandenem ableitbar.
**ABER: Die zentrale Architektur-Prämisse von M37 wird vom Boilerplate-Modell verletzt.** Spec Block A/B verlangt eine **eigene, parallele User-Klasse `AdminUser`** mit eigenem `password_hash`, `totp_secret`, eigener `AdminSession`, eigener `AdminRole/AdminPermission`-RBAC und eigener `AdminAuditLog`-Tabelle. Im Boilerplate ist `AdminUser` jedoch **kein eigenständiges Identity-Modell**, sondern eine 1:1-Erweiterung von `User`:
```prisma
// prisma/schema/accounts.prisma:112
model AdminUser {
userId String @id @unique
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
ssoProvider String? ssoSubjectId String? ssoGroups String[] lastSsoLoginAt DateTime?
}
```
D.h. Admin-Auth, Passwort, 2FA und Rollen laufen heute **über dasselbe `User`-/`UserRole`-/`Permission`-Fundament wie Tenant-User** (Admin-Status = `User` hat `AdminUser`-Zeile). Das ist exakt der „Generalschlüssel zwischen den Welten", den Spec Block A.2/A.3 und Milestone M034 (37.1) verbieten.
**Konsequenz für die Planung:** Vor jeder Übernahme muss eine **Architektur-Entscheidung** fallen:
- **(a) Spec-treu (empfohlen lt. Spec):** neue, vollständig getrennte `AdminUser`-Identität + `AdminSession` + `AdminRole/AdminPermission/AdminAuditLog` neu bauen. Boilerplate-Admin-Auth dient dann nur als **Vorlage** (Login-Form, MFA-Flow, Rate-Limit, Session-Cookie-Policy), nicht 1:1.
- **(b) Boilerplate-treu:** das bestehende `User`+`AdminUser`-Extension-Modell behalten und Spec Block A/B abschwächen (Change-Request, da es Pflichtenheft 37.1 widerspricht).
Dieser Punkt ist der Haupt-Grund, warum Reuse **medium** und nicht **high** ist.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `apps/web/app/routes/admin.tsx` + `apps/web/app/routes/admin/` (Tree) | Komplette Admin-Route-Welt unter eigener Surface (accounts, users, subscriptions, roles-and-permissions, audit-trails, metrics, feature-flags, marketing-leads, help-desk, settings, events) inkl. host-aware Subdomain-Routing-Tests (`admin.host-aware.test.ts`) | **als-vorlage** (Routen-Skelett + Subdomain-Trennung direkt; Inhalte HiveGrid-fachlich füllen) |
| `apps/web/app/application/sidebar/AdminSidebar.tsx` + `SidebarItem.ts` + `SidebarGroupDto.ts` | Statische, permission-getaggte Admin-Sidebar in Segmenten (Manage/Build/Market/Settings), `data-ui-id`-IDs, `adminPath()`-host-aware | **anpassen** (Sidebar-Hauptpunkte aus Block E übernehmen; HiveGrid nutzt eigene `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` — INTEGRATION-CONTRACTS §2) |
| `packages/url/src/canonical.ts` (`adminPath`/`adminUrl`) + `packages/config/src/routing.ts` + `packages/config/src/session-cookie.ts` | Host-aware Admin-URL-Builder, Domain-Routing, **domain-/pfad-gelockte Session-Cookie-Policy** | **1:1** (Cookie-Trennung `admin.` vs `app.` = Block A.3, M034) |
| `apps/web/app/routes/auth.admin.login.tsx`, `auth.admin.callback.tsx`, `auth.admin.logout.tsx` | Eigener Admin-Login-/Logout-Flow (heute via Authentik-OIDC) | **als-vorlage** (Flow-Gerüst; HiveGrid braucht Email+Passwort+TOTP statt OIDC — Block C; Magic-Link für Admin verbieten) |
| `apps/web/app/services/auth/admin-mfa-gate.server.ts` (`requireAdminMfaForAction`, `SENSITIVE_ADMIN_ACTIONS`) + `apps/web/app/utils/auth/mfa/*` (`enforcement.server`, `step-up.server`) | MFA-Step-up-Gate für sensible Admin-Aktionen — Taxonomie enthält bereits `impersonation.start`, `tenant.delete`, `permission.grant`, `audit.export`, `data.export` | **anpassen** (deckt Block C 2FA-Pflicht + Block Q Reason-Gates fachlich; auf neue `AdminUser`-Identität umhängen) |
| `apps/api/src/auth/login-rate-limit.ts` (`createFixedWindowRateLimiter`) + `packages/shared-store` (`createFixedWindow/SlidingWindowRateLimiter`) | Login-Rate-Limit (IP + Account-Fingerprint, Redis) | **anpassen** (Spec C: 5/15min Lock, Captcha ab 3., 10/24h → `locked`) |
| `apps/web/app/utils/session.server.ts` (Impersonation-State) + `apps/web/app/utils/session.impersonation.test.ts` | Impersonation-Session-State (`impersonatingFromUserId`/`StartedAt`, Validierung) | **anpassen** (Block G Impersonate; Spec: max 30 Min Cap + Reason-Pflicht ergänzen) |
| `apps/web/app/components/impersonation-banner.tsx` + `apps/web/app/root.tsx` (Wiring) + `root.impersonation-banner.test.tsx` | Rotes Klartext-Impersonation-Banner in der App-Shell (i18n, „Acting as … from …", Exit) | **anpassen** (Block G/M037: Banner-Text „Plattform-Support … Ticket #123" + Ticket-/Reason-Bezug) |
| `prisma/schema/accounts.prisma:266` `ImpersonationAudit` + `packages/db/src/impersonation-audit.server.ts` | Impersonation-Audit-Tabelle (`actorUserId`/`targetUserId`/`tenantId`/`action`/`reason`/`requestPath`/`metadata`, SetNull) | **1:1** (deckt M037 Audit-Spur inkl. Reason) |
| `prisma/schema/core.prisma:55` `AuditEvent` + `packages/db/src/audit-events.server.ts` + `packages/db/src/audit-hash.ts` + `packages/foundation/src/audit.ts` (`auditEvent`, `withAuditMiddleware`) | Tamper-evidenter, cross-tenant-fähiger Audit-Trail (Hash-Kette, `tenantId?`, `actorType`, `action`, `targetType/Id`, `metadata`, reiche Indizes) | **1:1 als AdminAuditLog-Ersatz** — `tenantId=null` = plattform-/operator-weit deckt Block B `AdminAuditLog` fachlich vollständig ab; HiveGrid muss **kein** neues Audit-Schema bauen, nur `action_type`/`target_kind`-Vokabular definieren |
| `apps/web/app/routes/admin/audit-trails.tsx` + `audit-export.tsx`/`.helpers.server.ts` + `packages/db/src/logs.server.ts` (`getAdminAuditLogList`, `serializeAdminAuditLogsCsv`) | Cross-Tenant-Audit-Liste mit Filter (Akteur/Action/Zeitraum) + CSV-Export, permission-gated (`admin.auditTrails.view`) | **anpassen** (Block L fast vollständig; Volltext-Suche in `summary_text` + JSON-Export ergänzen) |
| `packages/exports/src/audit-pdf.ts` (`serializeAuditEventsToPdf`) | Compliance-Audit-PDF (SOC2/HIPAA/GDPR-Evidence) | **1:1** (Block L Compliance-Export) |
| `prisma/schema/permissions.prisma` (`Role`/`Permission`/`RolePermission`/`UserRole`/`Group`) + `apps/web/app/routes/admin/accounts/roles-and-permissions.tsx` + `components/core/roles/*` + `packages/db/src/permissions-seed.server.ts` | Editierbares RBAC mit UI-Rollen-Editor + Permission-Seed | **als-vorlage** (Block D Bundle-Modell; bei Architektur (a) als `AdminRole/AdminPermission` parallel neu, Struktur 1:1 übertragbar) |
| `apps/web/app/utils/services/adminDashboardService.ts` + `packages/db/src/kpi.server.ts` (`getAdminTenantKpiCounts`, `getAdminActiveUserKpiCounts`) + `apps/web/app/utils/services/.server/subscriptionService.ts` (`getMrr`) | Admin-Dashboard-KPIs: Tenant-Count + Trend, MRR, aktive User | **anpassen** (Block F: MRR/ARPU/Churn/Expansion + Health-Kacheln + Sales-Pipeline ergänzen) |
| `apps/web/app/routes/admin/accounts/index.tsx` + `$id.tsx` (Tenant) + `users.tsx`/`users.test.tsx` + `blacklist.tsx` + `__ip-addresses/` | Tenant-Liste/-Detail + User-Verwaltung + IP-Logs + Blacklist | **anpassen** (Block G/H: Status-Wechsel mit Reason, Notes, Trial-Verlängerung, Bulk-Actions ergänzen) |
| `apps/web/app/routes/admin/accounts/subscriptions.tsx` + `subscriptions/$id.tsx` + `subscriptions-revenue.tsx` + `prisma/schema/subscriptions.prisma` (14 Modelle) + `apps/web/app/utils/stripe.server.ts` + `packages/entitlements` | Vollständiger Stripe-Billing-Stack + Admin-Subscription-Routen + MRR | **anpassen** (Block I: manueller Override, Force-Sync, Refund, Sonderpreis-Vermerk ergänzen) |
| `prisma/schema/featureFlags.prisma` (3 Modelle, append-only Audit) + `packages/feature-flags` (Engine v2, Targeting, Cache) + `apps/web/app/routes/admin/feature-flags.tsx` | Feature-Flag-Engine + Admin-Verwaltung | **1:1** (Block J = Verweis auf Modul 32; Admin-Routes liegen bereits unter `admin/feature-flags`) |
| `prisma/schema/marketingLeads.prisma` (`Lead`/`LeadEvent`/`TenantAcquisition`/`MarketingIntegration`, **operator-scoped, kein tenantId**) + `apps/web/app/routes/admin/marketing-leads/index.tsx`+`$id.tsx` + `apps/web/app/utils/leads/*` + `packages/marketing-outbound` | Operator-scoped Lead-Inbox + Detail + Status-Pipeline + First-Touch-Attribution + Convert-to-Tenant (`convertedToTenantId`) + Activity-Timeline (`LeadEvent`) + Outbound-Adapter | **anpassen** (Block M: deckt Lead-Inbox/Detail/Promote-to-Tenant/Activity-Stream sehr nah; fehlt: `AdminDeal`-Pipeline/Kanban, `assigned_to`, `industry/company_size`-Enums) |
| `prisma/schema/helpDesk.prisma` (`Feedback`, `SupportTicket` mit `source`/`status`/`priority`/`inboundMessageId`-Dedup) + `apps/web/app/modules/helpDesk/*` + `apps/web/app/routes/admin/help-desk.tsx` + `components/FeedbackTable.tsx` | Support-Ticket-Aufnahme inkl. Inbound-Email-Dedup + PII-Redaction + Admin-Inbox | **anpassen** (Block O: Konversation/Messages, Tags[], Assignee, Reply-Templates, Internal-Notes fehlen → erweitern) |
| `apps/web/app/routes/admin/metrics/` (`summary.tsx`, `logs.tsx`, `settings.tsx`) + `packages/metrics` (prom-client, AI-Cost-Counter) + `apps/worker/src/admin-server.ts`/`health-server.ts` + `infra/grafana` (queue-health, business-kpi Dashboards) | Metrics-Admin-Routen + Worker-Status/Health-Server + Grafana-Dashboards | **anpassen** (Block K Health-Dashboard: Service-Status + Error-Rate als Vorlage; BullMQ-Queue-Steuerung-UI + KWP-Sync neu) |
| `prisma/schema/queue.prisma` (`QueueFailedJob` BullMQ-DLQ, `ExportJob`) + `apps/worker/src/jobs/queue-failed-jobs*` + `packages/db/src/queue-failed-jobs.server.ts` | Failed-Job-Tracking (DLQ) | **anpassen** (Block K Worker-Queues: Liste/Retry/Pause-UI darauf aufbauen) |
| `packages/foundation/src/permissions.ts` (`withTenantScope`/`withPermission`/`requirePermission`) + `apps/web/app/utils/helpers/.server/PermissionsService.ts` (`verifyUserHasPermission`) | Permission-Gating + 404-statt-403 (Existenz-Versteckung) | **1:1** (Querschnitt; Block D-Durchsetzung + AGENTS DoD C.17) |
| `packages/foundation/src/notifications.ts` (`notify`/`bundleNotifications`) + `prisma/schema/notifications.prisma` + `prisma/schema/email.prisma` (`Campaign`/`OutboundEmail`) | Notifications + Outbound-Email/Kampagnen (für Bulk-Email an Tenant-Admins, AVV-Re-Akzeptanz-Mails) | **1:1 / anpassen** (Block G Bulk-Email, Block P AVV-Notification) |
| `packages/exports` (CSV/JSON/XLSX) + `apps/worker/src/jobs/{export,dsgvo-export}.ts` + `prisma/schema/queue.prisma` `ExportJob` | DSGVO-/Daten-Export-Pipeline (Tenant-Daten-Export-Anstoss, Block G) | **1:1** |
| `packages/foundation/src/errors.ts` (`CatalogError`) + `packages/view-models` (`VMState`, `ActionCallbacks`, `RegistryGate`) + `packages/i18n` | Klartext-Diagnostik, View-Model-Vertrag, i18n | **1:1** (Querschnitt; Block Q Klartext-Hinweise, AGENTS DoD A/E) |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
| Modell | Pfad | M37-Bezug |
|---|---|---|
| `AdminUser` | `prisma/schema/accounts.prisma:112` | **nur Teilabdeckung** — 1:1-Extension von `User` (`userId @id` + SSO-Felder). Kein eigenes `passwordHash`/`totpSecret`/`status`/`disabledReason`. Block B `AdminUser` braucht NEUES Modell oder Spec-Abschwächung. |
| `User` | `prisma/schema/accounts.prisma:1` | Auth-Fundament: `passwordHash`, `totpSecretEncrypted`, `totpEnabledAt`, `mfaRecoveryCodeHashes`, DSGVO-Flags. Vorlage für AdminUser-Auth-Felder. |
| `ImpersonationAudit` | `prisma/schema/accounts.prisma:266` | **deckt M037-Audit** (actor/target/tenant/action/reason/requestPath/metadata). |
| `AuditEvent` | `prisma/schema/core.prisma:55` | **deckt `AdminAuditLog` fachlich** (Hash-Kette, `tenantId?`, actor/target/action/metadata, Indizes). Kein neues Schema nötig. |
| `Role`/`Permission`/`RolePermission`/`UserRole`/`Group`/`GroupUser` | `prisma/schema/permissions.prisma:1-78` | RBAC-Fundament. Vorlage für `AdminRole/AdminPermission` (Block D). |
| `Tenant`, `TenantUser`, `TenantUserInvitation` | `prisma/schema/accounts.prisma:129/286/298` | Tenant-Verwaltung Block G/H (Status via `active`, Membership, Invitations). |
| `SubscriptionProduct…TenantSubscription`, `TenantFeatureOverride`, `Credit` (14) | `prisma/schema/subscriptions.prisma` | Subscription-Management Block I (Stripe-IDs, Plan, Override). |
| `FeatureFlag`/`FeatureFlagFilter`/`FeatureFlagAudit` | `prisma/schema/featureFlags.prisma` | Block J (Modul 32). |
| `Lead`/`LeadEvent`/`TenantAcquisition`/`MarketingIntegration` | `prisma/schema/marketingLeads.prisma:14-143` | Block M Lead-Inbox/Activity/Convert (operator-scoped, kein tenantId). **Kein `AdminDeal`.** |
| `Feedback`/`SupportTicket` | `prisma/schema/helpDesk.prisma:1/12` | Block O (Aufnahme + Inbound-Email-Dedup). **Keine Ticket-Messages/Konversation.** |
| `QueueFailedJob`/`ExportJob` | `prisma/schema/queue.prisma` | Block K Worker-DLQ + Block G Export. |
| `AppConfiguration`, `Log`, `MetricLog`, `Event` | `prisma/schema/core.prisma` | Health/Config-Querschnitt Block K. |
| `app.prisma` (leerer Platzhalter) | `prisma/schema/app.prisma` | **Vorgesehener Ort** für neue HiveGrid-Admin-Modelle (`AdminRole`, `AdminDeal`, `AdminTenantNote`, `Subprocessor`, `AvvVersion` …). |
---
## Lücken / komplett neu zu bauen
1. **Eigenständige `AdminUser`-Identität (Block A/B, M034)** — separate Tabelle mit `email`/`passwordHash`/`totpSecret`/`totpEnabled`/`status`/`disabledReason`/`createdByAdminUserId` **getrennt von `User`**. Heute existiert nur die `User`-Extension. **Architektur-Entscheidung blockierend** (siehe Kernbefund).
2. **`AdminSession` (Block C, M034)** — server-side Postgres-Sessions mit 8h-Cap, 1h-Inaktivität, **IP-Bindung (Re-Auth bei IP-Wechsel)**, Revoke-Liste. Boilerplate nutzt Cookie-Sessions (`session.server.ts`), kein DB-Session-Modell mit IP-Bindung → neu (Vorlage: `packages/shared-store` `createSessionStore`).
3. **`AdminRole`/`AdminPermission`/`AdminRolePermission`/`AdminUserRole` (Block D)** — eigene parallele RBAC mit Bundle-Stufen (`none/read/write/admin`, `viewer/operator/owner`). Struktur aus `permissions.prisma` ableitbar, aber neue Tabellen + Default-Rollen-Seed (`super_admin/support/sales/engineering/viewer`) + Self-Permission-Schutz (letzter super_admin).
4. **`AdminDeal` + Deal-Pipeline/Kanban (Block M)** — kein Deal-Modell, kein Kanban-View, kein Drag&Drop. `expected_arr_eur`, `seats`, `stage`. Komplett neu (Lead-Teil ist abgedeckt).
5. **`AdminTenantNote` (Block B/G)** — pro-Tenant Markdown-Notizen mit Kategorie/Pin/Archiv. Kein Modell vorhanden. Neu.
6. **Subprozessoren- + AVV-Verwaltung (Block P, M041)** — `Subprocessor`, `AvvVersion` (+ Re-Akzeptanz-Tracking) existieren **nicht** im Schema. Komplett neu (Querschnitt Modul 35).
7. **KWP-Sync-Health (Block K, M041)** — kein KWP/Heartbeat-Modell/Code in der Boilerplate (HiveGrid-spezifische Integration, M089-M095). Komplett neu.
8. **Support-Ticket-Konversation (Block O)** — `AdminSupportTicketMessage` (Reply-Thread, Internal-Notes, Attachments, Reaktions-Templates) fehlt; nur Single-Message-`SupportTicket` vorhanden. Erweitern.
9. **Worker-Queue-Steuerungs-UI (Block K)** — Retry/Pause/Resume/Remove pro BullMQ-Queue: Worker-Runtime + DLQ-Modell existieren, aber **keine Admin-UI/Steuerungs-API**. Neu (auf `apps/worker/admin-server.ts` aufsetzen).
10. **Manuelle Tenant-Anlage mit Sonder-Konditionen (Block N, M036)** — Slug-Live-Validation, Initial-Admin-Anlage, Trial-Dauer, Demo-Daten-Provisionierung, Reason-Pflicht. Tenant-Anlage existiert im Onboarding-/Registrierungs-Pfad, aber kein Admin-„Tenant-anlegen-im-Auftrag"-Flow. Neu (Teile aus Registration/Onboarding wiederverwenden).
11. **Dashboard-Erweiterung (Block F)** — Churn/Expansion-MRR, ARPU, System-Health-Kacheln, Sales-Pipeline-Volumen, Support-Kennzahlen, Redis-Cache (TTL 5 Min) + Hourly-Aggregat-Job. Basis (Tenant/MRR/Active-Users) vorhanden, Rest neu.
12. **`packages/ui-hivegrid` Admin-Shell + Subframe-Adapter** — der HiveGrid-eigene UI-Layer (`ui-hivegrid`, `ui-subframe`-Adapter) existiert in der Boilerplate **nicht** (nur Stubs `ui-app`/`ui-subframe`). Admin-Sidebar muss in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` registriert werden (INTEGRATION-CONTRACTS §2). Querschnitt für alle M034-M041.
13. **Impersonate 30-Min-Hard-Cap + Reason-Pflicht-Gate** — State + Banner vorhanden, aber Spec verlangt harte 30-Min-Session-Begrenzung und Reason-Pflicht-Block (Block Q). Erweitern.
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Architektur-Entscheidung (blockierend, vor M034):**
- Klären: getrennte `AdminUser`-Identität (Spec-treu, empfohlen) vs. Boilerplate-`User`-Extension (Change-Request gegen Pflichtenheft 37.1). Bis dahin keine Auth-Implementierung beginnen.
**M034 (Auth) — zuerst aus BP übernehmen, Rest neu:**
1. Übernehmen (als-vorlage): `auth.admin.login/logout`-Flow, `admin-mfa-gate.server.ts` (Step-up-Gate inkl. fertiger Sensitive-Action-Taxonomie), `login-rate-limit.ts`, `session-cookie.ts` (Domain-Lock), `adminPath`-Routing.
2. Neu: `AdminUser`/`AdminSession`-Modelle (in `app.prisma`), Email+Passwort+TOTP-Pflicht (Magic-Link verbieten), IP-Bindung, 8h/1h-Timeouts, 5/15 + 10/24h-Lockout, Bootstrap-Seed-Script.
**M039 (Konten & Rollen) — RBAC:**
3. `AdminRole/AdminPermission/AdminUserRole` als parallele RBAC (Struktur aus `permissions.prisma`, UI-Editor aus `roles-and-permissions.tsx`), Bundle-Stufen + Default-Rollen-Seed + Self-Permission-Schutz.
**M035 (Dashboard) + M036 (Mandanten):**
4. Dashboard: `adminDashboardService` + `kpi.server` als Basis, Health-/Pipeline-/Support-Kacheln + Redis-Cache + Hourly-Job ergänzen.
5. Mandanten: `admin/accounts` Liste/Detail erweitern (Status-Wechsel mit Reason → `AuditEvent`/`ImpersonationAudit`, `AdminTenantNote` neu, Trial-Verlängerung, Bulk-Email via `notify`/Campaign, Daten-Export via `packages/exports`). Manuelle Tenant-Anlage (Block N) neu.
**M037 (Stellvertreter-Anmeldung):**
6. Vorhandene Impersonation (Session-State + Banner + `ImpersonationAudit`) übernehmen; 30-Min-Hard-Cap + Reason-Pflicht-Gate (`requireAdminMfaForAction("impersonation.start")` ist schon da) + Banner-Text mit Ticket-Bezug ergänzen.
**M038 (Mitarbeiter-Verwaltung):**
7. `admin/accounts/users` als Vorlage; 2FA-Reset, Session-Revoke, Memberships, Deaktivieren auf neue Permission-Bundles umstellen; AdminUser-Verwaltung (Anlegen via Setup-Mail) neu.
**M040 (Lead-Pipeline):**
8. `Lead`/`LeadEvent`/`marketing-leads`-Routen + Convert-to-Tenant fast 1:1 übernehmen; `AdminDeal`-Modell + Kanban-Pipeline-UI + `assigned_to`/`industry`/`company_size` neu.
**M041 (Health/Audit/Support/Legal):**
9. Audit: `audit-trails.tsx` + `logs.server` + `audit-pdf` übernehmen (Volltext-Suche + JSON-Export ergänzen) — `AuditEvent` deckt `AdminAuditLog`.
10. Subscriptions-Admin: `subscriptions/$id` + Stripe erweitern (Override/Force-Sync/Refund/Diff-View).
11. Support: `helpDesk` + `SupportTicket` übernehmen; `AdminSupportTicketMessage`-Thread + Templates + Internal-Notes neu.
12. Health: `metrics`-Routen + Worker-Admin/Health-Server + Grafana als Basis; BullMQ-Queue-Steuerungs-UI (auf `QueueFailedJob`) + KWP-Sync (HiveGrid-spezifisch) neu.
13. Legal: `Subprocessor`/`AvvVersion`-Modelle + Re-Akzeptanz-Trigger (via `notify`/Campaign) komplett neu (Modul 35).
**Querschnitt (durchgängig):** `withTenantScope`/`withPermission`, `auditEvent`, `notify`, `CatalogError`, `VMState`, i18n-Keys + Sidebar-Registrierung in `packages/ui-hivegrid` (das zuerst angelegt werden muss) — gemäss AGENTS.md DoD + INTEGRATION-CONTRACTS.
---
## Realitäts-Vorbehalte (keine Erfindungen)
- `packages/ui-hivegrid` und ein gebauter `ui-subframe`-Adapter **existieren nicht** in der Boilerplate (nur Stubs). Die in AGENTS.md/INTEGRATION-CONTRACTS referenzierten Pfade sind HiveGrid-Soll, nicht Boilerplate-Ist.
- Boilerplate-`AdminUser` ist **kein** parallel-Identity-Modell — das ist der zentrale Spec-Konflikt.
- **Kein** `AdminRole`/`AdminPermission`/`AdminSession`/`AdminAuditLog`/`AdminLead`/`AdminDeal`/`AdminLeadActivity`/`AdminSupportTicket`/`AdminTenantNote`/`Subprocessor`/`AvvVersion`-Modell existiert (verifiziert via Grep über `prisma/schema/`).
- **Kein** KWP-/Heartbeat-Code existiert (HiveGrid-spezifisch).
- `SupportTicket` ist single-message (kein Konversations-Thread).
- Admin-Login läuft heute via Authentik-OIDC, **nicht** Email+Passwort+TOTP wie Spec C verlangt.
@@ -0,0 +1,146 @@
# Boilerplate-Mapping: M38 — Help-Center (öffentlich)
| | |
|---|---|
| **Modul-ID** | M38 |
| **Name** | Help-Center (öffentlich) |
| **Milestones** | M172 (Markdown-Artikel-Mgmt / Git-PRs), M173 (Routes + Suche + SEO + Kontextuelle Hilfe) |
| **Block** | Block 7 |
| **LPs** | LP-9, LP-10, LP-12, LP-13 |
| **Reuse-Level** | **medium** |
## TL;DR — Verdict
Die Boilerplate enthält ein **vollständiges, produktionsreifes Help-Center / Knowledge-Base-System** (SaaSRock-Stil) unter
`apps/web/app/modules/knowledgeBase/` mit öffentlichen Routen `/help/...`, Kategorien, Artikeln, Suche (Meilisearch + SQL-Fallback),
anonymem Daumen-hoch/runter-Feedback, View-Tracking, SEO-Metatags (OG/Twitter/Canonical), Markdown-Rendering mit Sanitizer,
verwandten Artikeln, Featured-Artikeln **und** kompletter Admin-Editor-UI — sogar mit RAG-Service für KI-Suche.
**Der entscheidende Bruch:** Die Boilerplate ist **DB-getrieben** (Prisma `KnowledgeBase*`-Modelle + Editor-UI in `admin/knowledge-base`).
Die HiveGrid-M38-**Phase-1**-Spec verlangt aber explizit das **Gegenteil**: **file-basierte** Markdown-Artikel im Repo, Pflege via
**Git-PRs**, **kein** Editor-UI, mit **Build-Time-Index + Sitemap + Frontmatter-/Verlinkungs-Validierung als Build-Step**
(Spec Block A.1, A.4; M172-Erfolgskriterium). Dieser file-/build-basierte Daten- und Validierungslayer **existiert in der Boilerplate nicht**.
Konsequenz: Die **UI-, Routing-, Such-, SEO- und Feedback-Schicht** ist als Vorlage exzellent (high reuse), aber der **Daten-Layer
muss komplett ersetzt** werden (DB → File/Frontmatter + Build-Index). Was die Boilerplate liefert, entspricht eher der HiveGrid-**Phase-2**
(DB-getriebene Pflege durch Plattform-Admin, Spec Block I). Daher gesamt **medium**.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `apps/web/app/routes/help/$slug.($lang).tsx` | Public Help-Home-Route (Kategorien + Suche), Sprach-Segment optional, Meta-Tags aus Loader | als-vorlage (URL-Schema von `/help/$slug/($lang)` → HiveGrid `/help/$lang/$category/$slug` umstellen) |
| `apps/web/app/routes/help/$slug.($lang).categories.$category.tsx` | Public Kategorie-Seite | als-vorlage |
| `apps/web/app/routes/help/$slug.($lang).articles.$article.tsx` | Public Artikel-Detail + `action` (Feedback) | als-vorlage |
| `apps/web/app/routes/help/help-routes.test.tsx` | Route-Smoke-/Render-Tests der Public-Help-Routen | als-vorlage (Test-Pattern für DoD-Smoke-Tests) |
| `apps/web/app/modules/knowledgeBase/routes/api/KbRoutes.Index.Api.tsx` | Loader-VM-Builder: `metatags/kb/search/categories/featured/isAdmin`; 404 bei unsupported lang | als-vorlage (Loader→VM-Konvention 1:1, Datenquelle tauschen) |
| `apps/web/app/modules/knowledgeBase/routes/api/KbRoutes.Category.Api.tsx` | Kategorie-Loader-VM | als-vorlage |
| `apps/web/app/modules/knowledgeBase/routes/api/KbRoutes.Article.Api.tsx` | Artikel-Loader-VM + anonymes `voteArticle` (thumbsUp/Down via `userAnalyticsId`, ohne PII) | als-vorlage (Feedback-Mechanik 1:1, Artikel-Quelle tauschen) |
| `apps/web/app/modules/knowledgeBase/routes/views/KbRoutes.{Index,Category,Article}.View.tsx` | Reine View-Komponenten (empfangen Loader-Data), Layer-getrennt | anpassen |
| `apps/web/app/modules/knowledgeBase/components/KbSearch.tsx` | Such-Eingabe mit `useDebounce` (500ms) + `q`-Query-Param + Ergebnis-Liste | anpassen (Spec verlangt 300ms-Debounce; Ranking Title>Desc>Keyword>Body ergänzen) |
| `apps/web/app/modules/knowledgeBase/components/KbHeader.tsx`, `KbFeaturedArticles.tsx`, `KbSkeletons.tsx` | Header, Featured-Artikel-Block, Loading-Skeletons | anpassen |
| `apps/web/app/modules/knowledgeBase/components/categories/Kb{Categories,CategoriesGrid,CategoriesList,Category,CategoriesTopArticles}.tsx` | Kategorien-Übersicht (Grid/List/„Top-Artikel“) | anpassen (deckt Spec Block C: Kategorie-Karten + „Beliebteste Artikel“) |
| `apps/web/app/modules/knowledgeBase/components/articles/Kb{Article,ArticleContent,Articles,ArticlesBySection}.tsx` | Artikel-Detail: Title/Description/Autor/Datum, Markdown-Body, verwandte Artikel, Daumen-Feedback | anpassen (deckt Spec Block D weitgehend; TOC fehlt — siehe Lücken) |
| `apps/web/app/modules/knowledgeBase/components/KbArticleContent.tsx` | `renderSanitizedMarkdown(content)` + `prose`-Styling + Related-Sidebar + Feedback-Buttons | anpassen |
| `apps/web/app/utils/html-sanitizer.ts` | `renderSanitizedMarkdown()` über `marked` (Renderer), Raw-HTML-Escaping, JS-URL-/rel-Hardening | 1:1 (sichere Markdown→HTML-Pipeline; Spec-Renderer-Frage „unified/remark“ damit faktisch schon gelöst) |
| `apps/web/app/modules/knowledgeBase/components/layouts/KbDocsLayout.tsx`, `KbDocsHeader.tsx` | „docs“-Layout-Variante (Sidebar-Navigation Kategorie→Artikel) | als-vorlage (passt zum Help-Layout; TOC-Spalte ergänzen) |
| `apps/web/app/components/ui/breadcrumbs/BreadcrumbSimple.tsx` (via `KbArticle.tsx`) | Breadcrumb Kategorie > Artikel | 1:1 (Spec Block C/D Breadcrumb) |
| `apps/web/app/modules/knowledgeBase/dtos/{KbArticleDto,KbCategoryDto,KbCategorySectionDto,KbNavLinkDto,KbSearchResultDto,KnowledgeBaseDto}.ts` | Vollständige DTO-/VM-Typen für KB/Kategorie/Artikel/Suche inkl. `metatags` | als-vorlage (Zielform für den neuen File-Index-Loader; Frontmatter→DTO mappen) |
| `apps/web/app/modules/knowledgeBase/service/KnowledgeBaseService.server.ts` | `kbToDto/categoryToDto/articleToDto` mit kompletten **SEO-Metatags** (title/description/OG/Twitter/Canonical), `search()`, `getFeaturedArticles()`, getypte Error-Codes → i18n-Keys | als-vorlage (Metatag-/DTO-Mapping 1:1 übernehmbar, DB-Reads durch File-Index-Reads ersetzen; nutzt `cachified` 24h-TTL — passt zu Spec „langer Cache-Header / SSG“) |
| `apps/web/app/modules/knowledgeBase/services/kbArticleSearch.server.ts` | Such-Service mit Meilisearch-Pfad + transparentem SQL-LIKE-Fallback, gleiche Rückgabeform | als-vorlage (Server-Side-Suche; für file-basiert: SQL-Pfad raus, FlexSearch-Index oder Postgres-FTS-Helper-Tabelle einsetzen) |
| `packages/search/src/{client,query,index-helper,sanitize}.ts` + `schemas/kb-articles.ts` | `@toolctrl/search` Meilisearch-Wrapper, tenant-scoped Query, Index-Schema `kbArticlesIndex`, Outbox-Publisher | anpassen (Spec bevorzugt Phase-1 client-side FlexSearch ODER Postgres-FTS; Meili ist „nice-to-have“ — als Server-Side-Option direkt verfügbar) |
| `apps/web/app/modules/knowledgeBase/services/kbArticleRag.server.ts` | RAG-Service für KB-Artikel (Embeddings-Suche) | als-vorlage (HiveGrid-**Phase-2** „KI-gestützte Artikel-Suche/RAG“, Spec Block I) |
| `packages/ai/src/embeddings/*` (`@toolctrl/ai/embeddings`) | Komplette Embeddings-/RAG-Pipeline (embed-and-upsert, retrieve, chunking, Outbox-Reindex) | als-vorlage (Phase-2 RAG) |
| `apps/web/app/modules/knowledgeBase/db/kbAnalytics.db.server.ts` | `createKnowledgeBaseView`, `voteArticle`, `getArticleStateByUserAnalyticsId` (anonym via `userAnalyticsId`) | als-vorlage (Spec: „helpful?“-Daumen anonym ohne PII; View-Counts = Phase-2) |
| `apps/web/app/utils/analyticsCookie.server.ts` (`getAnalyticsInfo`) | Anonyme Analytics-ID-Quelle für Feedback/Views ohne Login | anpassen (Spec verlangt anonym **ohne Cookies** — prüfen/anpassen) |
| `apps/web/app/components/ui/errors/ServerError.tsx` + Route-`ErrorBoundary` | Fehlerseiten-Pattern für Public-Routen | 1:1 |
| `apps/web/react-router.config.ts` + `apps/web/app/routes.ts` (Flat-Folder-Convention) | RR7-Routing-Setup inkl. „Plugin-Routen deaktivierbar“-Liste (`help/**` ist dort enthalten = Feature-Flag-fähig per Datei-Pattern) | 1:1 (Routing-Fundament; `help/**` aus `defaultDisabledPluginRouteFilePatterns` aktivierbar machen → Feature-Flag-Anforderung DoD erfüllt) |
| `packages/i18n/src/index.ts` (`@toolctrl/i18n`) + `apps/web/app/locale/*` | i18n-Setup (`defaultLocale="de"`, `supportedLocales`, SSR-Integration); Help-Center-Komponenten nutzen durchgängig `t(...)` | 1:1 (deckt LP-12 „alle UI-Strings aus Locale-Files, Phase 1 nur DE“) |
| `packages/view-models/src/index.ts` (`VMState`, `assertI18nLabel`, `ShellRegistries`) | View-Model-Statusmodell + i18n-Key-Zwang | 1:1 (Loader→VM-Konvention, DoD „Unit-Test VM-Builder mit Zod/Schema“) |
| `packages/ui-mock/*` + `apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.tsx` | Hot-Swap-/Visual-Regression-Fundament | als-vorlage (DoD: Hot-Swap-Drill + Visual-Snapshot) |
---
## Vorhandene Daten-Modelle
Quelle: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/knowledgeBase.prisma`
| Prisma-Modell | Relevanz für M38 |
|---|---|
| `KnowledgeBase` | KB-Container (slug, title, description, defaultLanguage, layout `list/articles/grid/docs`, color, enabled, `languages`, `links`, logo, seoImage, basePath, optional `tenantId`) — entspricht inhaltlich dem Help-Center-Root. **DB-getrieben — Phase-2-Modell, nicht Phase-1.** |
| `KnowledgeBaseCategory` | Kategorie (slug, order, title, description, **icon**, language, seoImage) — deckt Spec-`_category.json` (slug/label/description/icon/order) inhaltlich vollständig ab, aber als DB-Zeile statt File. |
| `KnowledgeBaseCategorySection` | Unter-Sektionen je Kategorie (order/title/description) — über Spec hinaus (optional). |
| `KnowledgeBaseArticle` | Artikel (slug, title, description, order, `contentDraft`/`contentPublished`/`contentPublishedAsText`, `contentType` wysiwyg/markdown, language, `featuredOrder`, seoImage, `publishedAt`, `relatedInArticleId`, `createdByUserId`) — deckt Frontmatter-Felder slug/title/order/description + Body inhaltlich ab. **Kein** Frontmatter-`deprecated`/`redirect_to`/`keywords`/`last_updated`-Äquivalent (siehe Lücken). |
| `KnowledgeBaseRelatedArticle` | Verwandte-Artikel-Relation (Spec: `related_slugs`). |
| `KnowledgeBaseViews` / `KnowledgeBaseArticleViews` | View-Tracking pro `userAnalyticsId` (Spec Block I Phase-2 „View-Counts“). |
| `KnowledgeBaseArticleUpvotes` / `KnowledgeBaseArticleDownvotes` | Anonymes Daumen-Feedback pro `userAnalyticsId` (Spec Block D „War hilfreich?“, ohne PII). |
**Wichtig:** Diese Modelle modellieren die **DB-getriebene** Variante. M38-Phase-1 ist **bewusst file-basiert** (Spec A.1, M172).
Sie sind nur als **Strukturreferenz / Phase-2-Fundament** relevant, nicht als Phase-1-Datenquelle.
Such-Index-Schema vorhanden: `packages/search/src/schemas/kb-articles.ts` (`kbArticlesIndex`).
Vektor/RAG-Speicher (Phase-2): `@toolctrl/vector-store` (pgvector/Qdrant), `prisma/migrations/...enable_pgvector`.
---
## Lücken / komplett neu zu bauen
1. **File-basierter Daten-Layer (Kern-Lücke).** Es gibt **keine** Boilerplate-Mechanik für
`content/help/de/<kategorie>/<slug>.md` + `_category.json`. Komplett neu zu bauen:
- Markdown-File-Loader mit **YAML-Frontmatter-Parser** (Pflicht: slug/title/category/order/description/last_updated; optional related_slugs/keywords/deprecated/redirect_to).
- `_category.json`-Loader (slug/label/description/icon/order).
- Mapping Frontmatter/File → bestehende DTO-Form (`KbArticleDto`/`KbCategoryDto` als Zielform wiederverwendbar).
2. **Build-Time-Index + Validierung (M172-Erfolgskriterium).** Nicht vorhanden. Neu:
- Build-Step erzeugt Volltext-Index (FlexSearch ~50KB) **oder** Postgres-FTS-Helper-Tabelle, Kategorien-Manifest, `sitemap.xml`.
- **Build-Fail**, wenn eine Kategorie-Referenz oder ein `related_slug` nicht existiert (harte Validierung — existiert in BP nicht).
3. **Frontmatter-spezifische Felder ohne DB-Pendant:** `last_updated` (BP nutzt `updatedAt`), `keywords`, `deprecated` + Deprecated-Banner, `redirect_to`/Redirect-Handling. Neu zu bauen (Spec A.2, Block D, Block H).
4. **Inhaltsverzeichnis (TOC) aus H2-Headings, klickbar/scroll-spy.** In `KbArticleContent`/`KbDocsLayout` **nicht** vorhanden (kein toc/heading-Generator gefunden). Neu zu bauen (Spec Block D).
5. **`/help/sitemap.xml`-Route.** Keine Sitemap-/robots-Route in der Boilerplate (`grep sitemap/robots` → leer). Neu (Spec Block B, A.4).
6. **URL-Schema-Umstellung.** Boilerplate-Routen sind `/help/$slug/($lang)/...` (KB-Slug zuerst, Sprache optional/hinten).
HiveGrid verlangt `/help/$lang/$category/$slug` mit `/help/` → `/help/de/`-Redirect und 404 für nicht-DE (Spec Block B, INTEGRATION-CONTRACTS §3). Routen-Files müssen neu strukturiert werden.
7. **Public-Mounting / Auth-Vorlagerung.** `help/**` steht aktuell in `defaultDisabledPluginRouteFilePatterns` (`apps/web/app/routes.ts`), also **standardmäßig deaktiviert**. Muss aktiviert und als **vor-Auth**, kein Tenant-Context, kein RLS gemountet werden (Spec Block G). IP-Rate-Limiting (1000 Req/Min/IP) ist neu zu ergänzen.
8. **Deep-Link-Mapping Route→Slug aus der App (Block F).** Hilfe-Icon-Pattern + Mapping-Konfiguration (`/{tenant}/...` → `kategorie/slug`) mit Fallback auf `/help/de/`. Komplett neu (kein Pendant in BP).
9. **Anonymes Feedback ohne Cookies.** BP-Feedback nutzt `getAnalyticsInfo` (`userAnalyticsId`, i.d.R. Cookie-gestützt). Spec fordert „anonym ohne Cookies“ — Mechanik prüfen/ersetzen.
10. **Such-Ranking & Highlight.** BP-SQL-Fallback ist einfaches LIKE ohne explizites Ranking; Spec verlangt Title>Description>Keyword>Body + Snippet-**Highlight** + Empty-State-Text mit `support@hivegrid.de`. Ranking/Highlight neu (Meili liefert Ranking, aber Phase-1 ist client-side FlexSearch vorgesehen).
11. **„Sprache nicht verfügbar“-Klartext-Banner / Redirect** (`/help/en/...` → `/help/de/` mit Hinweis, Spec Block H). BP wirft stattdessen hartes 404 bei unsupported lang.
12. **HiveGrid-Querschnitt-Pakete.** `@hivegrid/*` (activity/audit/notifications/entitlements/i18n) sind **HiveGrid-eigene** Pakete (INTEGRATION-CONTRACTS) und in der Boilerplate **nicht** vorhanden (dort `@toolctrl/*`). Für M38 großteils irrelevant (öffentlich, keine Permissions, keine schreibende Domain-Aktion außer anonymem Vote) — aber Feature-Flag-Schaltbarkeit (M006) und ggf. Audit für externe Effekte müssen HiveGrid-konform verdrahtet werden.
13. **Initial-Artikel-Inventar (~10-20 DE-Artikel).** Inhalt, nicht Code — neu zu schreiben (Spec A.5, M172). BP hat `DefaultKbsTemplate.ts` als Demo-Content, aber inhaltlich irrelevant.
---
## Empfohlenes Vorgehen
**Phase A — Daten-/Build-Fundament zuerst neu bauen (die Kern-Lücke):**
1. Verzeichnis-Layout `content/help/de/<kategorie>/<slug>.md` + `_category.json` festlegen.
2. Frontmatter-Parser + File-Loader bauen; Ausgabe **direkt auf die vorhandenen DTOs** (`KbArticleDto`/`KbCategoryDto`/`KbSearchResultDto` als Zielform) mappen — so bleibt die UI-Schicht wiederverwendbar.
3. Build-Step: Kategorien-Manifest + Volltext-Index (FlexSearch oder Postgres-FTS) + `sitemap.xml`; harte Validierung (Kategorie-Refs, related_slugs) → Build-Fail. (M172-Erfolgskriterium.)
**Phase B — UI/Routing aus Boilerplate übernehmen und umbauen:**
4. `renderSanitizedMarkdown` aus `apps/web/app/utils/html-sanitizer.ts` **1:1** übernehmen (löst die Renderer-Wahl der Spec).
5. View-Komponenten + DTO-Mapping aus `modules/knowledgeBase/{components,routes/views,service}` als Vorlage übernehmen; Daten-Reads von DB auf den File-Index umstellen.
6. SEO-Metatag-Builder (`kbToDto/categoryToDto/articleToDto`) **als-vorlage** übernehmen — OG/Twitter/Canonical sind fertig.
7. Routen neu nach HiveGrid-Schema `/help/$lang/$category/$slug` strukturieren (Vorlage: `routes/help/*`); `/help/`→`/help/de/`-Redirect, nicht-DE-Klartext-Banner, `sitemap.xml`-Route; `help/**` aus der Disabled-Liste aktivieren und **public/vor-Auth** mounten + IP-Rate-Limiting.
**Phase C — Ergänzungen, die der Boilerplate fehlen:**
8. TOC-aus-H2-Generator (klickbar/scroll-spy) in die Artikel-View ergänzen.
9. Deep-Link-Mapping Route→Slug (Block F) inkl. Hilfe-Icon-Pattern + Fallback `/help/de/`.
10. Such-Ranking (Title>Desc>Keyword>Body) + Snippet-Highlight + Empty-State-Klartext; Debounce auf 300ms.
11. Deprecated-Banner + `redirect_to`-Handling + Artikel-404-Klartextseite (Block D/H).
12. Anonymes Feedback (Daumen) aus `kbAnalytics.db.server.ts` übernehmen, aber **cookieless** umbauen.
**Phase D — DoD-Querschnitt (HiveGrid):**
13. Feature-Flag-Schaltbarkeit (M006), i18n-Keys (DE-Locale, LP-12), Smoke-Test (`routes/help/help-routes.test.tsx` als Vorlage), Hot-Swap-Drill + Visual-Snapshot. Sidebar-Eintrag entfällt (Help ist außerhalb Tenant-Sidebar, Spec Block B) — als „nur Inline-Verlinkung“ dokumentieren (DoD-Erreichbarkeit erlaubt das explizit).
**Phase-2 (später, BP liefert das Fundament fertig):** DB-getriebene Pflege + Editor-UI (`admin/knowledge-base/*` + `KnowledgeBase*`-Prisma-Modelle), Mehrsprachigkeit, **RAG-Suche** (`kbArticleRag.server.ts` + `@toolctrl/ai/embeddings` + `@toolctrl/vector-store`), View-Counts/Helpful-Statistik.
---
## Anti-Erfindung / Vorbehalte
- Die Boilerplate-Help-Center-Implementierung ist **DB-getrieben**; die file-/Git-PR-basierte Phase-1-Architektur der M38-Spec ist **nicht** vorhanden und muss neu gebaut werden.
- `help/**`-Routen sind in `apps/web/app/routes.ts` **standardmäßig deaktiviert** (`defaultDisabledPluginRouteFilePatterns`).
- **Kein** TOC-/H2-Generator, **keine** `sitemap.xml`-/robots-Route, **kein** Deep-Link-Route→Slug-Mapping in der Boilerplate gefunden.
- Such-SQL-Fallback ist LIKE-basiert ohne explizites Title>Desc>Keyword>Body-Ranking; Highlight fehlt.
- HiveGrid-Querschnitt-Pakete (`@hivegrid/*`, `packages/ui-hivegrid`, `packages/db/src/search/indexed-entities.ts`) sind **HiveGrid-eigen** und in der Boilerplate (`@toolctrl/*`) nicht enthalten.
@@ -0,0 +1,120 @@
# Boilerplate-Abgleich — M39 Help-Desk / Support
| Feld | Wert |
|---|---|
| **Modul-ID** | M39 |
| **Name** | Help-Desk / Support |
| **Milestones** | M174 (Email-/Feedback-Ticket-Eingang + Plattform-Admin-Bearbeitung), M175 (In-App-Feedback-Widget „Problem melden") |
| **Block** | Block 7 — Plattform-Außenseite (Betrieb, Compliance, Zugang) |
| **Reuse-Level** | **HIGH** |
| **Spec-Quellen** | `_bmad-output/specs/M39-help-desk.md`, `_bmad-output/pflichtenheft/blocks/block7.md` §39 |
## Kurzfazit
Die Boilerplate enthält ein **fast vollständiges Phase-1-Help-Desk-Modul** unter
`apps/web/app/modules/helpDesk` + `prisma/schema/helpDesk.prisma`. Es deckt im Kern:
- In-App-Feedback-Widget (`AddFeedbackButton.tsx`) mit Trigger + Modal + Submit-Action,
- Submit-Action verdrahtet in `app.$tenant.tsx` (`add-feedback` + `create-support-ticket`),
- Service- und DB-Layer für `Feedback` und `SupportTicket` (inkl. Inbound-E-Mail-Dedup),
- **PII-/Secret-Redaction** beim Submit (DSGVO-relevant, spec-konform),
- Plattform-Admin-Bereich `admin/help-desk` (Overview + Tickets-Liste + Feedback-Liste) mit Filter/Suche/Bulk-Delete,
- Admin-Sidebar-Eintrag bereits registriert,
- Notification an Admin-Rolle bei neuem Feedback/Ticket,
- Sliding-Window-Rate-Limiter als Package vorhanden.
Was fehlt, sind die **HiveGrid-spezifischen Spec-Erweiterungen** (reicheres Status-/Assignee-/
Internal-Notes-Datenmodell, Attachments, Browser-Info/App-Version-Capture, Screenshot, Detail-View,
10/h-Rate-Limit) und die **HiveGrid-Layer-Disziplin** (View-Model-Layer, ui-hivegrid-Adapter,
Permission-Keys statt `adminOnly`-Bool). Es ist eine **Anpass- und Erweiterungsaufgabe, kein Neubau.**
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/helpDesk.prisma` → `model Feedback` | Tenant/User-scoped Feedback (`message`, `fromUrl`, `tenantId?`, `userId?`, `createdAt`) | **als-vorlage** — Felder fehlen (status, assignee, internal_notes, route_path, browser_info, app_version, attachments, resolved_*) → erweitern |
| `prisma/schema/helpDesk.prisma` → `model SupportTicket` | Ticket mit `source`/`status`(default open)/`priority`, `subject`, `message`, `fromEmail`, `fromUrl`, `inboundMessageId @unique`, Indizes `[tenantId,status,createdAt]` + `[source,createdAt]` | **anpassen** — näher an Spec-Lifecycle als `Feedback`; entweder konsolidieren oder als Mailbox-Ticket-Modell weiterführen |
| `prisma/schema/core.prisma` → `model FileObject` (Z.213) | S3-Storage-Objekt (provider/bucket/key/contentType/byteSize/checksum/publicUrl) + `FileUploadProgress`/`FileChunk` | **anpassen** — Basis für Attachments (Spec A.3); Join `Feedback↔FileObject` + Storage-Pfad-Konvention `tenants/{id}/feedback/{id}/...` ergänzen |
| `apps/web/app/modules/helpDesk/services/Feedback.server.ts` | Submit-Service: Redaction, Rate-Limit-Count, Notification-Call, `createFeedback` | **anpassen** — Rate-Limit ist `count`-basiert ohne Zeitfenster (Spec: 10/User/h) → auf Sliding-Window umstellen; Browser-Info/App-Version/route_path ergänzen |
| `apps/web/app/modules/helpDesk/services/SupportTickets.server.ts` | `createInline` + `createFromInboundEmail` (E-Mail-Dedup via `inboundMessageId`), Subject-Normalisierung, Redaction | **anpassen** — `createFromInboundEmail` ist Phase-2-Vorgriff; `createInline`-Pattern 1:1 nutzbar |
| `apps/web/app/modules/helpDesk/services/FeedbackRedaction.ts` (+ `.server.ts`) | `redactFeedbackText` — entfernt E-Mails, Bearer-Tokens, API-Keys, Hex/Base64-Secrets aus Body+URL | **1:1** — deckt DSGVO-Transparenz/Query-Param-Stripping (Spec B.3) zum großen Teil ab |
| `apps/web/app/modules/helpDesk/db/feedback.db.server.ts` | `getAllFeedback` (Filter/Suche/Pagination, include tenant+user), `createFeedback` | **anpassen** — Volltextsuche nur über `message`; Spec will Body+Tenant-Name+User-Name; Cursor- statt Offset-Pagination |
| `apps/web/app/modules/helpDesk/db/supportTickets.db.server.ts` | `getAllSupportTickets`, `createSupportTicket`, `updateSupportTicketStatus` | **anpassen** — Status-Update-Funktion vorhanden; Assignee/Notes/Bulk-Status fehlen |
| `apps/web/app/components/layouts/buttons/AddFeedbackButton.tsx` | In-App-Trigger (Top-Bar-Button) + Feedback-Modal + Fetcher-Submit + Toast bei Erfolg/Fehler, autoerfasst `fromUrl`+`tenantId` | **als-vorlage** — UI-Grundgerüst da; nach `packages/ui-hivegrid` portieren (Layer-Disziplin), Attachments/Screenshot/Route-Anzeige/DSGVO-Hinweis/10-Zeichen-Validierung ergänzen |
| `apps/web/app/routes/admin/help-desk.tsx` | Plattform-Admin-Shell (SidebarIconsLayout: Overview/Tickets/Feedback) + Outlet | **anpassen** — Reihenfolge/Labels an HiveGrid; „Mailbox"-Direktlink-Tab (Spec D.1 `/feedback/mailbox`) ergänzen |
| `apps/web/app/routes/admin/help-desk/feedback.tsx` | Listen-Route: Loader baut Filterable-Props (tenant/user), Pagination, Action mit Bulk-`delete` + CSRF | **anpassen** — Status/Assignee/Zeitraum-Filter + CSV-Export + Bulk-Status/Bulk-Assign fehlen |
| `apps/web/app/routes/admin/help-desk/tickets.tsx` | Tickets-Listen-Route mit TableSimple (createdAt/subject/status/source/message) | **als-vorlage** — Listen-Pattern für die Feedback-Tabelle |
| `apps/web/app/modules/helpDesk/components/FeedbackTable.tsx` | Tabelle: Suche, Filter, Bulk-Select+Delete, Spalten (createdAt/tenant/user/message), Redaction in Anzeige | **anpassen** — Spalten Body-Preview(100), #Attachments, Route, Status-Badge, Assignee ergänzen; nach ui-hivegrid portieren |
| `apps/web/app/application/sidebar/AdminSidebar.tsx` (Z.287-294) | Admin-Sidebar-Eintrag „Help-Desk" + Sub „Feedback" via `enabledAdminRouteItem` / `UI_NAV_IDS.adminHelpDesk` | **anpassen** — Reachability-Anker vorhanden; auf HiveGrid-Permission-Gate (`platform_admin.feedback.read`) statt reinem Route-Enable umstellen |
| `packages/shared-store/src/helpers/rate-limit-sliding.ts` | Sliding-Window-Rate-Limiter (`consume`/`reset`, windowSeconds, max, Redis-Lua) | **1:1** — exakt für Spec B.5 „10 Submissions/User/h" |
| `apps/web/app/modules/notifications/services/.server/NotificationService.ts` → `sendToRoles` | Notify-Channel `admin-users` bei neuem Feedback/Ticket | **anpassen** — in HiveGrid über M011 `notify({...})` statt Direkt-Aufruf (AGENTS.md Querschnitt) |
| `apps/web/app/routes/help/$slug.($lang).tsx` (+ Geschwister) | Öffentliche Help-Center-Routen (Modul 38) | **als-vorlage** — Andock-Punkt für den mailto:`support@hivegrid.de`-Trigger (Spec B.1, Public-Kontext) |
| `apps/web/app/routes/admin/help-desk.auth.test.ts` | Auth-Test-Gerüst (Loader/Action gemockt, adminOnly) | **als-vorlage** — Test-Pattern für die HiveGrid-Smoke/Unit-Tests |
---
## Vorhandene Daten-Modelle
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
- **`helpDesk.prisma` → `Feedback`** — `id`, `createdAt`, `tenantId?`, `tenant`, `userId?`, `user`, `message`, `fromUrl`. Minimal: deckt Spec-Felder `id/created_at/tenant_id/tenant_user_id/body/route_path` ab. **Fehlt:** `updated_at`, `status`, `assignee_admin_user_id`, `internal_notes`, `resolved_at/_by`, `browser_info`, `app_version`, `attachments[]`, Spec-Indizes.
- **`helpDesk.prisma` → `SupportTicket`** — `id`, `createdAt`, `updatedAt`, `tenantId?`, `userId?`, `source`, `status`(@default open), `priority`, `subject`, `message`, `fromEmail?`, `fromUrl?`, `inboundMessageId? @unique`; Indizes `[tenantId,status,createdAt]`, `[source,createdAt]`. Näher am Spec-Status-Lifecycle als `Feedback`. **Fehlt:** Assignee, internal_notes, resolved-Felder, browser_info, app_version, Attachments-Relation.
- **`core.prisma` → `FileObject`** (Z.213) + `FileUploadProgress`/`FileChunk` (Z.195-211) — S3-Storage-Fundament für Attachments (Spec A.3). Es gibt **kein** dediziertes `FeedbackAttachment`-Join-Modell → neu.
**Permission/Plan-Hinweis:** `packages/entitlements/src/features.ts` definiert `supportTickets`+`prioritySupport` als Feature-Keys, `plans.ts` weist Quotas zu. Das ist Tenant-Entitlement-Logik, **nicht** die in Spec E.2 geforderten Plattform-Admin-Permissions (`platform_admin.feedback.read/write/delete`) — die fehlen komplett.
---
## Lücken / komplett neu zu bauen
**Datenmodell (Erweiterung, kein Neubau):**
- `status`-Enum (`open|in_progress|resolved|wontfix`), `assignee_admin_user_id`, `internal_notes` (Markdown), `resolved_at`, `resolved_by_admin_user_id` an Feedback ergänzen.
- `browser_info` (JSON: UA, Viewport, Screen, Sprache, Timezone), `app_version`, `route_path` als eigenes Feld.
- `FeedbackAttachment`-Relation auf `FileObject` + Storage-Pfad-Konvention `tenants/{tenantId}/feedback/{feedbackId}/...`, Typ-/Größen-Limits (5×10 MB, PNG/JPG/WEBP/PDF).
- Spec-Indizes `(status, created_at DESC)`, `(tenant_id, created_at DESC)`, `(assignee_admin_user_id, status)`.
**Widget (Spec B):**
- Browser-Info-Sammler-Util (UA/Viewport/Sprache/Timezone) — nicht vorhanden.
- App-Version-Einbettung zur Build-Zeit (Build-Hash) — nicht vorhanden.
- Screenshot-Funktion (`html2canvas-pro`, One-Click, mit Consent) — nicht vorhanden.
- Attachment-Upload-Komponente (Drag&Drop, max 5) im Modal — nicht vorhanden.
- Aktuelle-Route-Anzeige (read-only) + DSGVO-Hinweis + 10-Zeichen-Min-Validierung (Send disabled) im Modal — nur Basis-Modal da.
- Query-Param-Stripping bei `route_path` (Redaction deckt Secrets ab, aber nicht generelles Query-Strip).
- mailto:`support@hivegrid.de`-Trigger in Public-`/help/`-Routen — nicht vorhanden.
**Plattform-Admin-Detail-View (Spec D.3) — fehlt komplett:**
- Route `admin.hivegrid.de/feedback/:id`, Body-Anzeige mit URL-Link-Detection, Attachment-Preview (Image/PDF), Tenant-Block + User-Block mit Direktlinks ins Tenant-Admin (Impersonation M37), Browser-/Tech-Kontext ausklappbar, Inline-Edit Status/Assignee/Internal-Notes, Hard-Delete mit Warnung.
- **Activity-Log pro Feedback** (Status-/Assignee-/Notes-Wechsel mit Actor+Timestamp) — kein Audit/Activity-Wiring im BP-Modul; via M001/M045 neu verdrahten.
- Mailbox-Direktlink-Tab (Spec C/D.1 `/feedback/mailbox`) — nicht vorhanden.
**Liste (Spec D.2) — Teil-Lücken:**
- Status-/Assignee-/Zeitraum-Filter, Volltextsuche über Body+Tenant+User, Cursor-Pagination (50), Bulk-Status-Wechsel, Bulk-Assign, CSV-Export. Nur Tenant/User-Filter + Body-Suche + Offset-Pagination + Bulk-Delete vorhanden.
**Querschnitt / Layer-Disziplin (AGENTS.md DoD) — durchgehend neu:**
- View-Model-Layer (`packages/view-models`) — BP-Routen geben rohe DB-DTOs direkt aus.
- UI nach `packages/ui-hivegrid` (Widget+Tabelle), Subframe-Adapter — BP-UI liegt in `apps/web/app/components` + `modules/helpDesk/components`.
- Permission-Keys `platform_admin.feedback.read/write/delete` (M004) statt `requireAuth({adminOnly})`-Bool; Permission-Denied → 404 (Spec E.2).
- Audit auto (M001) + Activity (M045) + Notification via M011 `notify()` statt Direkt-`sendToRoles`.
- i18n-Keys (M003): BP nutzt `feedback.*`/`helpDesk.*`-Keys, aber HiveGrid-Klartexte (Spec B.4/F/39.Y) neu pflegen.
- Feature-Flag (M006), Smoke-Test/Hot-Swap (M017), Visual-Regression (M016) — neu pro DoD.
**Bewusst NICHT bauen (Phase 2 / Anti-Liste, Spec F + 39.X):**
Live-Chat, voll-Ticket-System mit User-Notifications, User-facing-Status-Page, NPS/CSAT, Mailbox-Sync in der App, KI-Auto-Triage, Feedback-Voting, Bug-Tracker-/Slack-Integration. → `SupportTickets.createFromInboundEmail` (Inbound-Mail→Ticket) ist ein Phase-2-Vorgriff und in M174 **nicht** zu aktivieren (Spec C.1/C.2: Mailbox extern lesen, nur Direktlink).
---
## Empfohlenes Vorgehen
**M174 zuerst (Backend + Plattform-Admin), dann M175 (Widget) — entspricht der Milestone-Abhängigkeit (M175 setzt M174 voraus).**
1. **Daten-Layer erweitern (M174):** `Feedback`-Modell der Boilerplate als Vorlage nehmen und um Spec-Felder (`status`-Enum, `assignee_admin_user_id`, `internal_notes`, `resolved_*`, `browser_info`, `app_version`, `route_path`) + Spec-Indizes + `FeedbackAttachment`→`FileObject`-Relation erweitern. Forward-Only-Migration mit Inverse-SQL-Kommentar. Entscheiden: `SupportTicket` als separates (Mailbox-)Modell behalten oder Feedback-Modell konsolidieren.
2. **Service-Layer übernehmen + härten (M174):** `Feedback.server.ts` + `feedback.db.server.ts` + `FeedbackRedaction.ts` aus BP übernehmen; Rate-Limit auf `rate-limit-sliding` (10/User/h) umstellen; Status-Lifecycle-Übergänge, Assignee-Set, Internal-Notes-Edit ergänzen; Notification auf M011 `notify()`, Audit/Activity über M001/M045 verdrahten.
3. **Plattform-Admin-Liste (M174):** Routen `admin/help-desk.tsx` + `feedback.tsx` + `FeedbackTable.tsx` als Vorlage nach View-Model + ui-hivegrid portieren; Status/Assignee/Zeitraum-Filter, Volltextsuche (Body+Tenant+User), Cursor-Pagination, Bulk-Status/Bulk-Assign, CSV-Export ergänzen; Permission-Gate `platform_admin.feedback.read`.
4. **Plattform-Admin-Detail-View neu (M174):** `/feedback/:id` mit allen Spec-D.3-Blöcken + Activity-Log + Hard-Delete; Mailbox-Direktlink-Tab (`/feedback/mailbox`) + Klartext-Hinweis (Spec C).
5. **In-App-Widget (M175):** `AddFeedbackButton.tsx` als Vorlage nach `packages/ui-hivegrid` portieren; Route-Anzeige, DSGVO-Hinweis, 10-Zeichen-Validierung, Browser-Info-Util, App-Version, Attachment-Upload (M052/M23-`FileObject`), `html2canvas-pro`-Screenshot ergänzen; Submit-Action (BP `app.$tenant.tsx`-Pattern) anpassen; mailto-Trigger in Public-`/help/`-Routen.
6. **Querschnitt + Tests + Reachability (beide):** Sidebar-Permission-Gate, i18n-Keys (HiveGrid-Klartexte), Feature-Flag, Smoke-/Unit-/Hot-Swap-/Visual-Regression-Tests, Empty-/Loading-/Permission-Denied(404)-States pro DoD.
---
*Erstellt durch Boilerplate-Abgleich-Agent. Geprüft direkt gegen `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (nicht nur Inventur). Es wurde nichts in der Boilerplate oder im HiveGrid-Code geändert.*
@@ -0,0 +1,196 @@
# Boilerplate-Abgleich — Gesamt-Übersicht (alle HiveGrid-Module)
> Konsolidierung aller 38 Modul-Verdicts + Detail-Reports gegen die Boilerplate
> (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`). Stand: 2026-06-04.
> Grundlage: `docs/boilerplate-mapping/M*.md` + `docs/boilerplate-inventory/*.md`.
> Wichtig: Das HiveGrid-Cloud-Repo enthält aktuell **nur Spec-/Docs-Artefakte** (kein `apps/`, `packages/`).
> Die Boilerplate ist die zu übernehmende Code-Basis — sie muss als Pre-Flight zuerst eingezogen werden.
---
## Executive Summary
**Grobe Gesamt-Abdeckung: ca. 35–45 % der HiveGrid-Planung ist durch die Boilerplate substanziell vorbereitet** — aber sehr ungleich verteilt:
- **Querschnitt/Fundament (M00): ~80–90 % fertig.** Audit (Hash-Kette), Permissions (404-statt-403, Tenant-Scope, Owner-Check), i18n (ICU/Plurale + CI-Gate), Feature-Flags (Engine v2), Idempotenz, Notifications, Outbox, View-Models, Adapter-Registry, DSGVO-FK-Map, CI-Gates — alles real, getestet, code-verifiziert. HiveGrid füllt überwiegend Inhalte ein (Error-Texte, Flags, i18n-Keys, Sidebar-Einträge). Dies ist das Fundament, auf dem **alle** Fachmodule stehen.
- **Plattform-/Infrastruktur-Module: hoch.** Auth/Multi-Tenancy (M27), Subscriptions/Billing (M28), Automation-Engine (M17), KI-Layer (M18), i18n (M30), Feature-Flags-Admin (M32) sind **high** — nahezu vollständige Architektur-Skelette vorhanden, HiveGrid baut Inhalte + gezielte Lücken.
- **Kommunikations-/Mid-Tier-Module: medium.** CRM (M01), Lead-Inbox (M02), Form-Builder (M05), Email (M09/M10), Telefonie (M12), HR-Hub (M14)*, Notifications (M22), Files (M23), Suche (M24), Tasks (M26)*, Apps-Engine (M33a), Public-API (M34), DSGVO (M35), Mobile (M36), Plattform-Admin (M37), Help-Center (M38), Help-Desk (M39), KWP (M19): **starkes Querschnitt-Fundament + Vorlagen, aber Domänen-Kern neu.**
- **Fachliche Greenfield-Module: low.** Sales-Pipeline (M03), Auftrags-/Projektpipeline (M04), Booking (M06), Angebot/Signatur (M07), Team-Chat (M13), Customer-Portal (M15), Calendar-Sync (M25): **kein Domänen-Modell in der Boilerplate** — nur Querschnitt + Bau-Vorlagen, der fachliche Kern (Daten + Logik + UI) ist Neubau.
**Die zentrale Erkenntnis:** Die Boilerplate bietet ein **erstklassiges Plattform-Fundament** (Auth, Billing, Automation, KI, Audit, i18n, Flags, Notifications, Files-Storage, Apps-Engine-Schema) — aber **fast keine HiveGrid-Fachdomäne** (kein typisiertes CRM-Modell, kein Deal/Pipeline/Project, kein Calendar, kein Booking, kein Chat). Boilerplate-Eigen-CRM ist Entity-Builder-basiert (Entity+Row+RowValue) und **architektonisch inkompatibel** mit den geforderten First-Class-Tabellen → muss entfernt, nicht angepasst werden.
### Vier wiederkehrende Quer-Befunde (für alle Module relevant)
1. **Naming-Drift (Blocker, kein Code-Gap):** HiveGrid-Doku referenziert durchgängig `@hivegrid/*`, `packages/ui-hivegrid`, `sidebar.config.ts`. Real existiert `@toolctrl/*`, `packages/ui-app` (Stub), Sidebar in `apps/web/app/application/sidebar/`. **Rebranding/Rename muss vor M018ff erfolgen**, sonst greifen alle DoD-Pfade ins Leere.
2. **Zwei falsche AGENTS.md-Pfadbehauptungen:** `packages/db/src/search/indexed-entities.ts` existiert nicht (Search liegt in `packages/search/`); durchgängiges `ui-hivegrid/sidebar.config.ts` entspricht nicht der Realität.
3. **Fehlende HiveGrid-Querschnittsdienste:** `logActivity()` / `@hivegrid/activity` (M045) und `Mass-Action-Schutz` (Bulk-Vorschau/Bestätigung) existieren **nirgends** in der Boilerplate — distinkt vom Audit-Log, Neubau.
4. **Falsche PLAN.md-Dependency-Annahmen (verifiziert):** `signature_pad` (M069), `browser-image-compression` (M052), `react-grid-layout` (M147), `react-beautiful-dnd` (M061→ist `@dnd-kit`), `kbar` (M058), `next-themes` (M030) sind **NICHT** in den Boilerplate-Deps. Vor Bau korrigieren.
### Subframe-Adapter (M15) — Querschnitt-Lücke für *alle* UI-Module
`packages/ui-subframe` ist ein **bewusst leerer Platzhalter** (nur README, leere Registry). Der Type-Bridge-Adapter (Subframe-Props ↔ HiveGrid-VM) existiert als Code nicht. Da User-Memory **jede Route via Subframe** verlangt, ist dieser Adapter-Layer eine harte Vorbedingung für jedes Fachmodul mit UI. Hoch priorisieren.
---
## Master-Tabelle
| Modul | Reuse | Wichtigste übernehmbare Assets | Größte Lücken | Milestones |
|---|---|---|---|---|
| **M00** Querschnitt-Hülle | 🟢 high | foundation (audit/permissions/errors/flags/idempotency/adapters/notifications/outbound-http), view-models, DB-Layer (Hash-Chain), CI-Gates (verify:i18n/ui-visual/hot-swap/tenant-isolation) | `logActivity`, indexed-entities-Registry, Subframe-Adapter-Code, Mass-Action-Schutz; Naming-Drift | M001–M017 |
| **M17** Automation-Engine | 🟢 high | komplette graph-Workflow-Engine (xyflow+dagre), Outbox-Trigger-Fanout, Block-Registry, Conditions, Resume, Credential-Crypto, Promptfoo-Gate | ~45 Domänen-Trigger + ~40 Actions, 24h-Undo, Anomalie/Loop-Guard, KI-NL-Erstellung, Dry-Run-Schwelle, Metering, Layer-Umbau | M075–M082 |
| **M18** KI-Layer / LLM-Gateway | 🟢 high | EU-Provider-Stack (Mistral/Scaleway/Aleph), 30-Min-Fallback, RAG+pgvector(HNSW), Promptfoo-OWASP-Suite, Pay-as-you-go-Overage-Engine | Whisper-EU-Transkription, Runtime-Input-Sanitizer, deterministischer Output-Cache, Sprach-zu-Automation, gesamtes UI | M083–M088 |
| **M27** Auth / Multi-Tenancy / RBAC | 🟢 high | Identity/Tenancy/RBAC-Modelle, TOTP+Recovery, HIBP-Policy, Magic-Link, Slug-Service, Settings-UI, ApiKey gehasht | Postgres-Sessions (BP=Cookie!), Postgres-RLS (fehlt!), Tenant-Lifecycle-Status-Enum, SHK-Rollen-Template, Reassign-Workflow | M018–M027 |
| **M28** Subscriptions / Billing | 🟢 high | Subscription-Datenmodell (13 Modelle), Stripe-Wrapper (~40 fn), Entitlements-Engine, Pricing-Admin, AI-Overage-Pipeline | Lifecycle-State-Machine, Seat-Modell (Büro/Monteur), Read-Only-Middleware (402), Frozen/Dunning, Apple-Compliance (LP-8!) | M153–M156 |
| **M30** i18n / Mehrsprachigkeit | 🟢 high | @toolctrl/i18n (ICU/Plurale/RTL), Server-Wiring (No-Flash), verify:i18n-Gate, Locale-Switcher | `Tenant.default_language`, `User.timezone/date_format`, TR/PL-Locales, Resolution-Order-Schritt, Empfänger-Auflösung | M028, M029 |
| **M01** CRM-Kern | 🟡 medium | Querschnitt komplett, Search+Fallback, Export/DSGVO, Import/Dedupe, Form-Capture, ~707 shadcn-Komponenten | Contact/Company/Lead/Activity/Tag/CustomField als **typisierte Tabellen** (BP-CRM=Entity-Builder, inkompatibel!), Merge, Promotion | M042–M046 |
| **M02** Lead-Inbox | 🟡 medium | Marketing-Lead-Inbox als Strukturmuster, Honeypot, Rate-Limiter, Realtime, Outbox, Retention-Cron, Apps-Engine-Schema | tenant-scoped Lead-Modell (BP-Lead operator-scoped!), Status-State-Machine, Routing-DSL, Anomalie-Detection, Statistik | M047–M051 |
| **M05** Form-Builder | 🟡 medium | Form-Widget (Builder+Drag&Drop, Zod, Origin-Allowlist, Honeypot, Captcha, Outbox-Routing), Submit-Endpoint | 9/17 Feldtypen, normalisiertes Datenmodell, 7/11 Submission-Aktionen, Conditional-Display, SHK-Vorlagen, hCaptcha statt Turnstile | M121–M125 |
| **M09** Email-Inbox + Sync | 🟡 medium | Mail-Stack (MailerSend EU), Adapter-Pattern (marketing-outbound), Bounce-Webhook-Vorlage, Storage, appsEngine (OAuth-DataConnection) | Gmail/Outlook-Mailbox-OAuth, Push-Sync (Pub/Sub/Graph), DKIM/SPF/DMARC, Auto-Match, gesamtes Inbox-Modell | M096–M099 |
| **M10** Email-Marketing | 🟡 medium | Campaign/OutboundEmail-Modelle, Kampagnen-CRUD+Editor, Sender-Mgmt, Tracking-Pixel/Unsubscribe-Token, Bounce-Webhook | Unsubscribe/Suppression/Segment/Template-Modelle, Daily-Cap/Frequenz/Spam-Score, BullMQ-Worker, EU-Provider-Tausch | M100–M104 |
| **M12** Telefonie (AirCall/HalloPetra) | 🟡 medium | Adapter-Registry-Pattern, OAuth-Flow-Template, AES-Crypto, HMAC-Webhook, Push/Notify-Pipeline, Workflow-Trigger | beide Provider-Adapter, Auto-Match (CRM-abhängig), E.164 (libphonenumber fehlt), gesamtes UI/Datenmodell | M105–M109 |
| **M14** HR-Hub | 🟡 medium | AES-Crypto, Storage+Signed-URLs, Audit, Notify, Exports/DSGVO, Imports, Form-Widget, Apps-Engine | alle 21 HR-Modelle, Per-Tenant-KMS/DEK, Leave-Approval-Engine, DE-Feiertage, Calendar-Modell, gesamtes UI | M133–M140 |
| **M19** KWP-Integration | 🟡 medium | Apps-Engine-Schema (DataConnection/AppSyncRun), gehashte API-Keys, Idempotenz, Storage, Worker-Cron, Webhook-Pattern | echtes Adapter-Interface (=M33a!), KWP-Modelle, Sync-/Konflikt-/Drift-Logik, gesamtes UI; **API-Variante vereinfacht stark** | M089–M095 |
| **M20** Dashboard / Reporting | 🟡 medium | Tenant-Dashboard-Route, dashboard-registry (Gating), Stat-DTO (Drill-Down), Export-Infra (PDF/CSV), Realtime/SSE, Recharts | Widget-/Layout-Engine, WidgetCatalog, Drag&Drop-Grid (react-grid-layout fehlt!), Aggregat-Cache, 7 Rollen-Layouts | M147–M150 |
| **M21** Audit-Log (Anzeige) | 🟡 medium | AuditEvent (Hash-Chain) ~70%, Write-Path, verifyAuditChain, Export-Pipeline (audit-pdf/csv), Retention-Cron | Diff-Felder (before/after), summary_text, AuditRetentionPolicy+Legal-Hold, Saved-Views, gesamte Anzeige-UI, Prisma-Middleware | M151, M152 |
| **M22** Notifications (3-Kanal) | 🟡 medium | In-App-Slice (DB→SSE→Center), Push-Pipeline (FCM/APNs/WebPush), DeviceToken, BullMQ-Queue, Mail-Stack | reiches Notification-Aggregat, Bundle/QuietHours-Modelle, PUSH-Enum, Bundle-/Quiet-Hours-Logik, fast alle UI | M115–M117 |
| **M23** Files / Dokumentenablage | 🟡 medium | packages/storage (S3/Scaleway, SigV4, Tenant-Isolation, ClamAV-Pipeline, Magic-Bytes) — sehr reif | File/Version/EntityLink-Modelle, Chunked-Upload+Resume, Preview/Thumbnail (keine Libs!), OCR/Suche, gesamtes UI | M052–M055 |
| **M24** Globale Suche (Cmd+K) | 🟡 medium | packages/search (Index/Outbox/Fallback), EU-Embeddings (Scaleway 1024d), pgvector tenant-scoped, RAG-Indexer, CommandPalette | FTS-Pfad (BP=Meilisearch!), Hybrid-RRF-Fusion, SearchIndexEntry-Modell, Permission-Query-Filter, Domain-Adapter | M056–M058 |
| **M26** Tasks / Aufgaben | 🟡 medium* | Querschnitt reif (Notify+Push/Email, Outbox, RBAC+Groups, Cron), shadcn-Tabellen, appsEngine (ERP-Sync) | Task-Modell (RowTask ist Falle!), TaskWatcher, Reminder-Anti-Spam, Listen/Detail/Archiv-Logik, ERP-Sync | M071–M074 |
| **M33a** Apps-Engine / Adapter | 🟡 medium | appsEngine.prisma (5 Modelle, App/DataConnection/AppSyncRun), AES-Crypto, Queue, HMAC-Webhook, Probe-Scheduler-Pattern | Adapter-Interface, 5-Status-State-Machine, Setup-Wizard, Probe-Scheduler, Webhook-Sturm-Schutz, Schema-Drift | M008–M010 |
| **M34** Public-API & Webhooks | 🟡 medium | dediziertes apps/api (Hono, OpenAPI, API-Key/Scope-Auth, Error-Envelope, ApiKeyLog), signierte Webhook-Delivery+Backoff | typisierte Read-Endpoints, Cursor-Pagination, 5 Webhook-Modelle, X-RateLimit-Header, Swagger-UI, Event-Katalog | M161–M163 |
| **M35** DSGVO-Export / Löschung | 🟡 medium | User-Level-DSGVO komplett (Export/Delete/Grace/Pseudonymize), USER_FK_MAP, Streaming-Export-Framework, Privacy-Hub | gesamte Tenant-Ebene, ZIP-mit-Binär-Bundling, AVV-PDF+Subprozessoren, Tenant-Lifecycle, Tenant-Hard-Delete-Cron | M164–M166 |
| **M36** Mobile-App (Capacitor) | 🟡 medium | Capacitor-7-Wrapper komplett, Push-Pipeline serverseitig, Session-Persist, Sentry, Permission-Strings | Offline-Modus (IndexedDB/Queue), Biometrie/Face-ID, Camera/Network-Plugins, Apple/Google-Compliance, Force-Update | M167–M171 |
| **M37** Plattform-Admin | 🟡 medium | Admin-Subdomain-Routing, AdminSidebar, MFA-Step-up, ImpersonationAudit+Banner, RBAC, KPIs, Stripe-Stack, Lead-Inbox | **getrennte AdminUser-Identität (Spec verlangt, BP verletzt!)**, AdminSession (IP-Bind), AdminDeal/Pipeline, ui-hivegrid | M034–M041 |
| **M38** Help-Center (öffentlich) | 🟡 medium | komplettes KB-System (Routes/Suche/SEO/Feedback/Markdown-Render/RAG) — als Vorlage | file-/build-basierter Daten-Layer (BP=DB-getrieben!), Build-Index+Sitemap, Frontmatter-Validierung | M172, M173 |
| **M39** Help-Desk / Support | 🟢 high | Feedback+SupportTicket-Modelle, Service/DB-Layer, In-App-Widget, PII-Redaction, Admin-Bereich, Sliding-Rate-Limiter | Detail-View, Status/Assignee/Notes/Attachments, reichere Liste, Browser-Info/Screenshot, Permission-Keys | M174, M175 |
| **M31** Branding / Theme | 🟡 medium | Light/Dark-Basis (binär), Capacitor-Status-Bar/Splash, Tenant.themeConfig+Parser, ~20 Themes, settings/theme-Route | 3-Wert-Theme (system), prefers-color-scheme, matchMedia-Listener, TenantBranding-Tabelle (Phase 2) | M030 |
| **M03** Sales-Pipeline | 🔴 low | Querschnitt 1:1, @dnd-kit (vorhanden!), SSE (kein WS), EntityView-board-Pattern, Row.folio-Sequenz, BullMQ-Cron | Deal/Pipeline/Stage/Forecast komplett neu, Stage-Engine, Won-Handoff, Field-Level-Volumen-Redaction, Stuck-Detection | M059–M064 |
| **M04** Auftrags-/Projektpipeline | 🔴 low | DB-Layer, RBAC+Groups, Notify+Push-Worker, appsEngine (KWP), @react-pdf, @dnd-kit, App-Shell | alle 8 Kern-Modelle neu, **Plantafel-Grid (kein Lib!)**, signature_pad (fehlt!), Abnahme-State-Machine, Konflikt-Detektor | M065–M070 |
| **M06** Booking (Calendly) | 🔴 low | Querschnitt, handlebars (Template-Engine!), Redis-Cache, Form-Widget, Lead, Site (booking), shadcn-Calendar | gesamtes Booking-Modell, Slot-Engine, EXCLUDE-gist-Doppelbuchungsschutz, Public-Flow, .ics, Calendar-Sync (M25 fehlt!) | M126–M129 |
| **M07** Angebot + e-Signatur | 🔴 low | defineAdapter, SSRF-outbound-http, Stripe/MailerSend-Webhook als Blaupause, appsEngine (OAuth), Storage, Outbox | PandaDoc/DocuSign-Adapter, 5 Signatur-Modelle, **hängt an M3-Deal-Modell**, Inbound-Webhook-Routen, 5-Schritt-Wizard | M130–M132 |
| **M13** Team-Chat (intern) | 🔴 low | Querschnitt (Notify/Permissions/Audit/Storage+AV), RowComment-Muster, realtime-Client (Reconnect), hocuspocus-Blueprint | 7 TeamChat-Modelle, **generischer WebSocket-Room-Layer (realtime=SSE!)**, Mention-Resolver, Link-Previews, gesamtes UI | M110–M114 |
| **M15** Customer-Portal | 🔴 low | Querschnitt (Auth-Primitiven, Storage+ClamAV, Mail, DSGVO, Rate-Limit), TenantUser-Auth als Referenz | gesamte CustomerPortal-Datenebene, **kein Session-Modell!**, getrennte PortalUser-Auth, alle Endkunden-Views | M141–M146 |
| **M25** Calendar-Sync (Google/MS) | 🔴 low | Querschnitt, AES-Crypto, SSRF-http, Outbox+Cron, HMAC-Webhook-Pattern, defineAdapter, appsEngine (Feld-Vorlage) | 5 Calendar-Modelle, CalendarAdapter, Google/MS-Adapter (kein googleapis/Graph!), OAuth2-Flow, Sync, Verfügbarkeit | M118–M120 |
*M14/M26 sind grenzwertig low→medium (starker Querschnitt, Domäne neu); M37 medium mit blockierender Architektur-Entscheidung.
---
## Gruppierung nach Reuse-Level (Quick-Wins zuerst)
### 🟢 HIGH — Quick-Wins (Fundament aktivieren + Inhalte füllen)
- **M00 Querschnitt-Foundation** — Pre-Flight für *alles*; ~80–90 % fertig. Vier echte Neubauten (`logActivity`, indexed-entities, Subframe-Adapter, Mass-Action) + Naming-Drift-Fix.
- **M30 i18n** — Mechanik komplett; 3 DB-Felder + TR/PL + 2 Resolver-Schritte.
- **M27 Auth/Tenancy/RBAC** — fast vollständig; 3 echte Architektur-Neubauten (Postgres-Sessions, RLS, Lifecycle-Status).
- **M28 Billing** — Datenmodell+Stripe+Pricing+Overage fertig; Lifecycle/Seat/Read-Only neu. **Achtung Apple-Compliance LP-8.**
- **M17 Automation-Engine** — Engine 1:1; Domänen-Trigger/Actions + USP-Mechaniken + Layer-Umbau.
- **M18 KI-Layer** — EU-Stack+RAG+Promptfoo+Overage fertig; Whisper + Sanitizer + Sprach-zu-Automation + UI.
- **M39 Help-Desk** — fast komplettes Phase-1-Modul; Anpass-/Erweiterungsaufgabe.
### 🟡 MEDIUM — solides Fundament + Vorlagen, Domänen-Kern neu
M01 CRM, M02 Lead-Inbox, M05 Form-Builder, M09 Email-Inbox, M10 Email-Marketing, M12 Telefonie, M14 HR-Hub, M19 KWP, M20 Dashboard, M21 Audit-Anzeige, M22 Notifications, M23 Files, M24 Suche, M26 Tasks, M31 Branding, M33a Apps-Engine, M34 Public-API, M35 DSGVO, M36 Mobile, M37 Plattform-Admin, M38 Help-Center.
### 🔴 LOW — Greenfield-Fachdomäne (Querschnitt + Bau-Vorlagen, Kern neu)
M03 Sales-Pipeline, M04 Auftrags-/Projektpipeline, M06 Booking, M07 Angebot/Signatur, M13 Team-Chat, M15 Customer-Portal, M25 Calendar-Sync.
> **Es gibt kein „none".** Selbst die low-Module profitieren erheblich vom Querschnitt + konkreten Bau-Vorlagen.
---
## Querschnitt-Foundation (M00) — Status separat
**Reuse-Level: HIGH, code-verifiziert (nicht nur Inventur).** Fast die gesamte Querschnitt-Hülle existiert als lauffähige, getestete Patterns + CI-Gates:
| Baustein | Status | Quelle |
|---|---|---|
| M001 Audit (Hash-Chain pro Tenant) | ✅ 1:1 | `foundation/src/audit.ts` + `db/src/audit-events.server.ts` |
| M002 Klartext-Diagnostik (CatalogError) | ✅ Engine fertig, `catalogRegistry` **leer** (HiveGrid füllt) | `foundation/src/errors.ts` |
| M003 i18n-Pflicht | ✅ 1:1 + CI-Gate | `packages/i18n` + `verify:i18n` |
| M004/M005 Tenant-Scope/Owner-Check/404-statt-403/SSRF | ✅ 1:1 | `foundation/src/permissions.ts` + `outbound-http.ts` |
| M006 Feature-Flag-Engine | ✅ 1:1 (v2: Targeting/Cache/Hooks) | `packages/feature-flags` |
| M007 Idempotenz-Wrapper | ✅ 1:1 | `foundation/src/idempotency.ts` |
| M008–M010 Apps-Engine-Adapter + State-Machine | ⚠️ Registry+Status-Enum da, **Interface+State-Machine neu** (=M33a) | `foundation/src/adapters.ts` + `appsEngine.prisma` |
| M011 Notification-Service | ✅ 1:1 | `foundation/src/notifications.ts` |
| M012–M014 Workspace/View-Model/Action-Contract | ✅ 1:1 | `packages/view-models` |
| M015 Subframe-Adapter | ❌ **nur leere Boundary, Adapter-Code fehlt** | `packages/ui-subframe` |
| M016/M017 Visual-Regression + Hot-Swap-Drill | ✅ 1:1 + CI-Gates | `packages/ui-mock` + `ci.yml` |
**Vier echte M00-Neubauten:** (1) `logActivity()`/Activity-Stream (distinkt vom Audit), (2) Search-indexed-entities-Registry (falscher AGENTS-Pfad), (3) Subframe-Adapter-Code, (4) Mass-Action-Schutz. **Plus durchgängiger Naming-Drift** (`ui-hivegrid`/`@hivegrid/*` vs. Realität) — Phase-0-Pflicht.
---
## KWP (M19) — API-Anbindungs-Auswirkung (hervorgehoben)
**Stand 2026-06-04: Mit der NEUEN offiziellen KWP-API kippt die Architektur von 3 auf 2 Komponenten** — aus `Cloud ↔ kwpsync.exe ↔ MSSQL` wird `Cloud ↔ KWP-API`. Das verändert den Milestone-Schnitt erheblich:
| Milestone | Auswirkung der KWP-API |
|---|---|
| M089 (Sync-Programm / kwpsync.exe) | **ENTFÄLLT** (kein Windows-Client, kein MSSQL-Treiber, kein NSSM/DPAPI/Auto-Update mehr) |
| M090 (Heartbeat + Recovery) | **stark vereinfacht** → generischer M33a-Health-Probe |
| M091 (Warteschlange + Replay) | **vereinfacht** — lokale SQLite-Queue entfällt, nur Cloud-Outbox bleibt |
| M092 (Schema-Drift-Sentinel) | **vereinfacht bis ENTFÄLLT** → API-Versions-/Contract-Check (zod-Response-Validierung) |
| M093 (Konflikt „KWP gewinnt") | **BLEIBT unverändert** — transport-unabhängige Domain-Regel |
| M094 (Plantafel-Sync) | **vereinfacht** via API-Endpoints/Webhooks |
| M095 (Dokumenten-Archiv-Sync) | **vereinfacht** via API-Endpoints/Webhooks |
**Netto:** Aufwand sinkt deutlich. Bei API-Variante passt `DataConnection.type='rest-api'/'oauth2'` **nahtlos** ins generische Apps-Engine-Muster (statt `windows_client`-Sonderweg) — das **hebt das faktische Reuse-Level Richtung medium-high**. **Empfehlung:** M089–M095 vor Umsetzung gegen die API **neu schneiden**. Harte Vorbedingung bleibt **M008–M010 (M33a Adapter-Interface)**.
---
## Empfohlene Übernahme-Reihenfolge (gemäß Cluster-Reihenfolge der Planung)
### Phase 0 — Pre-Flight (blockierend, vor jedem Fachmodul)
1. **Boilerplate als Code-Basis einziehen** (HiveGrid-Repo ist heute Docs-only). AGENTS Pre-Flight-Check schlägt sonst fehl.
2. **Naming-Drift beheben:** `@toolctrl/*` → `@hivegrid/*`, `ui-app`-Stub → `ui-hivegrid`, Sidebar-Konvention, AGENTS-Pfade (`indexed-entities.ts`, `sidebar.config.ts`) korrigieren.
3. **EU-Sterilisation:** OAuth-GitHub/Google-Login-Reste entfernen (M27), Anthropic/OpenAI-Embedding-Stubs deaktiviert lassen (M18, DSGVO-Hard-Constraint).
4. **M00 aktivieren:** foundation/view-models/i18n/feature-flags 1:1 + CI-Gates verdrahten. Die 4 echten Neubauten (`logActivity`, indexed-entities-Registry, **Subframe-Adapter** [Quer-Voraussetzung für alle UI], Mass-Action-Schutz) anlegen.
### Phase 1 — Plattform-Fundament (high reuse, ermöglicht alles Weitere)
5. **M27 Auth/Tenancy/RBAC** — inkl. 3 Architektur-Neubauten (Postgres-Sessions, **RLS**, Lifecycle-Status). Vorbedingung für *alle* tenant-scoped Module.
6. **M30 i18n** + **M31 Branding** (Quick-Wins, klein).
7. **M28 Billing** (Lifecycle/Seat/Read-Only; Apple-LP-8 beachten).
8. **M32 Feature-Flags-Admin**, **M33a Apps-Engine** (Adapter-Interface — Vorbedingung für M07/M09/M12/M19/M25), **M34 Public-API**.
### Phase 2 — Daten-Kern (Cluster „CRM-Fundament")
9. **M01 CRM-Kern** — Contact/Company/Lead als typisierte Tabellen; **Boilerplate-Entity-Builder-CRM entfernen**. Vorbedingung für M02/M03/M07/M09/M12.
10. **M23 Files**, **M24 Suche** (FTS-Architektur-Entscheid), **M26 Tasks**, **M22 Notifications**, **M21 Audit-Anzeige**.
### Phase 3 — Vertriebs-/Auftrags-Kette (Cluster „Sales→Projekt")
11. **M02 Lead-Inbox** → **M03 Sales-Pipeline** (low, Greenfield) → **M04 Auftrags-/Projektpipeline** (low, Plantafel-Neubau) → **M07 Angebot/Signatur** (hängt an M3-Deal).
### Phase 4 — Kommunikation & Termine
12. **M05 Form-Builder**, **M06 Booking**, **M25 Calendar-Sync** (low; M25 ist harte Vorbedingung für M06-Verfügbarkeit), **M09/M10 Email**, **M12 Telefonie**, **M13 Team-Chat** (WebSocket-Layer neu).
### Phase 5 — USP & Integration
13. **M17 Automation-Engine** (high; nach Domänen-Events der Vormodule), **M18 KI-Layer** (high), **M19 KWP** (gegen API neu schneiden).
### Phase 6 — Endkunden & Plattform-Betrieb
14. **M14 HR-Hub**, **M15 Customer-Portal** (low), **M20 Dashboard** (nach Domänen-Modulen), **M29 Onboarding**, **M35 DSGVO** (Tenant-Ebene), **M36 Mobile**, **M37 Plattform-Admin**, **M38 Help-Center**, **M39 Help-Desk**.
---
## Risiken / Offene Fragen
### Architektur-Risiken (blockierend)
- **R1 — Naming-Drift:** Ohne Rename greifen *alle* DoD-Pfade ins Leere. Höchste Priorität (Phase 0).
- **R2 — Postgres-RLS fehlt (M27/A.4):** Boilerplate macht nur App-Level-Scoping. RLS-Migration + `SET LOCAL app.tenant_id` + App-Role ohne BYPASSRLS + Worker-Job-Context komplett neu — Sicherheits-Fundament.
- **R3 — Kein Session-Prisma-Modell (M27/M15):** Weder TenantUser noch PortalUser haben server-side Postgres-Sessions (BP=Cookie-only). Betrifft M021 + das gesamte Customer-Portal.
- **R4 — AdminUser-Identität (M37):** Spec 37.1 verlangt vollständig getrennte AdminUser/AdminSession/AdminRole/AdminAuditLog; BP nutzt User-Extension + dasselbe RBAC + Authentik-OIDC. **Blockierende Entscheidung vor M034:** spec-treu neu bauen vs. Change-Request.
- **R5 — CRM-Architektur-Konflikt (M01):** BP-CRM ist Entity-Builder (Entity+Row+RowValue), Spec verlangt typisierte First-Class-Tabellen. **BP-CRM entfernen, nicht anpassen** — sonst sickert fremde Architektur ein.
- **R6 — Operator-scoped Lead (M02/M06/M37):** `marketingLeads.Lead` ist operator-scoped (globales `@@unique([email])`, Funnel-Status). Der tenant-scoped HiveGrid-CRM-Lead gehört fachlich zu M01 und muss neu — NICHT mitbenutzen.
### Technische Risiken
- **R7 — Subframe-Adapter fehlt (M15-Querschnitt):** Pflicht für jede UI-Route (User-Memory), aber nur leere Boundary. Quer-Voraussetzung.
- **R8 — realtime = SSE, kein WebSocket:** Präjudiziert M03 (Live-Kanban) und blockiert M13 (Team-Chat braucht generischen WS-Room-Layer). hocuspocus ist CRDT, kein Chat-Broadcast.
- **R9 — Fehlende Dependencies (PLAN.md falsch):** `signature_pad`, `browser-image-compression`, `react-grid-layout`, `kbar`, `next-themes`, `libphonenumber`, `googleapis`/`@microsoft/microsoft-graph`, `ics/ical-generator`, `EXCLUDE USING gist/btree_gist` — alle NICHT vorhanden. Vor Bau ergänzen.
- **R10 — Apple-Compliance (M28/M36, LP-8):** Fertige BP-Pricing/Upgrade-UI darf NICHT in die Mobile-App. Größtes Anti-Risiko bei Billing.
- **R11 — Suche-Architektur (M24):** BP=Meilisearch+SQL-ILIKE, Spec=Postgres-FTS+pgvector-RRF-Fusion. Phase-0-Entscheid nötig (FTS-Pfad + Fusion komplett neu).
- **R12 — Per-Tenant-KMS fehlt (M14/M25):** CryptoApi ist Single-Env-Key. Spec verlangt Per-Tenant-DEK/KMS (Password-Safe, OAuth-Tokens).
### Offene fachliche Fragen (für User/Noah)
- **F1:** EU-SMTP-Provider final wählen (M10/M22) — MailerSend ist nicht-EU (LP-13-Konflikt); Scaleway TEM evaluieren.
- **F2:** Captcha-Provider — BP=Cloudflare Turnstile, Spec=hCaptcha (EU). Tausch nötig (M05/M125).
- **F3:** KWP-API-Verfügbarkeit/Vertrag bestätigen → M089–M095 neu schneiden.
- **F4:** SHK-Custom-Field-/Tag-Defaults + 7-10 SHK-Rollen-Template finalisieren (M01/M27/M29 — deklaratives Seeding).
- **F5:** Idempotenz-Strategie Stripe-Webhook (M28): StripeWebhookLog-Tabelle (Spec) vs. Outbox-dispatchKey (BP) — Konflikt klären.
- **F6:** Saved-Searches Phase 1 vs. 2 (M24); `url/email` als eigene field_type vs. Validierung (M01); Activity-Tabelle vs. Audit-Wiederverwendung (M01/M45).