Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M29-onboarding.md
T
2026-07-08 16:15:37 +02:00

25 KiB

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
29 Onboarding 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-3
LP-7
LP-9
LP-10
requirements-pur

Modul 29 — Onboarding

Detail-Spec gemäß LP-9. Branchen-getriebenes Onboarding nach Self-Service-Signup. Phase 1 nur SHK-Templates voll implementiert; andere Branchen sichtbar als „Coming soon" (LP-3). Branchen-Templates deklarativ abgelegt (LP-3 + AV #3) — neue Branche = neues Verzeichnis mit Template-Dateien, kein Code-Patch.

Themenblöcke

A. Datenmodell
B. Wizard-Flow nach Signup
C. Branchen-Templates (deklarativ)
D. Smart-Setup pro Branche (SHK Phase 1)
E. Demo-Daten-Provisioning
F. Erste-Schritte-Checkliste
G. Mitarbeiter-Einladung (Verweis M27)
H. KI-Walkthrough
I. Routes
J. Permissions-Anwendung
K. Klartext-Hinweise/-Fehler
L. Phase 2 / Backlog

Block A — Datenmodell

Onboarding

Globale Definition eines Onboarding-Pfads (z.B. „SHK-Standard", „Maler" — Phase 2).

  • id (UUID)
  • code (unique, snake_case — z.B. shk_standard)
  • display_name, description
  • industry_code (Enum: shk | elektro | maler | sanitaer | tischlerei | dachdecker | ...)
  • is_active (Boolean — false = „Coming soon")
  • version (Semver — Templates können versioniert werden)
  • template_directory_path (string — Pfad zum deklarativen Template-Verzeichnis)
  • created_at, updated_at

OnboardingFilter

Filter-Bedingungen, die ein Onboarding-Pfad selektieren können (Branche + Größe + ggf. weitere).

  • id, onboarding_id (FK)
  • criterion_key (z.B. industry, company_size, tenant_type)
  • operator (Enum: equals | in | greater_than | less_than)
  • criterion_value (JSON)

OnboardingStep

Ein einzelner Schritt im Wizard.

  • id, onboarding_id (FK)
  • code (z.B. firmendaten, branche, groesse, logo, seed_demo_data, complete)
  • display_name, description
  • step_type (Enum: info | form | action | confirmation)
  • position (Integer — Sortierung)
  • is_skippable (Boolean)
  • validation_rules (JSON — Pflichtfelder, Format-Constraints)
  • action_handler (string — Code-Referenz für action-Steps, z.B. seed_shk_demo_data)

OnboardingSession

Eine konkrete Onboarding-Durchführung pro Tenant.

  • id, tenant_id (FK, unique während Phase 1 — ein aktives Onboarding pro Tenant)
  • onboarding_id (FK)
  • started_at, completed_at (nullable)
  • current_step_id (FK auf OnboardingStep)
  • status (Enum: in_progress | completed | abandoned)
  • started_by_user_id
  • payload (JSONB — alle gesammelten Antworten)

OnboardingSessionAction

Log der Aktionen während einer Session (Audit + Replay).

  • id, onboarding_session_id
  • step_id, action_type (Enum: step_entered | step_completed | step_skipped | data_saved | external_call)
  • payload (JSON)
  • created_at, actor_user_id

OnboardingSessionFilterMatch

Welche Filter haben gegriffen, als das Onboarding zugeordnet wurde.

  • id, onboarding_session_id
  • onboarding_filter_id
  • matched_value (JSON)

OnboardingSessionStep

Detail-Status pro Step in einer Session.

  • id, onboarding_session_id, step_id
  • status (Enum: pending | in_progress | completed | skipped)
  • completed_at
  • submitted_data (JSON)

OnboardingDemoProvisioning

Tracking der Demo-Daten-Ausrollung.

  • id, tenant_id, onboarding_session_id
  • template_code (z.B. shk_demo_v1)
  • provisioned_at
  • entities_created (JSON — z.B. {"contacts": 12, "deals": 5, "projects": 3, "pipelines": 2, ...})
  • provisioning_log (Markdown — Klartext, was angelegt wurde)
  • removable_until (Timestamp — z.B. 30 Tage Grace, danach werden Demo-Daten Teil des realen Bestands)

OnboardingInvitationDispatch

Tracking der Mitarbeiter-Einladungen (Verbindung zu M27 D.1 TenantUserInvitation).

  • id, tenant_id, onboarding_session_id
  • tenant_user_invitation_id (FK auf M27)
  • dispatched_at, dispatched_by_user_id
  • bulk_batch_id (für CSV-Bulk-Einladungen — Phase 2)

Indizes

  • OnboardingSession: unique on (tenant_id, status='in_progress') (nur eine aktive Session)
  • OnboardingSessionAction: Index auf (onboarding_session_id, created_at)

Sonderfälle

  • Onboarding-, OnboardingStep-, OnboardingFilter-Daten sind global (kein tenant_id) — sie sind Plattform-Konfiguration aus Templates geseeded
  • OnboardingSession, OnboardingDemoProvisioning, OnboardingInvitationDispatch sind tenant-scoped mit RLS
  • Branchen-Templates können per Migration / Seeding aus Konfigurations-Verzeichnissen geladen werden — siehe Block C

Block B — Wizard-Flow nach Signup

Aufruf-Pfad

  1. User schließt Self-Service-Signup ab (M27 A.1) → Tenant + Legacy-Provider-Subscription angelegt (M28)
  2. Bei erstem Login auf Tenant-Slug-Route: Auto-Redirect nach /onboarding/setup/
  3. Wizard läuft → bei Abschluss Redirect nach /{tenant}/

Schritte (Phase 1, SHK-Default)

Step Inhalt Pflicht
1 — Willkommen Klartext-Begrüßung, Vorschau auf nächste Schritte, geschätzte Dauer — (nur Info)
2 — Firmendaten bestätigen Firmenname (aus Signup), Slug (aus Signup, read-only), USt-Id editierbar, Adresse ✓
3 — Branche bestätigen SHK pre-selected (aus Signup); andere Branchen sichtbar mit „Coming soon"-Hinweis und disabled ✓
4 — Größe bestätigen Dropdown 1-10 / 11-25 / 26-50 / 51-100 / 100+ (aus Signup) ✓
5 — Logo (optional) Upload-Funktion mit Format-Hinweis (PNG/SVG, max. 2 MB) optional
6 — Smart-Setup-Vorschau Klartext: „Wir richten für dich folgendes ein: [Liste der SHK-Templates]" mit Toggle pro Template-Gruppe ✓ (mind. Default-Auswahl bestätigen)
7 — Demo-Daten Klartext: „Sollen wir Beispiel-Daten anlegen, damit du sofort etwas siehst?" — Default ja, Toggle optional
8 — Mitarbeiter einladen Inline-Formular „Email + Rolle"-Paare, beliebig viele Zeilen, „Später"-Skip-Button optional
9 — Erste-Schritte-Liste Klartext-Erklärung der Checkliste, kein Eingabe-Schritt — (nur Info)
10 — Fertig Klartext-Bestätigung, Direkt-Link ins Tenant-Dashboard, Hinweis auf KI-Walkthrough —

Wizard-Verhaltensregeln

  • Resumable: bei Abbruch (Browser-Schließen, Logout) → bei nächstem Login zurück zum letzten Step
  • Step-Skip: falls is_skippable=true → Skip-Button mit Klartext-Hinweis
  • Validation pro Step: vor step_completed-Eintrag
  • Progress-Indikator: Anzahl abgeschlossener Steps / Gesamt
  • Rückwärts-Navigation: möglich bis zum Step-Typ action (irreversible Aktionen wie Demo-Daten-Provisioning blocken Rückwärts-Navigation)

Erst-Login-Detection

  • Beim ersten Login auf Tenant-Slug-Route: prüfen OnboardingSession mit status='completed' für diesen Tenant
  • Falls keine Session: Auto-Start
  • Auto-Match-Filter (OnboardingFilter) bestimmt welches Onboarding zugewiesen wird (Phase 1: nur shk_standard aktiv)

Block C — Branchen-Templates (deklarativ)

Verzeichnis-Struktur

Pro Branche ein Verzeichnis, geseeded beim Tenant-Anlegen je nach Branche:

/templates/onboarding/
  /shk/
    onboarding.yml              → OnboardingDefinition + Steps + Filter
    pipelines/
      sales.yml                 → Sales-Pipeline-Stages
      project.yml               → Projekt-Pipeline-Stages
    forms/
      sales-aufnahme.yml
      foto-checkliste.yml
      acceptance-protokoll.yml
    custom-fields/
      contact.yml               → SHK-spezifische Custom-Felder für Contacts
      company.yml
      lead.yml
    permissions/
      roles.yml                 → Default-Rollen-Definitionen (siehe M27 C.2)
    demo-data/
      contacts.yml
      companies.yml
      deals.yml
      projects.yml
      ...
    checklist/
      first-steps.yml           → Erste-Schritte-Checkliste-Items
  /elektro/                     → Phase 2
  /maler/                       → Phase 2
  ...

Template-Dateiformat

YAML mit deklarativer Struktur. Beispiel shk/onboarding.yml:

code: shk_standard
display_name: SHK / Sanitär-Heizung-Klima
industry_code: shk
is_active: true
version: 1.0.0
filters:
  - criterion_key: industry
    operator: equals
    value: shk
steps:
  - code: welcome
    type: info
    position: 1
  - code: company_data
    type: form
    position: 2
    fields: [name, slug, vat_id, address]
  ...

Lade-Logik

  • Beim System-Start (oder in Migrations-Skript): Template-Verzeichnisse einlesen, in Onboarding/OnboardingStep/OnboardingFilter synchronisieren
  • Beim Tenant-Anlegen mit Branche=X: assoziiertes Onboarding wird als OnboardingSession gestartet
  • Smart-Setup ausführen = Template-Dateien aus dem Branchen-Verzeichnis abarbeiten und auf Tenant-Daten übertragen

Phase-1-Status

  • Nur shk aktiv und vollständig implementiert
  • Andere Branchen-Codes (elektro, maler, etc.) im Frontend sichtbar als „Coming soon"-Optionen mit is_active=false ihrer Onboarding-Records
  • Bei Auswahl einer „Coming soon"-Branche: Klartext-Hinweis im Signup-Formular „Diese Branche ist noch in Vorbereitung. Wir richten dir vorerst die SHK-Konfiguration ein, du kannst alles anpassen."

Block D — Smart-Setup pro Branche (SHK Phase 1)

Sales-Pipeline-Stages (Default)

Vorgeschlagene Stages für SHK (siehe Modul 3):

  • Anfrage
  • Besichtigung geplant
  • Angebot erstellt
  • Verhandlung
  • Gewonnen
  • Verloren

Projekt-Pipeline-Stages (Default)

Vorgeschlagene Stages (siehe Modul 4):

  • Angenommen
  • Materialbeschaffung
  • Vorbereitung
  • Ausführung
  • Abnahme
  • Abgeschlossen

Form-Templates (Default — siehe Modul 5)

  • Sales-Aufnahme (Vor-Ort-Datenerfassung Vertriebler): Anlagen-Typ, Verbrauch, Dachfläche/Heizfläche, Foto-Bestand
  • Foto-Checkliste (Monteur-Pflicht): Vor-Bild Anlage, Anschluss, Mess-Punkte, Nach-Bild
  • Acceptance-Protokoll (Abnahme): Funktionsprüfung-Items, Mängel-Aufnahme, Kunden-Signatur (siehe Modul 7)

Custom-Felder (siehe Modul 1 Block F SHK-Defaults)

  • Contact: Heizungsanlage Hersteller, Heizungsanlage Modell, Letzte Wartung, Wartungsvertrag
  • Company: Anzahl Anlagen, Vertragsklasse
  • Lead: Anlagen-Typ Interesse

Standard-Permissions pro Rolle (siehe M27 C.2 — 7 SHK-Rollen)

  • GF / Geschäftsführer
  • Vertriebsleiter
  • Vertriebler
  • Projektleiter / Bauleiter
  • Büro / Backoffice
  • Marketing
  • Monteur

Geseeded mit Default-Permission-Bundles aus dem SHK-Template.

Provisioning-Reihenfolge

  1. Pipelines (Sales + Projekt)
  2. Custom-Felder
  3. Rollen + Permissions
  4. Form-Templates
  5. Erste-Schritte-Checkliste
  6. (Optional) Demo-Daten

Bei Fehler in einem Schritt: Rollback der bisherigen Seedings, OnboardingSessionAction.action_type = external_call mit Klartext-Fehler, Tenant-Admin sieht Step als „fehlgeschlagen" mit Retry-Button + Plattform-Admin-Alert.

Konfigurierbarkeit nach Setup

  • Alle geseedeten Daten sind nach Setup vom Tenant-Admin vollständig editierbar (umbenennen, löschen, neue anlegen)
  • Kein „Locked Template"-Konzept

Block E — Demo-Daten-Provisioning

Konzept

User landet nicht in einer leeren App, sondern in einer „lebendigen": vorkonfigurierte Beispiel-Kontakte, Beispiel-Deals in verschiedenen Stages, Beispiel-Projekt mit aktivem Chat.

Default-Demo-Daten (SHK)

  • ~10 Beispiel-Contacts (Mix aus Privat-/B2B)
  • ~3 Beispiel-Companies
  • ~5 Beispiel-Deals in unterschiedlichen Stages
  • 1 Beispiel-Projekt im Stage „Ausführung" mit Chat-Verlauf, Tasks, Foto-Checkliste
  • 1 Beispiel-Lead in Inbox
  • ~5 Beispiel-Files (PDFs, JPGs)
  • Tags-Beispiele
  • Beispiel-Booking-Page mit Verfügbarkeit

Identifikation

  • Alle Demo-Daten haben Flag is_demo_data = true auf der jeweiligen Entity (Phase-1-Konvention)
  • Filter-Toggle in allen relevanten Listen-Views: „Demo-Daten ausblenden"
  • OnboardingDemoProvisioning.removable_until = +30 Tage; danach werden Demo-Daten nicht automatisch gelöscht, sondern bleiben als reguläre Daten (User kann sie manuell löschen)

Bulk-Lösch-Funktion

In /{tenant}/admin/onboarding/demo-data/:

  • Anzeige aller Demo-Entities mit Anzahl
  • „Alle Demo-Daten löschen"-Button mit Multi-Step-Confirm
  • Permission: tenant.admin

Klartext beim Wizard

  • Step „Demo-Daten": „Wir legen Beispiel-Kontakte und ein Beispiel-Projekt an, damit du sofort siehst wie HiveGrid funktioniert. Du kannst sie jederzeit löschen." — Default-Toggle „Ja"

Block F — Erste-Schritte-Checkliste

Konzept

Sichtbar im Tenant-Dashboard nach Wizard-Abschluss (siehe Modul 20). Status-getrackt, expandierbar.

Default-Items (SHK Phase 1)

Item Status-Erkennung
KWP-Connection einrichten KwpSettings.connection_active = true
Mailbox verbinden EmailIntegrationMailbox-Eintrag mit status=active
AirCall verbinden TelephonyConnection.status = active mit provider=aircall
Booking-Page anlegen Existenz mind. einer BookingPage
Mitarbeiter einladen Mind. 1 TenantUserInvitation versendet
Erste Automation testen Mind. 1 AutomationRule aktiviert mit executions_count > 0
Erste Form anlegen Mind. 1 nicht-Template Form
Erste Sales-Pipeline-Bewegung Mind. 1 Deal.stage_change-Event

Datenmodell-Anbindung

Jedes Checklist-Item ist deklarativ in shk/checklist/first-steps.yml definiert mit:

  • code, display_name, description
  • detection_rule (Code-Referenz oder DSL für Status-Auswertung)
  • position, is_dismissible (User kann manuell als „erledigt" markieren)
  • cta_link (Direkt-Link in den entsprechenden Modul-Bereich)

Status-Tracking

  • Bei jedem relevanten Event (Mailbox verbunden, Form angelegt, etc.): Auswertung der Detection-Rules + Update einer in-memory-cache-Zwischenschicht
  • Tenant-Admin kann die Checkliste dauerhaft ausblenden (Setting dashboard_show_first_steps = false)
  • Nach 100% Erledigung: Automatisches Ausblenden mit Klartext-Glückwunsch „Alle Erste-Schritte erledigt — viel Erfolg mit HiveGrid!"

UI-Anbindung

In Modul 20 (Dashboard) als eigenständiger Widget:

  • Liste der Items mit Status-Icon (erledigt / offen)
  • Pro Item: Klartext-Titel + Beschreibung + CTA-Link
  • Aufklappbar / einklappbar
  • Manuell als „erledigt" markierbar

Permission: jeder authentifizierte Tenant-User mit dashboard.read.


Block G — Mitarbeiter-Einladung im Onboarding

Verbindung zu M27 D.1

Wizard-Step 8 nutzt das bestehende Tenant-User-Invitation-Flow aus M27 D.1:

  • Email + Rolle-Auswahl pro Zeile
  • Optional: Persönliche Nachricht (gemeinsam für alle)
  • System legt TenantUserInvitation an + sendet Magic-Link-Email
  • OnboardingInvitationDispatch als Tracking-Eintrag

Wizard-spezifische Verhaltensregeln

  • Inline-Validierung: Email-Format live geprüft
  • Duplikat-Check: Bei doppelter Email innerhalb des Formulars Klartext-Hinweis
  • Rollen-Vorauswahl: Default „Vertriebler" für erste Zeile (häufigster Fall), per Dropdown änderbar
  • Skip-Button: „Später einladen" → kein Eintrag, Wizard geht weiter
  • Bulk-CSV-Import: Phase 2 (Konsistenz mit M27 D.1)

Klartext-Hinweise

  • „Eingeladene Mitarbeiter erhalten eine Email mit Magic-Link. Sie können sofort anfangen — du musst nicht warten."
  • „Die Rolle bestimmt, was deine Mitarbeiter in HiveGrid dürfen. Du kannst sie jederzeit ändern."

Block H — KI-Walkthrough

Konzept

Nach Wizard-Abschluss landet User im Tenant-Dashboard. Optional erscheint Klartext-Hinweis vom KI-Layer (Modul 18): „Soll ich dir HiveGrid kurz zeigen?" — bei Bestätigung führt KI conversational durch:

  1. KI fragt: „Was willst du heute zuerst machen — einen Lead bearbeiten, ein Projekt erstellen oder Mitarbeiter einrichten?"
  2. User antwortet in Klartext
  3. KI navigiert zur entsprechenden Modul-Route, gibt Kontext-Hinweise: „Hier siehst du deine Sales-Pipeline. Klick auf eine Karte um Details zu sehen."
  4. KI bleibt verfügbar als persistenter Helper im rechten Panel

Pflicht-Properties

  • Aktivierung: explizit auf User-Trigger (LP-5 — KI ist Werkzeug, kein autonomer Agent)
  • Kein Auto-Start: Hinweis erscheint, aber User muss klicken
  • Permanent abschaltbar: Setting ai_walkthrough_offered = false in User-Settings
  • Action-Boundary: KI darf navigieren und erklären, keine schreibenden Aktionen ohne separate User-Bestätigung (AV #20, EC-5)

Kontext-Quellen

  • KI hat Zugriff auf:
    • Aktuellen Tenant-Status (Onboarding-Vollständigkeit, Erste-Schritte-Checkliste)
    • Help-Center-Artikel (Modul 38) via RAG
    • Modul-spezifische Hilfe-Texte
  • KI hat keinen Zugriff auf private Daten anderer Tenants (LP-13 + RLS)

Klartext

  • Initial-Prompt: „Soll ich dir die Plattform zeigen? Wir gehen die wichtigsten Funktionen Schritt für Schritt durch."
  • Bei Skip: „Kein Problem — du findest die Hilfe jederzeit im KI-Assistent oder im Help-Center."
  • Bei Frage außerhalb Kompetenzbereich: „Das kann ich noch nicht — frag gerne im Help-Center oder unseren Support."

Verbindung zu Modul 18

KI-Walkthrough ist nicht ein eigener Code-Pfad, sondern nutzt das Tenant-Assistant-Konzept aus Modul 18 mit speziellem System-Prompt-Modus „onboarding-walkthrough".


Block I — Routes

Sidebar-Eintrag

Während Wizard: keine Sidebar (Vollbild-Modus). Nach Wizard: Erste-Schritte-Checkliste im Dashboard.

Routes

/onboarding/setup/                              → Wizard nach Signup (kein Tenant-Slug — User noch nicht in Tenant)
/onboarding/setup/step/{step_code}/             → Spezifischer Step
/{tenant}/onboarding/checklist/                 → Erste-Schritte-Checkliste-Detail-View
/{tenant}/admin/onboarding/                     → Onboarding-Übersicht (Plattform-Admin-Sicht im Tenant-Admin)
/{tenant}/admin/onboarding/demo-data/           → Demo-Daten-Verwaltung

Sonderfälle

  • /onboarding/setup/ ist nicht unter Tenant-Slug-Prefix — der Tenant ist zwar angelegt, aber Wizard läuft global
  • Nach Wizard: Auto-Redirect auf /{tenant}/
  • Bei mid-Wizard-Logout + Re-Login: Auto-Redirect zurück zum Step

Block J — Permissions-Anwendung

Permission-IDs

Permission Erlaubt
onboarding.run Wizard-Schritte ausführen — automatisch für den User mit tenant.admin der initial den Tenant angelegt hat
onboarding.demo_data.manage Demo-Daten verwalten (Bulk-Löschung)
onboarding.checklist.dismiss Erste-Schritte-Items als „erledigt" markieren / Checkliste dauerhaft ausblenden

Bundle-Mapping (Variante 2)

Bundle Atomare Permissions
onboarding.none (keine — Wizard nicht zugänglich)
onboarding.run onboarding.run + onboarding.checklist.dismiss
onboarding.admin onboarding.run + onboarding.demo_data.manage + onboarding.checklist.dismiss

Anwendung in Routes

  • /onboarding/setup/ → onboarding.run (Default für Initial-Tenant-Admin) ODER tenant.admin
  • /{tenant}/admin/onboarding/demo-data/ → onboarding.demo_data.manage ODER tenant.admin
  • /{tenant}/onboarding/checklist/ → jeder authentifizierte Tenant-User mit dashboard.read

Sonderfälle

  • Mehrfach-Wizard-Durchführung nicht in Phase 1 (eine Session pro Tenant). Phase 2: Re-Onboarding für neue Branchen-Templates.
  • Nicht-Initial-Tenant-Admin (z.B. später eingeladener User mit tenant.admin) soll Wizard nicht erneut sehen — Detection über OnboardingSession.status = completed für Tenant.

Block K — Klartext-Hinweise/-Fehler

Pflicht-Texte (LP-10 + AV #1):

Wizard

  • Welcome-Step: „Willkommen bei HiveGrid! Wir helfen dir, dein Workspace in 5 Minuten einsatzbereit zu machen."
  • Branche „Coming soon"-Hinweis: „Diese Branche ist noch in Vorbereitung. Du erhältst vorerst die SHK-Konfiguration, kannst aber alles selbst anpassen."
  • Smart-Setup-Vorschau: „Wir richten für dich folgendes ein: 7 Standard-Rollen, 2 Pipelines, 3 Form-Templates, SHK-spezifische Felder. Du kannst alles später ändern."
  • Demo-Daten-Frage: „Sollen wir Beispiel-Daten anlegen, damit du sofort siehst wie alles funktioniert? Du kannst sie jederzeit löschen."
  • Mitarbeiter-Skip: „Du kannst jederzeit unter Mitarbeiter-Verwaltung weitere Personen einladen."
  • Wizard-Abschluss: „Fertig! Dein HiveGrid-Workspace ist einsatzbereit. Die Erste-Schritte-Liste auf deinem Dashboard zeigt dir die nächsten Aufgaben."

Erste-Schritte-Liste

  • Item-CTA: „Jetzt einrichten →"
  • Item-erledigt-Hinweis: „Erledigt ✓"
  • Vollständig-Glückwunsch: „Alle Erste-Schritte erledigt — viel Erfolg mit HiveGrid!"

KI-Walkthrough

  • Initial: „Soll ich dir die Plattform zeigen? Wir gehen die wichtigsten Funktionen Schritt für Schritt durch."
  • Skip: „Kein Problem — du findest die Hilfe jederzeit im KI-Assistent oder im Help-Center."

Fehler-Cases

Fehler Klartext + Lösungs-Hinweis
Smart-Setup-Step schlägt fehl (z.B. Pipeline-Anlage) „Wir konnten die Pipeline nicht anlegen. Wir versuchen es nochmal — falls es wieder fehlschlägt, kontaktiere bitte den Support." + Retry-Button
Demo-Daten-Provisioning schlägt fehl „Demo-Daten konnten nicht angelegt werden. Du kannst trotzdem starten — wir versuchen es im Hintergrund nochmal." (kein blockierender Fehler)
Logo-Upload zu groß „Das Logo ist zu groß (max. 2 MB). Bitte kleineres Bild wählen."
Logo-Format ungültig „Logo muss PNG, JPG oder SVG sein."
Mitarbeiter-Einladung mit ungültiger Email Inline-Hinweis pro Zeile: „Diese Email ist nicht gültig."
Mitarbeiter-Einladung an bestehenden User des Tenants „[Email] ist bereits Mitglied — Rolle: [Rolle]"
Branchen-Template nicht gefunden (Edge-Case bei Migration) „Konnte SHK-Template nicht laden. Plattform-Admin wurde benachrichtigt." + Auto-Plattform-Admin-Alert
Wizard-Resume bei zwischenzeitlichem Tenant-Cancel „Dein Workspace wurde inzwischen gekündigt. Bitte neu anmelden oder Support kontaktieren."

Block L — Phase 2 / Backlog

Bewusst NICHT in Phase 1:

  • Branchen-Templates für Elektro / Maler / Sanitär / Tischlerei / Dachdecker (alle deklarativ, gleiche Verzeichnis-Struktur)
  • Migration-Tools:
    • HubSpot-Importer (CRM + Leads + Deals)
    • Quiply-Importer (HR + Mitarbeiter)
    • KWP-Bestandsdaten-Importer
  • CSV-Bulk-Import für Bestandsdaten (Contacts, Companies, Deals) im Onboarding-Wizard als optionaler Schritt
  • KI-gestützter Onboarding-Coach: lernt aus Tenant-Verhalten, schlägt nächste Schritte vor (über Heuristiken hinaus)
  • Re-Onboarding für bestehende Tenants (z.B. wenn neue Templates in der Branche verfügbar)
  • Multi-Branchen-Tenant (Tenant ist gleichzeitig SHK + Elektro — Sub-Pipelines, Sub-Rollen)
  • Onboarding-Analytics für Plattform-Admin: Welche Steps werden am häufigsten geskippt, wo brechen User ab, durchschnittliche Wizard-Dauer
  • Custom-Onboarding pro Tenant: Tenant-Admin kann zusätzliche Steps für Unter-Onboarding eigener Mitarbeiter definieren
  • A/B-Testing von Wizard-Texten: Plattform-Admin testet Konversions-Optimierung
  • Demo-Daten-Branchen-Varianten: Mehrere SHK-Demo-Sets (z.B. „kleiner Betrieb" vs. „mittelständisch")
  • Onboarding-Replay: Tenant-Admin kann Wizard für Lerneffekt wiederholen

Architektur-Vorschriften (Querschnitt)

  • LP-3 + AV #3 — Branchen-Templates deklarativ: alle Branchen-spezifischen Daten (Pipelines, Rollen, Custom-Felder, Forms, Demo-Daten, Checkliste) in YAML-Verzeichnis-Struktur, kein Hardcode
  • LP-10 + AV #1 — Klartext-Diagnostik: alle Wizard-Schritte und Fehler menschenlesbar
  • AV #4 — i18n: alle Strings extern: Wizard-Texte über Locale-Files (Modul 30), DE Phase 1
  • AV #5 — Permissions-aware: Wizard-Zugriff über onboarding.run, kein hardcoded Owner-Check
  • AV #6 — Audit-Trail-Default: alle Wizard-Schritte mit OnboardingSessionAction geloggt
  • AV #20 — Action-Boundary für KI: KI-Walkthrough führt keine schreibenden Aktionen ohne User-Bestätigung
  • LP-9 + Stil-Vorgabe: UI-Element-Anforderungen als Liste, kein Layout

Detail-Spec-Status: DRAFT

Erste vollständige Detail-Spec für Modul 29. Vor Bau: Verifizierung mit Noah + finale SHK-Default-Werte (Pipelines, Custom-Felder, Demo-Daten-Inhalte) festlegen. Konkrete Template-YAML-Strukturen entstehen mit Implementierung.

Offene Detail-Punkte (nicht-blockierend):

  • Konkrete SHK-Demo-Daten-Inhalte (welche Beispiel-Kontakte, welche Deal-Stages besetzt) — Noah-Validierung
  • Konkrete Detection-Rules-DSL für Erste-Schritte-Items (vs. hardcoded JS-Funktionen)
  • Genaue Logo-Upload-Pipeline (Resize, Format-Konvertierung) — gemeinsam mit Modul 23 Files
  • KI-Walkthrough-Dialog-Skripte / System-Prompt für Modul-18-Integration
  • Konkrete Permission-IDs zusammen mit M27-Permission-Konsolidierung
  • Subframe-UI-Designs (separat)
  • Migrations-Skripte für Template-Sync beim Versions-Update