Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P20-billing-onboarding-branding.md
T

70 lines
6.9 KiB
Markdown

# 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.