Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/AK-P20.md
T

61 lines
6.7 KiB
Markdown

# AK-P20 · P20 Billing (Stripe Abo-Baukasten) + Onboarding + Branding
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **AI-Credits-Screen + AI-Token-Quota entfallen** (kein LLM-Gateway in v1 — HiveGrid wird MCP-Server, [[VR-MCP]]; `AiCredits`/`AiTokenUsage` gestrichen). Die Verbrauchs-Übersicht bleibt für Automation-Läufe + Speicher. Alle AI-Credits/AI-Token-Stellen unten sind durchgestrichen.
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Akeshan |
| **Phase** | P20 — Billing, Onboarding & Branding |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-08 · Gate W4 |
| **Status** | geplant |
## Abhängigkeiten & Parallelität
- **Blocked by:** `EXT-07` (Stripe-Account + Produkte/Preise + Webhook-Endpoint), `AK-P19` (Abo-Baukasten-Mechanik + Admin-Tenant-Verwaltung als Voraussetzung)
- **Blocks:** `AK-P21` (DSGVO/Launch — Tenant-Löschung braucht Stripe-Cancel)
- **Läuft parallel zu:** Raffaels Kern-Kette (Auftrags-/Abnahme-Welt P9). Eigene `prisma/schema/billing.prisma` + Onboarding-Teile (AD-21); `core.prisma` (Tenant) nur über Relation.
- **Konflikt-Risiko:** gering — additive Tabellen + Read-Only-Middleware (Frozen) auf der Request-Pipeline (Querschnitt, additiv).
## Was wir bauen
Drei gebündelte v1-Module: **Billing als Stripe-Abo-Baukasten** (M154-Recut) — Basis-Preis pro Nutzer + Feature-Module als **daten-getriebene Positionen**, **KEINE Seat-Typen**; In-App **keine** Pricing-/Upgrade-/Plan-Wechsel-UI (Apple-Compliance LP-8) — nur Read-Only-Übersicht + externer Verweis; **Trial + Dunning** (Tag 1/3/7) + **Frozen-Modus** (Read-Only-Middleware); Verbrauchs-Zähler + Drossel (Aufschlags-Abrechnung → v2). **Onboarding** = **Auto-SHK-Provisionierung** beim Signup (Seeds M158, **ohne Wizard** — der ist v2) + Demo-Daten-Knopf + Erste-Schritte-Checkliste. **Branding** = nur **Hell/Dunkel-Toggle** (kein System-Modus), flash-frei via SSR-Cookie.
## Benötigte Screens (Backend bedient — Design liefert `D-P20`)
| Screen [Route] | Kern-Inhalt |
|---|---|
| Abo-Übersicht [`/admin/subscription`] | Basis-Plan + **Feature-Module als Positionsliste mit Preisen** (read-only), Status/Trial-Countdown, **KEIN Upgrade-Button** (Hinweis-Box „Plan-Wechsel über Account-Manager/hivegrid.de"), Pausieren + Kündigen |
| Verbrauchs-Übersicht [`/admin/usage`] ~~· AI-Credits [`/admin/usage/ai-credits`]~~ (AI-Credits-Screen entfällt — [[AD-26]]) | Quota-Balken je Metrik (Automation/~~AI-Tokens~~ (entfällt)/Speicher), ~~Donut AI-Verbrauch~~, 80%-Warnbanner, Aufgebraucht-Klartext |
| Rechnungen/Zahlung [`/admin/billing`] | **Stripe-Customer-Portal-Embed** (Rechnungs-History/PDF, Zahlungsmethode, USt-Daten) |
| Demo-Daten [`/admin/onboarding/demo-data`] | Settings-Knopf „Beispieldaten anlegen" (~25 Datensätze, Klartext-Liste), Demo-Zähler + Lösch-Funktion, „Demo ausblenden"-Filter |
| Erste-Schritte-Checkliste [`/onboarding/checklist`] | Auto-erkannte Status-Häkchen, CTA-Links, manuell abhakbar/ausblendbar, Glückwunsch bei 100% (auch Dashboard-Widget) |
| Status-Banner-System (Shell) | trial-Ende-3-Tage / past_due / frozen / deletion_pending je eigener Klartext + Action; Read-Only-Toast bei blockiertem Schreib-Button |
| Hell/Dunkel-Toggle [Profil/User-Menü] | Zwei Optionen, sofortige Anwendung, flash-frei (SSR-Cookie) |
## Definition of Done
- [ ] **Stripe-Abo-Baukasten**: Basis-Preis pro Nutzer + Feature-Module als daten-getriebene Positionen — **KEINE Seat-Typen** (M154-Recut); Preise geparkt (AD-15)
- [ ] **Trial + Dunning** (Tag 1/3/7) + **Frozen-Modus** (Read-Only-Middleware) greift; Status-Banner pro Zustand; Verbrauchs-Zähler + Drossel (Aufschlags-Abrechnung → v2)
- [ ] **In-App keine** Pricing-Tabelle/Upgrade-Buttons/Plan-Wechsel-UI (LP-8) — Read-Only + externer Verweis; Pause/Kündigen erlaubt
- [ ] **Auto-SHK-Provisionierung** beim Signup (Seeds M158: Pipelines, Custom-Felder, Rollen, Form-Templates, Checkliste) — **ohne Wizard-UI** (v2)
- [ ] **Demo-Daten-Knopf** (per Settings, `is_demo_data`-Flag löschbar) + „Demo ausblenden"-Filter
- [ ] **Erste-Schritte-Checkliste** (auto-erkannter Status, CTA-Links, abhakbar/ausblendbar; Dashboard-Widget)
- [ ] **Hell/Dunkel-Toggle** flash-frei (SSR-Cookie, `next-themes`) — kein System-Modus
- [ ] Konnektor `tenantHasModule('billing')`; RLS auf allen Tenant-Tabellen
## Technische Bausteine
- **Entities** (eigene `prisma/schema/billing.prisma`): `SubscriptionProduct` (Plan Core/Swarm/Colony — global), `SubscriptionPrice` (stripe_price_id, interval), `SubscriptionFeature` (+ `ProductFeature`, quota_value JSON — **Brücke zur Konnektor-Pflicht**, `tenantHasModule()`), `SubscriptionUsageBasedPrice`/`UsageBasedTier`, `TenantSubscription` (1:1 Tenant, status trial/active/past_due/cancelled/frozen, Stripe-IDs, Dunning-Felder), `TenantSubscriptionProductPrice` (quantity=Seats, is_metered), `TenantSubscriptionUsageRecord`, `Credit`, `CheckoutSessionStatus`. Onboarding: `Onboarding`/`OnboardingSession`/`OnboardingDemoProvisioning`. Branding: `User.theme_preference` (Feld, kein eigenes Modell). `core.prisma` über Tenant-Relation (AD-21).
- **Abo-Baukasten** (M154-Recut): `SubscriptionFeature.code` (z.B. `kwp_integration`) = Entitlement-Schicht; Struktur aus Legacy `pricing-plans.ts` portieren, Preise = Kostenmatrix (AD-15).
- **Stripe-Integration**: Webhook-Handler (Signatur), Customer-Portal-Embed, Dunning-Email-Sequenz, Frozen-Read-Only-Middleware auf der Request-Pipeline.
- **Auto-SHK-Provisionierung** orchestriert die Self-Seeds aller Module (AD-12); Demo-Daten-Seed via `is_demo_data`; Trial-Freischaltung durch Plattform-Admin (AK-P19).
- **RLS** überall (global: Produkte/Features/Preise); `next-themes` SSR-Cookie für Hell/Dunkel.
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 12: Billing & Abo-Baukasten** (Recut-Modell, keine Seat-Typen) + **Domäne 13** (Onboarding, OnboardingDemoProvisioning, User.theme_preference)
- `REQUIREMENTS.md` → `REQ-billing-datenmodell`, `REQ-billing-trial-dunning`, `REQ-onboarding-demo-daten`, `REQ-branding-theme-phase1` (Onboarding-Wizard → v2)
- `ROADMAP.md` → Phase 20 · `PHASE-SOURCES.md` → Phase 20 (M153-stripe, M154-recut bindend, M155-trial-readonly, M156-metering Zähler+Drossel, M158-shk-provisionierung, M159-branchen-templates nur SHK, M160-demo gedünnt, M030 nur Hell/Dunkel)
- `designer-briefs/P20-billing-onboarding-branding.md` (Abo-Baukasten, kein Upgrade-UI LP-8, Demo-Knopf, Hell/Dunkel)
- `_bmad-output/specs/M28-subscriptions-billing.md` (⚠ M154-Recut), `M29-onboarding.md` (Wizard → v2), `M31-branding.md` · Legacy: `archive/hivegrid-cloud/app/config/pricing-plans.ts`
## Dev-Nachzug (nach Davids `D-P20`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `AK-P20` aktualisiert