Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,755 @@
---
module: 28
title: Subscriptions / Billing
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-1, LP-2, LP-7, LP-8, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 28 — Subscriptions / Billing
> **Detail-Spec gemäß LP-9.** Subscription-Engine und Billing-Anbindung an Stripe. Pricing-Modell selbst ist **geparkt** — die Engine wird so flexibel gebaut, dass konkrete Plans später konfigurativ definiert werden können (LP-7 + Brainstorming „Geparkt für später"). **Apple-Compliance (LP-8):** keinerlei Pricing-/Upgrade-UI in der App selbst — Self-Service-Signup ausschließlich über Marketing-Site `hivegrid.de`.
## Themenblöcke
```
A. Datenmodell + Pricing-Konfiguration
B. Subscription-Lifecycle + Status-Übergänge
C. Self-Service-Signup-Flow + Stripe-Checkout
D. Seat-Modell (Büro vs. Monteur)
E. Trial-Phase
F. Dunning + Past-Due
G. Downgrade-Read-Only-Middleware
H. Frozen-Modus (User-Pause)
I. Service-Metering (Trigger-Volumen, AI-Token)
J. AI-Credits-System
K. Setup-Fee-Handling
L. Demo-Buchung (extern)
M. Routes + In-App-Sicht
N. Permissions-Anwendung
O. Klartext-Hinweise/-Fehler
P. Phase 2 / Backlog
```
---
## Block A — Datenmodell + Pricing-Konfiguration
### Grundprinzip
Engine ist **konfigurations-getrieben**. Plattform-Admin definiert Produkte, Preise, Features, Usage-Tiers über Datenstrukturen — Code kennt die konkreten Plans nicht. Damit kann das Pricing-Modell jederzeit angepasst werden, ohne Code-Releases.
### Entitäten
#### `SubscriptionProduct`
Ein Plan-Produkt (z.B. `Cloud`, `Cloud+`, `Enterprise` — Namen werden später festgelegt).
- `id` (UUID), `created_at`, `updated_at`
- `code` (technischer Schlüssel, unique, snake_case — z.B. `cloud_basic`)
- `display_name` (User-sichtbar, locale-abhängig — DE Pflicht, weitere via Modul 30)
- `description` (Markdown)
- `tier_order` (Integer — für Vergleich „höher/niedriger" bei Up-/Downgrade)
- `is_active` (Boolean — neue Tenants können nur aktive Produkte wählen)
- `is_self_service_eligible` (Boolean — `Enterprise` z.B. nur per Plattform-Admin zuweisbar)
- `setup_fee_required` (Boolean — siehe Block K)
- `trial_default_days` (Integer, 5-7 — siehe Block E; null = kein Trial)
- `requires_manual_activation` (Boolean — Vertrieb gibt Trial frei, siehe Block E)
#### `SubscriptionPrice`
Konkreter Preispunkt (Stripe-Price-Mapping).
- `id`, `subscription_product_id` (FK)
- `stripe_price_id` (string, eindeutig)
- `currency` (ISO 4217 — `EUR` Default)
- `interval` (Enum: `month | year | one_time` — `one_time` für Setup-Fee)
- `interval_count` (Integer, default 1)
- `unit_amount_cents` (Integer)
- `tax_behavior` (Enum: `inclusive | exclusive` — Stripe-konform)
- `is_active`
- `valid_from`, `valid_until` (für preisliche Übergangsphasen)
#### `SubscriptionFeature`
Ein technisches Feature-Flag (siehe M27 Block F.1 für Loader-Convention).
- `id`, `code` (unique, snake_case — z.B. `kwp_integration`, `automation_advanced_branches`, `email_marketing`, `ai_assistant`)
- `display_name`, `description`
- `category` (Enum: `module | sub_feature | integration | ai`)
#### `SubscriptionProductFeature` (M:N)
Welche Features welcher Plan enthält.
- `subscription_product_id`, `subscription_feature_id`
- `quota_value` (JSON, optional — z.B. `{"max_users": 10}` oder `null` für unbegrenzt)
#### `SubscriptionUsageBasedPrice`
Definition eines Verbrauchs-basierten Preisteils (Trigger-Volumen, AI-Token).
- `id`, `subscription_product_id`
- `metric_code` (Enum: `automation_trigger | ai_token | sms_outbound | other`)
- `display_name`
- `included_amount` (Integer — im Plan inklusive)
- `overage_pricing_strategy` (Enum: `tier | per_unit | block`)
- `unit_label` (z.B. `1 Trigger`, `1.000 Token`)
#### `SubscriptionUsageBasedTier`
Stufen-Tarife für Überschreitungen.
- `id`, `subscription_usage_based_price_id`
- `from_amount`, `to_amount` (Integer — `to_amount` null = bis unendlich)
- `unit_amount_cents`
- `flat_amount_cents` (Pauschale für Block-Strategie)
#### `TenantSubscription`
Aktive Subscription pro Tenant.
- `id`, `tenant_id` (unique, M:1)
- `status` (Enum: `trial | active | past_due | cancelled | frozen` — siehe Block B)
- `subscription_product_id` (FK)
- `stripe_customer_id`, `stripe_subscription_id`
- `started_at`, `current_period_start`, `current_period_end`
- `trial_start`, `trial_end`
- `cancel_at_period_end` (Boolean)
- `cancelled_at`, `cancellation_reason` (optional)
- `frozen_since` (Timestamp — siehe Block H)
- `setup_fee_paid_at` (Timestamp, nullable)
- `last_dunning_attempt_at`, `dunning_attempt_count`
- `created_by_user_id`, `created_via` (Enum: `self_service | platform_admin | api`)
#### `TenantSubscriptionProduct`
Snapshot der gewählten Produkt-Konfiguration zum Zeitpunkt der Buchung (für Audit + Preisstabilität).
- `id`, `tenant_subscription_id`
- `subscription_product_id` (FK auf das Produkt-Original)
- `snapshot_data` (JSONB — kompletter Stand bei Buchung)
- `valid_from`, `valid_until`
#### `TenantSubscriptionProductPrice`
Welche `SubscriptionPrice`-Einträge dem Tenant zugeordnet sind (Plan-Preis + Setup-Fee + ggf. Add-Ons).
- `id`, `tenant_subscription_id`, `subscription_price_id`
- `quantity` (Integer — z.B. Seat-Anzahl)
- `is_metered` (Boolean — siehe Usage-Records)
- `valid_from`, `valid_until`
#### `TenantSubscriptionUsageRecord`
Verbrauchs-Datensatz für metered Pricing.
- `id`, `tenant_subscription_id`, `metric_code`, `period_start`, `period_end`
- `usage_amount` (Integer)
- `reported_to_stripe_at` (Timestamp, nullable)
- `created_at`
- Indexe auf `(tenant_subscription_id, metric_code, period_start)`
#### `CheckoutSessionStatus`
Tracking des Stripe-Checkout-Flows pro Tenant-Anlage.
- `id`, `tenant_id` (FK), `stripe_checkout_session_id`
- `status` (Enum: `pending | completed | expired | failed`)
- `intent` (Enum: `initial_signup | plan_change | reactivate_from_frozen | reactivate_from_past_due`)
- `created_at`, `completed_at`, `expires_at`
- `error_message` (string)
- `redirect_url_success`, `redirect_url_cancel`
#### `Credit`
AI-Credit-System (siehe Block J). Token-Quota mit Carry-Over-Regeln.
- `id`, `tenant_id`
- `credit_type` (Enum: `ai_token | automation_trigger_bonus | other`)
- `amount` (Integer — positive = Guthaben, negative = Verbrauch)
- `source` (Enum: `plan_inclusion | manual_grant | promo_code | overage_purchase | refund`)
- `valid_from`, `valid_until` (optional — Plan-Inclusion verfällt am Period-Ende)
- `balance_after` (Integer — gerechnete Saldo nach diesem Eintrag)
- `created_at`, `created_by_user_id` (NULL für System)
- `notes` (Klartext für Audit)
### Indizes (Performance)
- `TenantSubscription`: unique auf `tenant_id`, Index auf `status`, `current_period_end`, `dunning_attempt_count`
- `TenantSubscriptionUsageRecord`: Composite-Index auf `(tenant_subscription_id, metric_code, period_start)`
- `Credit`: Index auf `(tenant_id, credit_type, created_at DESC)` für Saldo-Berechnung
### Sonderfälle / Constraints
- `TenantSubscription` ist **nicht** RLS-gegated (App-Code permission-gegated, da Plattform-Admin alle Tenants sehen muss — siehe M27 A.4)
- `SubscriptionProduct/Price/Feature` sind **global** (kein `tenant_id`) — sie sind Plattform-Konfiguration
- `Credit` ist tenant-scoped mit RLS
- Soft-Delete für `SubscriptionProduct` über `is_active=false` (alte Tenants behalten Snapshot via `TenantSubscriptionProduct`)
---
## Block B — Subscription-Lifecycle + Status-Übergänge
Status-Werte (entsprechen M27 A.5 Tenant-Status-Werten — `TenantSubscription.status` und `Tenant.status` sind synchronisiert):
```
trial → Self-Service-Signup-Phase, Vertrieb-freigegeben für 5-7 Tage
active → Bezahlend, voller Funktionsumfang
past_due → Stripe-Zahlung gescheitert, Read-Only (siehe Block G)
cancelled → User-Kündigung wirkt zum Period-Ende oder sofort
frozen → User pausiert Workspace, reduzierte Gebühr, Read-Only (siehe Block H)
```
### Übergangs-Tabelle
| Von | Nach | Trigger |
|---|---|---|
| `trial` | `active` | Trial-Konversion: Stripe-Checkout-Setup erfolgreich abgeschlossen |
| `trial` | `cancelled` | Trial läuft ab ohne Konversion → Tenant wird zu `deletion_pending` (M27) |
| `active` | `past_due` | Stripe-Webhook `invoice.payment_failed` |
| `past_due` | `active` | Nachzahlung erfolgreich (Stripe-Webhook `invoice.payment_succeeded`) |
| `past_due` | `cancelled` | Nach 14 Tagen + 3 Dunning-Versuchen erfolglos → Stripe gibt `subscription.deleted` |
| `active` | `frozen` | User klickt „Workspace pausieren" + bestätigt reduzierten Plan |
| `frozen` | `active` | User klickt „Reaktivieren" + Standard-Plan-Checkout |
| `frozen` | `past_due` | Reduzierte Gebühr scheitert |
| `*` | `cancelled` | User klickt „Tenant kündigen" — wirkt zum Period-Ende, oder sofort bei Trial |
| `cancelled` | `active` | User zieht Kündigung innerhalb 30 Tagen zurück (Tenant noch nicht hard-deleted) |
### Übergangs-Hooks (Side-Effects)
Bei jedem Übergang wird ausgelöst:
- Audit-Log-Eintrag mit alt/neu Status, Trigger-Quelle, Stripe-Event-ID
- Activity-Stream-Eintrag (`subscription_status_changed`)
- Tenant-Status-Synchronisation (M27 A.5)
- Notification an Tenant-Admin (Email + In-App via M22)
- Bei Übergang in `past_due`/`cancelled`/`frozen`: Read-Only-Middleware-Cache invalidieren
---
## Block C — Self-Service-Signup-Flow + Stripe-Checkout
### Signup-Pfad (extern → intern)
Externer Pfad — siehe M27 A.1:
1. Marketing-Site `hivegrid.de/signup` (Next.js, extern, **nicht** Teil dieser Codebase)
2. Leitet zu `app.hivegrid.de/signup` für Account-Erstellung
3. Nach Account-Anlage: automatischer Tenant-Anlage-Schritt + Stripe-Checkout
### In-App-Signup-Schritte (`/signup`)
1. Auth-Account-Anlage (siehe M27 B.1) — Email, Pwd, AGB, DSGVO, AVV
2. Tenant-Daten — Firmenname, Slug, Branche, Größe (siehe M27 A.1)
3. Plan-Auswahl mit `is_self_service_eligible=true`-Filter
4. Stripe-Checkout-Session-Erstellung mit `intent=initial_signup`
5. Redirect auf Stripe-Checkout (extern bei Stripe gehostet)
6. Nach Erfolg → `/{tenant}/onboarding/setup/` (siehe M29)
### Checkout-Konfiguration
- **Stripe-Customer** mit Tenant-`id` als `metadata.tenant_id`
- **Subscription-Setup** mit Trial (siehe Block E)
- **Steuer-Behandlung:** Stripe Tax aktiv, EU-Reverse-Charge-Logik
- **Zahlungsmethoden:** SEPA-Lastschrift (Default DE/EU), Kreditkarte
- **DPA (Auftragsverarbeitungsvertrag):** wird elektronisch im Signup unterzeichnet (M27 A.1 — AVV-Akzeptanz-Checkbox)
- **EU-Entity-Präferenz:** Stripe Ireland Ltd. (Stripe Payments Europe DAC — EU-Vertragspartner)
### Stripe-Webhooks (Pflicht-Handling)
| Webhook-Event | Wirkung in HiveGrid |
|---|---|
| `checkout.session.completed` | `CheckoutSessionStatus.status = completed`, Trial-Aktivierung oder direkter Active-Wechsel |
| `invoice.created` | Rechnung lokal als Referenz speichern (Customer-Portal lädt Original aus Stripe) |
| `invoice.payment_succeeded` | Falls `past_due` → `active`-Übergang triggern |
| `invoice.payment_failed` | `past_due`-Übergang triggern, Dunning-Counter erhöhen |
| `customer.subscription.updated` | Plan-Wechsel propagieren (Snapshot aktualisieren) |
| `customer.subscription.deleted` | `cancelled`-Übergang triggern |
| `customer.subscription.trial_will_end` | 3 Tage vor Trial-Ende: Notification + In-App-Banner |
### Idempotenz
Webhook-Handler **Pflicht-idempotent** über `stripe_event_id` als Unique-Constraint in einer `StripeWebhookLog`-Tabelle (Schreib-Idempotenz, AV #8).
---
## Block D — Seat-Modell
Spiegelt LP-2 (Büro vs. Baustelle als kontextuelle Modi).
### Seat-Typen
| Typ | Inhalt |
|---|---|
| **Büro-Seat** | Vollzugang zur Plattform, Default-UI-Modus „Büro", alle Module zugreifbar gemäß Permissions |
| **Monteur-Seat** | Eingeschränkter Zugang, Default-UI-Modus „Baustelle", reduzierte Modul-Sicht (Projekt-Detail, Tasks, Acceptance, Foto-Forms, Chat in eigenen Channels, HR-Hub eigene Doks) — siehe M27 C.2 Monteur-Rolle |
### Pflicht-Verknüpfung mit Rolle
- Jeder Tenant-User hat **genau einen Seat-Typ** zur aktiven Zeit
- Bei User-Einladung (M27 D.1) wählt Tenant-Admin Seat-Typ als Pflichtfeld
- **Seat-Typ ist Lizenz-Konzept**, Rolle ist Permission-Konzept — beide separat
- Ein Monteur-Seat kann **nur** Rollen mit Default-UI-Modus `Baustelle` zugewiesen bekommen (Validierungs-Regel)
- Ein Büro-Seat kann jede Rolle bekommen
### Seat-Counting + Stripe-Sync
- Bei Einladung/Aktivierung eines neuen Users: Seat-Counter hochzählen, Stripe-`Subscription.items[].quantity` updaten
- Bei Deaktivierung/Entfernung: Seat-Counter runter, Stripe-Update zum Period-Ende (proration nach Tenant-Admin-Setting)
- **Übersicht in `/{tenant}/admin/usage/`:** aktuelle Seats pro Typ + verfügbare Seats laut Plan + Trend-Chart
### Plan-Quotas
`SubscriptionProductFeature.quota_value` enthält (Beispiel):
```json
{
"max_buero_seats": 10,
"max_monteur_seats": 50,
"max_buero_seats_overage_blocked": false
}
```
Bei Erreichung Quota:
- **Hard-Limit** (Default): Einladung blockiert, Klartext: *„Plan-Limit von 10 Büro-Seats erreicht. Upgrade nötig — siehe Marketing-Site."*
- **Soft-Limit** (Konfiguration): zusätzliche Seats werden automatisch über Usage-Based-Price abgerechnet
---
## Block E — Trial-Phase
### Eigenschaften
- **Dauer:** 5-7 Tage (per `SubscriptionProduct.trial_default_days`)
- **Vertriebs-freigegeben:** Vertrieb (Plattform-Admin) muss Trial **manuell aktivieren** (`requires_manual_activation=true` für Phase-1-Trials), um Spam zu verhindern
- **Voller Funktionsumfang während Trial** (kein Read-Only)
- **Stripe:** Subscription mit `trial_end` gesetzt, keine Zahlungs-Auslösung vor Trial-Ende
- **Zahlungsmethode:** **nicht** zwingend zu Trial-Beginn (Vertriebs-Modus). Wird in Phase 2 für Self-Service-Trials erforderlich (User-Diskussion auslagerbar)
### Trial-Aktivierungs-Flow
1. User schließt Signup ab → `TenantSubscription.status = trial`, aber `trial_start = null`
2. Tenant erscheint in Plattform-Admin-Liste „Trial-Anfragen" (M37)
3. Vertrieb prüft + aktiviert → setzt `trial_start = now()`, `trial_end = now() + trial_default_days`
4. Tenant erhält Klartext-Email: *„Dein HiveGrid-Trial ist freigeschaltet. Bis [Datum] kannst du alles testen."*
### Trial-Ende-Flow
- 3 Tage vor Trial-Ende: In-App-Banner + Email-Notification mit Klartext und Hinweis auf Marketing-Site (kein In-App-Upgrade — LP-8)
- 1 Tag vor Trial-Ende: erneute Notification
- Trial-Ende ohne Konversion: `TenantSubscription.status = cancelled`, Tenant geht in `deletion_pending` (30 Tage Grace, M27 A.5)
### Trial-Konversion
Tenant-Admin geht auf Marketing-Site (`hivegrid.de/upgrade`), wählt Plan, gelangt zurück nach `app.hivegrid.de/{tenant}/admin/subscription/checkout-return` mit Stripe-Session-Token → CheckoutSessionStatus + Webhook-Verarbeitung → `active`-Übergang.
---
## Block F — Dunning + Past-Due
### Stripe-Standard-Dunning
- **3 Wiederholungs-Versuche** über **14 Tage** (Stripe Smart Retries oder eigene Schedule)
- Versuche typischerweise: Tag 0 (initial), Tag 3, Tag 7, Tag 14
- HiveGrid empfängt `invoice.payment_failed` und `invoice.payment_succeeded`-Events
### Past-Due-Verhalten
- Workspace **read-only** (siehe Block G)
- In-App-Banner: *„Zahlung fehlgeschlagen, Konto in 14 Tagen gesperrt — [Zahlungsmethode aktualisieren]"* mit Direkt-Link zum Stripe-Customer-Portal
- Email-Notification an Tenant-Admins mit Klartext + Direkt-Link
- Nach 3 Fehlversuchen + 14 Tagen ohne Erfolg: `cancelled`
### Notification-Strategie
| Event | Empfänger | Kanal |
|---|---|---|
| Erste Zahlungs-Fehler | Tenant-Admins | Email + In-App |
| Versuch 2/3 fehlgeschlagen | Tenant-Admins | Email + In-App |
| 1 Tag vor finalem Cancel | Tenant-Admins | Email + In-App + Push (M22) |
| Final-Cancel | Tenant-Admins + Plattform-Admin | Email + Plattform-Admin-Alert |
---
## Block G — Downgrade-Read-Only-Middleware
### Wirkung
Bei Status `past_due` ODER `frozen` ODER `cancelled` (mit `cancel_at_period_end=true` und Period bereits abgelaufen):
- App **rendert** noch alle Daten lesend
- **Schreibende Aktionen blockiert** auf Middleware-Ebene
- Schreibende API-Endpoints liefern 402 Payment Required mit Klartext-Body
- Schreibende UI-Elemente (Buttons, Forms) entweder ausgeblendet oder ausgegraut mit Tooltip
### Genaue Read/Write-Grenzen (analog M27 A.5 Frozen-Modus)
| Aktion | `past_due` / `frozen` / `cancelled-period-over` |
|---|---|
| Login (alle Rollen) | ✓ |
| Daten lesen | ✓ |
| Stammdaten-Edit, neue Datensätze | ✗ |
| Email/WhatsApp/Push senden | ✗ |
| Automationen ausführen | ✗ (eingehende Trigger werden verworfen, nicht gequeued) |
| Eingehende Webhooks | ✗ (mit 402-Response, nicht gequeued) |
| Customer-Portal-Zugang (Endkunden) | ✓ (read-only) |
| API (Read) | ✓ |
| API (Write) | ✗ (402) |
| Stripe-Customer-Portal-Zugang | ✓ (Pflicht zur Reaktivierung) |
| Plan-Wechsel / Reaktivierung | ✓ (einziger erlaubter Schreib-Pfad) |
### Implementierungs-Vorgabe
- Middleware **vor** Route-Loader: prüft `TenantSubscription.status` + `is_writable_status()`-Helper
- Middleware **vor** Worker-Job-Ausführung: blockiert Automation-Worker, Notification-Worker, Webhook-Outbound-Worker bei nicht-schreibendem Status
- Cache der Status-Auflösung: 30 Sekunden (TTL), bei Stripe-Webhook explizit invalidieren
### Klartext-Hinweise
- In-App-Banner pro Status (siehe M27 A.5)
- Bei Klick auf blockierten Schreib-Button: Toast *„Workspace ist read-only. Status: [Klartext]. [Reaktivieren]"*
---
## Block H — Frozen-Modus (User-Pause)
### Use-Case
Tenant kann Workspace pausieren statt zu kündigen (z.B. Saison-Pause bei kleinen Betrieben). Reduzierte Gebühr, Workspace read-only, jederzeit reaktivierbar — Daten bleiben.
### Pause-Flow
1. Tenant-Admin in `/{tenant}/admin/subscription/` → „Workspace pausieren"
2. Klartext-Erklärung: was bleibt, was nicht geht, welche Gebühr
3. Bestätigung mit Tipp-Eingabe „PAUSIEREN" (Multi-Step-Schutz)
4. Stripe: Subscription-Wechsel auf `frozen_plan_price` (eigener `SubscriptionPrice` mit reduzierter Gebühr)
5. `TenantSubscription.status = frozen`, `frozen_since = now()`
6. M27 Tenant-Status synchronisiert auf `frozen`
### Reduzierte Gebühr
- Konfigurations-Setting (`SubscriptionProduct` hat optionalen `frozen_mode_price_id`)
- Phase 1: Default ca. **1/10** des Standard-Plan-Preises (konkrete Preise im Pricing-Setup, **geparkt**)
### Reaktivierungs-Flow
1. User klickt In-App-Banner „Reaktivieren"
2. Stripe-Checkout-Session mit `intent=reactivate_from_frozen` und gewähltem Standard-Plan
3. Nach Erfolg: `frozen → active`-Übergang
### Sonderfälle
- Frozen-Tenant kann sich **nicht** in den anderen End-Status (`cancelled`) wechseln, ohne erst zu reaktivieren — *außer* expliziter Kündigung mit Klartext-Hinweis
- Bei Zahlungsausfall der reduzierten Gebühr: `frozen → past_due`
---
## Block I — Service-Metering
### Metriken (Phase 1)
Engine baut bereits Tracking auf, **konkrete Pricing-Schwellen geparkt**:
| Metrik-Code | Was wird gezählt |
|---|---|
| `automation_trigger` | Anzahl Trigger-Auslösungen in der Automation-Engine pro Tenant pro Period (siehe Modul 17 EC-1 Hard-Limit) |
| `ai_token` | LLM-Token-Verbrauch (siehe Block J) — Prompt-Token + Completion-Token pro Provider, normalisiert |
| `sms_outbound` | SMS-Versand falls Modul 22 aktiv (Phase 2) |
| `whatsapp_session` | WhatsApp-Session-Kosten (Phase 2) |
### Tracking-Pflichten
- Jede Automation-Trigger-Ausführung: `TenantSubscriptionUsageRecord` inkrementieren (idempotent über Trigger-Run-ID)
- Jeder LLM-Call: Token-Verbrauch nach Response loggen, in `Credit`-Verbrauch verrechnen
- Aggregation pro **Period** (entspricht Stripe-Subscription-Period — typisch monatlich)
### Reporting an Stripe
- Bei `metric_code` mit `is_metered=true`-Subscription-Item: Usage-Reporting an Stripe via `usage_records.create` am Period-Ende oder real-time (Strategie pro Metrik konfigurierbar)
- `reported_to_stripe_at`-Feld für Tracking
### In-App-Sicht (`/{tenant}/admin/usage/`)
Zu zeigende Daten:
- Aktuelle Period mit Verbrauch pro Metrik
- Plan-Inklusiv-Menge pro Metrik
- Verbrauch in % (Progress-Indikator)
- Trend gegenüber Vorperiode
- Historische Perioden (letzte 12)
Benötigte UI-Elemente:
- Listen-/Tabellen-Anzeige der Metriken
- Detail-Drill-Down pro Metrik mit Zeitachsen-Visualisierung
- Filter nach Period
- Export der Verbrauchs-Daten als CSV
Operationen:
- Reine Lese-Sicht — keine Verbrauchs-Änderungen
- Add-On-Käufe (Trigger-Volumen-Pakete) → **Phase 2**
Permissions: `billing.read` oder `tenant.admin`.
---
## Block J — AI-Credits-System
### Konzept
Pro Plan inkludierte AI-Token-Quota (z.B. Cloud: 1 Mio Token/Monat — konkrete Mengen geparkt).
### Saldo-Berechnung
- Saldo aus `Credit`-Tabelle (Sum aller Einträge eines `credit_type`)
- Bei Plan-Period-Start: Plan-Inclusion als positiver `Credit` mit `valid_until = period_end`
- Bei jedem LLM-Call: negativer `Credit`-Eintrag mit Token-Anzahl
### Verbrauchs-Verrechnung
1. LLM-Call ausgelöst via Modul 18
2. Pre-Check: Saldo > erwarteter Maximal-Verbrauch?
- Ja → Call ausführen
- Nein → Klartext-Fehler: *„AI-Credits aufgebraucht. Plan-Wechsel oder Add-On nötig — siehe Marketing-Site."* (Apple-Compliance-konform — kein In-App-Upgrade)
3. Nach Call: Token aus Response-Metadata, negativer Credit-Eintrag
### Carry-Over-Regeln (Phase 1)
- Plan-Inclusion **verfällt** am Period-Ende (`valid_until` enforced)
- Manual-Grants (Vertrieb gibt Bonus) ohne `valid_until` bleiben
- Promo-Codes mit fixem `valid_until`
### In-App-Sicht (`/{tenant}/admin/usage/ai-credits/`)
Zu zeigende Daten:
- Aktueller Saldo pro `credit_type`
- Verbrauchs-Historie mit Quelle (welche User, welcher Modul-Aufruf)
- Hochrechnung: bei aktuellem Verbrauchs-Trend wann wäre Saldo aufgebraucht
Benötigte UI-Elemente:
- Saldo-Anzeige
- Verbrauchs-Liste mit Filter
- Trend-Chart
Permissions: `billing.read`.
---
## Block K — Setup-Fee-Handling
### Anwendung
- Cloud-Plan: Setup-Fee einmalig
- Cloud+-Plan: Setup-Fee einmalig, höher (Pricing geparkt)
- Enterprise: individuell
### Konfiguration
- `SubscriptionProduct.setup_fee_required = true` aktiviert Pflicht-Setup-Fee
- Separater `SubscriptionPrice` mit `interval=one_time`
- Im Stripe-Checkout: zwei Items (recurring + one_time)
### Tracking
- `TenantSubscription.setup_fee_paid_at` wird gesetzt bei `invoice.payment_succeeded` der ersten Rechnung
- Vor Zahlung: Workspace ist im Trial- oder Pre-Active-Modus (vollfunktional, weil Trial)
- Falls Setup-Fee nicht gezahlt aber Subscription aktiv (Edge-Case): wie `past_due` behandeln
### Plan-Wechsel von Cloud → Cloud+
- Falls Setup-Fee schon für Cloud bezahlt: nur Differenz berechnen
- Logik: `effective_setup_fee = neuer_plan.setup_fee - bisherige_setup_fee_summe` (clamped >= 0)
---
## Block L — Demo-Buchung (extern)
### Konzept
Enterprise-Anfragen → Marketing-Site bietet Demo-Buchung über externes Tool (Calendly o.ä.). **Nicht** in HiveGrid integriert.
### Pflicht-Properties
- Marketing-Site `hivegrid.de/demo` mit Calendly-Embed
- Vertrieb erhält Termin, führt Demo, legt **manuell** Tenant über `admin.hivegrid.de` an (M37)
- Tenant erhält Initial-Login-Email mit Magic-Link (M27 B.2)
- `TenantSubscription.created_via = platform_admin`
### Was nicht in dieses Modul gehört
- Demo-Booking-Engine (das ist M6 Booking — wird aber **nicht** für Demo-Termine genutzt; M6 ist tenant-internal für Endkunden-Termine)
---
## Block M — Routes + In-App-Sicht
### Sidebar-Eintrag
Sidebar-Hauptpunkt **Admin** (Workspace-Admin, siehe M27 A.3) → Sub-Eintrag „Subscription".
### Routes
```
/{tenant}/admin/subscription/ → Subscription-Übersicht
/{tenant}/admin/subscription/plan-info/ → Plan-Details (Read-Only)
/{tenant}/admin/subscription/checkout-return/ → Stripe-Checkout-Return-Handler
/{tenant}/admin/usage/ → Verbrauchs-Übersicht (Trigger, AI-Token, Seats)
/{tenant}/admin/usage/ai-credits/ → AI-Credits-Detail
/{tenant}/admin/billing/ → Stripe-Customer-Portal-Embed (Rechnungen + Zahlungsmethode)
```
### `/admin/subscription/` — Übersicht
Zu zeigende Daten:
- Aktueller Plan-Name + Status (Klartext)
- Period-Start + Period-Ende
- Trial-Status falls aktiv
- Seat-Übersicht pro Typ
- Inklusiv-Quotas pro Metrik mit aktuellem Verbrauch
Benötigte UI-Elemente:
- Read-Only-Anzeige aller Plan-Eigenschaften (KEIN „Upgrade"-Button — LP-8)
- Hinweis-Box: *„Plan-Wechsel über deinen Account-Manager oder hivegrid.de"* mit Link nach extern (öffnet in neuem Tab)
- Pause-Button (Frozen-Modus, siehe Block H)
- Kündigen-Button
Operationen:
- Workspace pausieren (Block H)
- Tenant kündigen (M27 A.5)
- Status anzeigen
### `/admin/usage/`
Siehe Block I.
### `/admin/billing/`
Stripe-Customer-Portal-Embed (Stripe-gehostet, IFrame oder Redirect):
- Rechnungs-Historie (PDF-Download)
- Zahlungsmethode aktualisieren
- Steuer-Daten / USt-Id editieren
Permission: `billing.read` für Anzeige, `tenant.admin` für Zahlungsmethoden-Änderung.
### Was NICHT in der App ist (LP-8)
- Pricing-Tabelle / Plan-Vergleich
- Upgrade-Buttons
- Add-On-Käufe (Phase 2 evtl. via Marketing-Site)
- Promotional-Banner für höhere Plans
- Plan-Wechsel-UI
---
## Block N — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `billing.read` | Subscription-Übersicht, Usage, Rechnungen einsehen |
| `tenant.admin` | Plan-Wechsel, Pause/Reaktivierung, Kündigung, Zahlungsmethoden, Seat-Management |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `billing.none` | (keine) |
| `billing.read` | `billing.read` |
| `billing.admin` | `billing.read` + `tenant.admin`-Sub-Permissions für Subscription |
### Anwendung in Routes
- `/{tenant}/admin/subscription/` → `billing.read` oder `tenant.admin`
- `/{tenant}/admin/usage/` → `billing.read` oder `tenant.admin`
- `/{tenant}/admin/billing/` → `billing.read` oder `tenant.admin`
- Pause-/Kündigen-/Reaktivierung-Aktion → `tenant.admin`
### Anwendung in Action-Buttons
- Workspace pausieren: `tenant.admin`
- Workspace reaktivieren: `tenant.admin`
- Tenant kündigen: `tenant.admin` (zusätzlich Last-Tenant-Admin-Schutz, M27 D.4)
- Verbrauchs-Daten exportieren: `billing.read`
### Plattform-Admin-Sicht (M37)
- Sicht auf alle `TenantSubscription`-Datensätze
- Manuelle Trial-Aktivierung (`requires_manual_activation` Flow)
- Manuelle Subscription-Anlage für Enterprise
- Manuelle Credit-Grants (Bonus / Promo-Codes)
- Permission: `platform.billing.admin`
---
## Block O — Klartext-Hinweise/-Fehler
Pflicht-Texte (LP-10 + AV #1):
- **Trial-Aktivierungs-Email:** *„Dein HiveGrid-Trial ist freigeschaltet. Bis [Datum] kannst du alles testen. Bei Fragen: [Support-Link]"*
- **Trial-Ende-3-Tage-Warning:** *„Dein Trial endet in 3 Tagen am [Datum]. Plan wählen unter hivegrid.de"*
- **Trial-abgelaufen:** *„Dein Trial ist abgelaufen. Workspace ist read-only. Plan wählen unter hivegrid.de"*
- **Past-Due-Initial:** *„Zahlung gescheitert für Rechnung vom [Datum]. Wir versuchen es in [N] Tagen erneut. [Zahlungsmethode aktualisieren]"*
- **Past-Due-Final:** *„Letzter Zahlungsversuch fehlgeschlagen. Konto wird in 24h gesperrt. [Zahlungsmethode aktualisieren]"*
- **Frozen-Banner:** *„Workspace pausiert seit [Datum]. Reaktivieren um wieder zu schreiben."*
- **Read-Only-Klick auf Schreib-Button:** *„Diese Aktion ist nicht möglich, weil dein Workspace pausiert ist. [Reaktivieren]"*
- **Seat-Quota-erreicht:** *„Plan-Limit von [N] [Typ]-Seats erreicht. Plan-Wechsel über hivegrid.de"*
- **AI-Credits-aufgebraucht:** *„AI-Credits für diese Period verbraucht. Verfügbar wieder am [Period-Start]. Plan-Wechsel über hivegrid.de"*
- **Trigger-Volumen-Limit:** *„Automation-Trigger-Limit erreicht für diese Period. Eingehende Trigger werden verworfen bis [Period-Start]. Plan-Wechsel über hivegrid.de"*
- **Stripe-Webhook-Verarbeitungsfehler:** Plattform-Admin-Alert mit Klartext-Stack-Trace
- **Plan-Wechsel-Confirmation-Email:** *„Plan-Wechsel auf [Plan-Name] wirksam ab [Datum]. Differenz: [Betrag] EUR."*
- **Setup-Fee-Hinweis im Checkout:** *„Bei Buchung wird zusätzlich eine einmalige Setup-Gebühr von [Betrag] berechnet."*
### Fehler-Cases
| Fehler | Klartext + Lösungs-Hinweis |
|---|---|
| Stripe-Checkout-Session abgelaufen | *„Die Bezahl-Session ist abgelaufen. Bitte Plan-Wahl wiederholen."* + Direkt-Link |
| Stripe-Customer-Portal nicht erreichbar | *„Die Rechnungs-Verwaltung ist gerade nicht erreichbar. Bitte später erneut versuchen oder [Support-Link]"* |
| Plan-Wechsel auf nicht existierenden Plan | *„Der gewählte Plan ist nicht mehr verfügbar. Bitte aktuelle Plan-Liste auf hivegrid.de wählen."* |
| Setup-Fee-Zahlung fehlgeschlagen, Subscription aktiv | Plattform-Admin-Alert + Tenant-Admin-Klartext: *„Setup-Gebühr-Zahlung gescheitert. Bitte Zahlungsmethode prüfen — sonst wird Konto in 14 Tagen gesperrt."* |
| Webhook-Signature ungültig | 401-Response, Plattform-Admin-Alert (möglicher Angriff) |
| Tenant kündigt während Trial | Klartext: *„Dein Trial wurde beendet. Workspace wird in 30 Tagen gelöscht — [Zurückziehen]"* |
---
## Block P — Phase 2 / Backlog
Bewusst NICHT in Phase 1 (LP-8 + Apple-Compliance):
- **In-App-Subscription-Self-Service** (Plan-Wechsel direkt in der App ohne Marketing-Site-Umweg) — wartet auf App-Store-Compliance-Klärung
- **Add-On-Käufe** (zusätzliche Trigger-Volumen-Pakete, AI-Credits-Top-Ups) — Marketing-Site oder Phase-2-In-App
- **Multi-Tenant-Billing** für Konzerne (mehrere Tenants in einer Stripe-Subscription gebündelt)
- **Custom-Pricing-Tier** per Plattform-Admin (individuelle Preisverhandlung Enterprise)
- **Promo-Code-System** (Discount-Codes im Checkout)
- **Annual-Billing-Toggle** mit konfigurierbarem Jahres-Rabatt
- **Self-Service-Trial ohne Vertriebs-Freigabe** (`requires_manual_activation = false`-Modus, mit Zahlungsmethoden-Pflicht)
- **Reseller-Modell** (Agentur kauft Subscription für Endkunde-Tenant, eigene Margin)
- **Usage-Forecasting** (KI-basiert: „bei aktuellem Verbrauch wirst du den Plan in 7 Tagen sprengen")
- **Self-Service-Cancellation-Survey** mit Auto-Discount-Angebot
---
## Architektur-Vorschriften (Querschnitt)
- **AV #6 — Audit-Trail-Default:** Jede Subscription-Status-Änderung, jeder Plan-Wechsel, jede Credit-Veränderung geloggt mit Diff
- **AV #8 — Idempotenz pro Webhook-Verarbeitung:** Stripe-Events nicht doppelt verarbeiten (über `stripe_event_id`)
- **AV #5 — Permissions-aware-Default:** Listen / Verbrauchs-Sicht filtert nach `billing.read`/`tenant.admin`
- **LP-8 — Apple-Compliance:** keinerlei Pricing-/Upgrade-UI in App; alle externen Links öffnen in neuem Browser-Fenster mit `noopener noreferrer`
- **LP-10 + AV #1 — Klartext-Diagnostik:** alle Subscription-/Billing-Fehler menschenlesbar mit Lösungs-Hinweis
- **LP-13 — EU-Stack:** Stripe-Vertragspartner ist Stripe Payments Europe DAC (Ireland), DPA elektronisch unterzeichnet
- **AV #11 — Read-Only-Middleware** strukturell für alle Schreib-Pfade (Routes, API, Worker)
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 28. **Vor Bau:** Verifizierung mit Noah + Pricing-Modell-Konkretisierung (separate Runde). Konkrete Stripe-Price-IDs, Webhook-Endpoint-URLs, EU-Entity-Vertragsdetails kommen mit Implementierung.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkretes Pricing-Modell (Cloud/Cloud+/Enterprise-Preise, Trigger-Volumen-Schwellen, AI-Token-Mengen, Setup-Fee-Beträge, Frozen-Mode-Preis, Annual-Discount-%) — geparkt für eigene Runde
- Konkretes Branchen-Plan-Mapping (alle Branchen können alle Pläne, oder Branchen-spezifische Trial-Tage?)
- Genaue Stripe-Smart-Retries-Konfiguration vs. eigene Schedule
- Edge-Case bei Plan-Downgrade mid-period (Pro-rata vs. Period-End)
- Migration für Bestandskunden (Geerkens beim Go-Live) — Pricing-Modell-Festlegung erforderlich
- Konkrete Permission-IDs zusammen mit M27-Permission-Konsolidierung
- Subframe-UI-Designs (separat)