Files

6.9 KiB

Designer-Brief · P20 — Billing, Onboarding & Branding

Phase: 20/21 · Module: M28 / M29 / M31 · Owner-Dev: Akeshan (AK-P20) · Designer: David Aktive Quellen: zugehörige Ticket-Docs · ROADMAP.md/ROADMAP-V2.md · REQUIREMENTS.md · ENTITY-MODEL.md. Subframe: Pflicht je Route. Archetypen aus D0 (A2 Liste, A6 Settings, KPI/Charts, A5 Modal).

🟡 Drei kleine v1-Module gebündelt — wichtige Schnitte (verbindlich):

  • Billing = Lago/Mollie/HiveGrid-Recut (AD-27): Plans + Seats und Feature-Entitlements liegen lokal in HiveGrid; Lago liefert Billing-/Invoice-State, Mollie nur Payment-State. In-App keine Pricing-/Upgrade-/Plan-Wechsel-UI — nur Read-Only-Übersicht + Verweis nach hivegrid.de/Account-Manager. Verbrauchs-Zähler sind Limit-Transparenz, kein Usage-Billing.
  • Onboarding: v1 = Auto-SHK-Provisionierung (Seeds M158 beim Signup, ohne Wizard). Der Onboarding-Wizard-UI ist v2 — bitte KEINEN mehrstufigen Setup-Wizard designen. KI-Walkthrough → v2. v1-Screens: Demo-Daten-Verwaltung + Erste-Schritte-Checkliste.
  • Branding: Der Light/Dark-Unterbau bleibt erhalten, der Toggle ist vorerst deaktiviert (DARK_MODE_IN_APP=false, PR #81). Logo/Farben/White-Label bleiben ausserhalb v1.

Was dieses Modul tut (Kurzfassung)

Ein neuer Betrieb kommt vom Self-Service-Signup per Auto-SHK-Provisionierung ins Produkt, nutzt HiveGrid-Entitlements mit Lago-/Mollie-Status, kann optional Demo-Daten anlegen/löschen und sieht eine Erste-Schritte-Checkliste. Der Light/Dark-Toggle bleibt vorerst ausgeschaltet.

Benötigte Screens

Screen [Route] Kern-Inhalt Archetyp
Abo-Übersicht [/:tenant/settings/subscription] Plan + Seats + gebuchte Feature-Module · Status/Trial-Countdown · KEIN Upgrade-Button (Hinweis „Plan-Wechsel über Account-Manager / hivegrid.de") · Kündigen, falls fachlich freigegeben A6 + KPI
Verbrauchs-Übersicht [/:tenant/settings/usage] Quota-Balken für Automation-Läufe und Speicher · aktueller Verbrauch vs. inklusiv · Klartext bei Limit-Erreichen, ohne Usage-Billing-Sprache KPI + Charts
Rechnungen/Zahlung [/:tenant/settings/billing] Lago-Invoice-Status, Mollie-Payment-Status, Download-/Kontaktzustand und Klartext-Hilfe A6
Demo-Daten [/:tenant/settings/onboarding/demo-data] Settings-Knopf „Beispieldaten anlegen" (~25 Datensätze, Klartext-Liste was kommt) · Demo-Zähler + Lösch-Funktion · „Demo ausblenden"-Filter (kein Wizard, kein KI-Walkthrough) A6
Erste-Schritte-Checkliste [/:tenant/onboarding/checklist] Items mit Status-Häkchen (auto-erkannt), Klartext + Beschreibung, CTA-Link je Item, manuell abhakbar, dauerhaft ausblendbar, Glückwunsch bei 100% · auch als Dashboard-Widget A2
Status-Banner-System (Shell) Tenant-Status-Banner: Trial-Ende-3-Tage / past_due / frozen mit Klartext und Aktion zur Abo-Übersicht beziehungsweise zum Account-Manager. deletion_pending samt Shell-Aktion gehört zu D-P21; die finale Read-only-Toast-Optik bleibt hier offener Nachzug. in A1-Shell integriert (D0)
Light/Dark-Toggle [Profil / User-Menü] Vorerst nicht sichtbar und im App-/Admin-Bereich nicht aktiv (DARK_MODE_IN_APP=false) kein neuer Screen

(Signup-Formular → P2-Auth. Mitarbeiter-Einladung → P2/P20-Seeds. Kein Onboarding-Setup-Wizard und kein Customer-Checkout in v1; Self-Service-Billing folgt in v2/P24.)

Geplante Features (muss abgedeckt sein)

  • Billing zeigt lokale HiveGrid-Plans/Seats/Entitlements read-only; Lago liefert Invoice-/Billing-State, Mollie den Payment-State. Kein Customer-Checkout und kein Usage-Billing (AD-27).
  • Trial mit Dunning (Tag 1/3/7) und Frozen-Modus (Read-Only-Middleware) greift; Status-Banner pro Zustand mit Klartext + Action; Verbrauchs-Zähler + Drossel aktiv (Aufschlags-Abrechnung → v2)
  • In-App keine Pricing-Tabelle/Upgrade-Buttons/Plan-Wechsel-UI (LP-8) — Abo-Übersicht read-only + externer Verweis; Kündigen bleibt bei vorhandener Berechtigung erlaubt
  • Neuer Tenant wird nach Signup automatisch SHK-provisioniert (Seeds M158: Pipelines, Custom-Felder, Rollen, Form-Templates, Checkliste) — ohne Wizard-UI (die folgt v2); Trial-Freischaltung durch Plattform-Admin
  • Optionale Demo-Daten (5 Contacts, 3 Deals, 2 Projekte, Tasks) per Settings-Knopf provisionierbar und via is_demo_data-Flag löschbar; „Demo ausblenden"-Filter in Listen (KI-Walkthrough → v2; einfaches Löschen statt Multi-Step-Bulk)
  • Erste-Schritte-Checkliste mit auto-erkanntem Status, CTA-Links, manuell abhakbar/ausblendbar (als Dashboard-Widget)
  • Light/Dark-Toggle ist vorerst deaktiviert; der vorhandene Unterbau bleibt unangetastet (PR #81).

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

Plan-/Seat-/Feature-Positionsliste (read-only), Trial-Countdown- und Billing-Status-Badge, KPI-/Quota-Balken (Automation/Speicher), Warnbanner, externer Verweis („Plan-Wechsel über hivegrid.de", neuer Tab), Kündigen-Button mit Bestätigungs-Modal, Lago-Invoice-Status, Mollie-Payment-Status, Rechnung-Download/Support-Hinweis, Demo-Daten-Anlege-Knopf mit Klartext-Inhaltsliste, Demo-Zähler + Lösch-Button, „Demo ausblenden"-Filter-Toggle, Checklisten-Items mit Status-Icon + CTA-Link + manuell-abhaken + ausblenden, Status-Banner-Stack (trial/past_due/frozen) mit Action-Button, bestehende 423-Klartext-Hülle plus final zu gestaltender Read-only-Toast sowie Empty-/Loading-/Fehler-/Permission-Denied-States (Klartext mit Lösungs-Knopf). deletion_pending wird in D-P21 gestaltet.

Interim-UI-Handoff (AD-28, Stand 2026-07-12)

Die Dev-Vorschau steht auf den kanonischen Tenant-Routen /:tenant/settings/subscription, /:tenant/settings/usage, /:tenant/settings/billing, /:tenant/settings/onboarding/demo-data und /:tenant/onboarding/checklist; das Dashboard nutzt dasselbe Checklisten-VM. Die Screens erhalten reine Billing-/Onboarding-VMs und injizierte Action-Callbacks. Der Hot-Swap-/Visual-Nachweis liegt unter packages/ui-mock/visual-baseline/ak-p20-interim.*; der echte M016-Pixelnachweis liegt in tests/component/ak-p20-interim.ct.tsx mit fünf PNG-Baselines unter tests/component/__screenshots__/. Der schnelle React-Markup-Nachweis bleibt in apps/web/app/components/screens/ak-p20-interim.visual.test.tsx. Davids finales D-P20-Delta bleibt offen und ersetzt später nur die Screen-Internals; Loader, VM-Verträge und Routen bleiben stabil. Beim Nachzug ist die Interim-Baseline neu zu ziehen.

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/ROADMAP nachgezogen:
  • Plane-Ticket (AK-P20) aktualisiert: Recut-Titel, Label design-nachzug und Abschlusskommentar 1dee227f-4726-4b7c-8ef1-7a15108f7e99; Status bis zur Done-Freigabe unverändert.