--- module: 29 title: Onboarding phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-3, LP-7, LP-9, LP-10] spec_style: 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`: ```yaml 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