Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M29-onboarding.md
T

604 lines
25 KiB
Markdown

---
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 + Stripe-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