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

6.7 KiB

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