toolctrl-labs/HiveGrid-Wireframes
9
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e341c5938ac25ff069732732835837de3d39d5e1
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M29-onboarding.md
T

16 KiB
Raw Blame History

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.

Reference in new issue View Git Blame Copy Permalink