# 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//{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.