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