Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P24-self-service-billing-wizard.md
2026-07-08 16:15:37 +02:00

4.7 KiB
Raw Permalink Blame History

Designer-Brief · P24 — Self-Service-Billing & Onboarding-Wizard (v2-P3)

Phase: 24/34 (v2-P3) · Module: M28/M29 (M157 + M28-Self-Service-Delta, Block P) · Owner-Dev: Akeshan (VA-P24a/b) · Designer: David · Slot: v2-W1→W2 (Abo-UI 13.–17., Wizard 18./19.07.) Quellen: ROADMAP-V2.md §v2-P3 (Screens/Features = Hauptquelle) · ROADMAP.md §Phase 24 · _bmad-output/specs/M28-subscriptions-billing.md (Block P) · _bmad-output/specs/M29-onboarding.md Subframe: Pflicht je Route. Archetypen aus D0 (A2 Liste, A3 Detail, A5 Modal, A6 Settings, Vollbild-Flow).

🔵 Recut-/PWA-Hinweis: PWA-only (AD-17) → Self-Service-Billing läuft komplett über Web-Checkout (v1-Payment-Checkout wiederverwenden). Keine App-Store-Billing-Auflage — Apple-Guideline 3.1.3 entfällt vollständig, Plan-Wechsel direkt im Web. Self-Service ist v2, weil konkrete Preise feststehen müssen (v1 EXT-14 fixiert). Das Wizard-Framework ist großteils v1-fähig; v2-Delta = weitere Branchen + KI-Coach (per Retro-Integration aus P25) + Migration-Importer. Branchen-Template-Seeding ist ein geteilter Mechanismus (P24/P26/P30).

Was dieses Modul tut (Kurzfassung)

Tenants buchen und wechseln Pläne self-service über den Web-Checkout (Trial ohne Vertriebs-Freigabe, Add-On-Käufe) und durchlaufen nach dem Signup einen resumebaren, branchen-getriebenen Onboarding-Wizard (State-Machine), der das SHK-Branchen-Template deklarativ aus YAML seedet (Pipelines/Rollen/Custom-Felder/Forms/Demo/Checkliste). Eine Erste-Schritte-Checkliste (Detection-Rules) führt weiter; Demo-Daten lassen sich gebündelt löschen.

Benötigte Screens

Screen [Route] Kern-Inhalt Archetyp
Onboarding-Wizard [/onboarding/setup/step/:n] 10-Step-Vollbild-Flow: Branchen-Wahl, Pipelines/Rollen/Felder, Forms, Demo-Daten, Team-Einladung etc. · Step-Validierung · Rückwärts-Block nach irreversiblen Actions · resumebar Vollbild-Flow
Erste-Schritte-Checkliste [/onboarding/checklist] Checklisten-Widget (Detection-Rules: erledigt/offen) + Detail-Sicht mit Deep-Links zu den Aufgaben A2/Widget
Demo-Daten-Verwaltung [/admin/onboarding/demo-data] Übersicht geseedete Demo-Daten + Bulk-Löschung (Bestätigung) A6
Self-Service-Plan-Wechsel [/admin/subscription] Aktueller Plan, verfügbare Pläne (Web-Checkout), Plan-Wechsel/Upgrade/Downgrade, Zahlungsmethoden-Pflicht, Checkout-Return A6 + Web-Checkout
Add-On-Kauf-Flächen [/admin/subscription · /admin/usage] Add-On-Katalog (z. B. AI-Credits, Seats), Kauf via Web-Checkout, Usage-/Quota-Anzeige A6

Geplante Features (muss abgedeckt sein)

  • Self-Service-Trial ohne Vertriebs-Freigabe (requires_manual_activation=false) mit Zahlungsmethoden-Pflicht
  • Plan-Wechsel + Add-On-Käufe über Web-Checkout-Flow (PWA-only → kein App-Store, keine Store-Billing-Auflage)
  • Onboarding-Wizard resumebar nach Signup, Step-Validierung, Block der Rückwärts-Navigation nach irreversiblen Actions
  • SHK-Branchen-Template (Pipelines/Rollen/Custom-Felder/Forms/Demo/Checkliste) deklarativ aus YAML geseedet; weitere Branchen „coming soon"
  • Erste-Schritte-Checkliste mit Detection-Rules + Demo-Daten-Bulk-Löschung
  • KI-Walkthrough-Coach-Andockpunkt (wird von P25 rückwirkend eingehängt — kein harter Forward-Dep)
  • Wiederverwendung v1: Payment-Checkout + Webhook-Handler + Legacy-ProviderWebhookLog + SubscriptionFeature/ProductFeature (Feature-Gate) + Read-Only-Middleware + TenantUserInvitation

Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)

Step-Progress-Indikator (10 Steps, Vollbild), Step-Inhalts-Container mit Validierungs-Feedback, „Zurück gesperrt"-Hinweis nach irreversiblen Actions, Branchen-Auswahl-Karten (SHK aktiv, andere „coming soon"-disabled), Plan-Vergleichs-Karten/Tabelle (Features pro Plan, aktueller Plan markiert), Web-Checkout-Trigger-Button + Checkout-Return-Status, Zahlungsmethoden-Pflicht-Hinweis, Add-On-Katalog-Karten mit Preis + Kauf-Button, Usage-/Quota-Auslastungs-Anzeige (Balken), Erste-Schritte-Checklisten-Widget (abhakbare Items mit Deep-Link), Demo-Daten-Lösch-Bestätigung (mit Folgen-Hinweis), Resume-Banner („Onboarding fortsetzen"), KI-Coach-Slot/Platzhalter (von P25 befüllt), Empty-/Loading-/Permission-Denied-States (Klartext).

Davids Delta (David füllt aus)

  • Überschriebene/geänderte Spec-Punkte:
  • Neue UI/UX-Entscheidungen:
  • Subframe-Screen-Link(s):
  • Offene Fragen an Dev:

Dev-Nachzug (wir nach Davids Delta)

  • Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
  • REQUIREMENTS/PHASE-SOURCES nachgezogen:
  • Plane-Ticket (VA-P24a/b) aktualisiert: