Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,603 @@
|
||||
---
|
||||
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
|
||||
Reference in new issue
Block a user