756 lines
32 KiB
Markdown
756 lines
32 KiB
Markdown
---
|
|
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 Legacy-Provider. 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 + Legacy-Provider-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 (Legacy-Provider-Price-Mapping).
|
|
|
|
- `id`, `subscription_product_id` (FK)
|
|
- `legacyProvider_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` — Legacy-Provider-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)
|
|
- `legacyProvider_customer_id`, `legacyProvider_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_legacyProvider_at` (Timestamp, nullable)
|
|
- `created_at`
|
|
- Indexe auf `(tenant_subscription_id, metric_code, period_start)`
|
|
|
|
#### `CheckoutSessionStatus`
|
|
|
|
Tracking des Legacy-Provider-Checkout-Flows pro Tenant-Anlage.
|
|
|
|
- `id`, `tenant_id` (FK), `legacyProvider_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 → Legacy-Provider-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: Legacy-Provider-Checkout-Setup erfolgreich abgeschlossen |
|
|
| `trial` | `cancelled` | Trial läuft ab ohne Konversion → Tenant wird zu `deletion_pending` (M27) |
|
|
| `active` | `past_due` | Legacy-Provider-Webhook `invoice.payment_failed` |
|
|
| `past_due` | `active` | Nachzahlung erfolgreich (Legacy-Provider-Webhook `invoice.payment_succeeded`) |
|
|
| `past_due` | `cancelled` | Nach 14 Tagen + 3 Dunning-Versuchen erfolglos → Legacy-Provider 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, Legacy-Provider-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 + Legacy-Provider-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 + Legacy-Provider-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. Legacy-Provider-Checkout-Session-Erstellung mit `intent=initial_signup`
|
|
5. Redirect auf Legacy-Provider-Checkout (extern bei Legacy-Provider gehostet)
|
|
6. Nach Erfolg → `/{tenant}/onboarding/setup/` (siehe M29)
|
|
|
|
### Checkout-Konfiguration
|
|
|
|
- **Legacy-Provider-Customer** mit Tenant-`id` als `metadata.tenant_id`
|
|
- **Subscription-Setup** mit Trial (siehe Block E)
|
|
- **Steuer-Behandlung:** Legacy-Provider 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:** Legacy-Provider Ireland Ltd. (Legacy-Provider Payments Europe DAC — EU-Vertragspartner)
|
|
|
|
### Legacy-Provider-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 Legacy-Provider) |
|
|
| `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 `legacyProvider_event_id` als Unique-Constraint in einer `Legacy-ProviderWebhookLog`-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 + Legacy-Provider-Sync
|
|
|
|
- Bei Einladung/Aktivierung eines neuen Users: Seat-Counter hochzählen, Legacy-Provider-`Subscription.items[].quantity` updaten
|
|
- Bei Deaktivierung/Entfernung: Seat-Counter runter, Legacy-Provider-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)
|
|
- **Legacy-Provider:** 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 Legacy-Provider-Session-Token → CheckoutSessionStatus + Webhook-Verarbeitung → `active`-Übergang.
|
|
|
|
---
|
|
|
|
## Block F — Dunning + Past-Due
|
|
|
|
### Legacy-Provider-Standard-Dunning
|
|
|
|
- **3 Wiederholungs-Versuche** über **14 Tage** (Legacy-Provider 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 Legacy-Provider-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) |
|
|
| Legacy-Provider-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 Legacy-Provider-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. Legacy-Provider: 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. Legacy-Provider-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 Legacy-Provider-Subscription-Period — typisch monatlich)
|
|
|
|
### Reporting an Legacy-Provider
|
|
|
|
- Bei `metric_code` mit `is_metered=true`-Subscription-Item: Usage-Reporting an Legacy-Provider via `usage_records.create` am Period-Ende oder real-time (Strategie pro Metrik konfigurierbar)
|
|
- `reported_to_legacyProvider_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 Legacy-Provider-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/ → Legacy-Provider-Checkout-Return-Handler
|
|
/{tenant}/admin/usage/ → Verbrauchs-Übersicht (Trigger, AI-Token, Seats)
|
|
/{tenant}/admin/usage/ai-credits/ → AI-Credits-Detail
|
|
/{tenant}/admin/billing/ → Legacy-Provider-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/`
|
|
|
|
Legacy-Provider-Customer-Portal-Embed (Legacy-Provider-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"*
|
|
- **Legacy-Provider-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 |
|
|
|---|---|
|
|
| Legacy-Provider-Checkout-Session abgelaufen | *„Die Bezahl-Session ist abgelaufen. Bitte Plan-Wahl wiederholen."* + Direkt-Link |
|
|
| Legacy-Provider-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 Legacy-Provider-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:** Legacy-Provider-Events nicht doppelt verarbeiten (über `legacyProvider_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:** Legacy-Provider-Vertragspartner ist Legacy-Provider 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 Legacy-Provider-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 Legacy-Provider-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)
|