Track HiveGrid Cloud planning reference
This commit is contained in:
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)
|
||||
Reference in new issue
Block a user