Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -11,14 +11,14 @@ 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`.
> **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 + Stripe-Checkout
C. Self-Service-Signup-Flow + Legacy-Provider-Checkout
D. Seat-Modell (Büro vs. Monteur)
E. Trial-Phase
F. Dunning + Past-Due
@@ -61,15 +61,15 @@ Ein Plan-Produkt (z.B. `Cloud`, `Cloud+`, `Enterprise` — Namen werden später
#### `SubscriptionPrice`
Konkreter Preispunkt (Stripe-Price-Mapping).
Konkreter Preispunkt (Legacy-Provider-Price-Mapping).
- `id`, `subscription_product_id` (FK)
- `stripe_price_id` (string, eindeutig)
- `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` — Stripe-konform)
- `tax_behavior` (Enum: `inclusive | exclusive` — Legacy-Provider-konform)
- `is_active`
- `valid_from`, `valid_until` (für preisliche Übergangsphasen)
@@ -115,7 +115,7 @@ 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`
- `legacyProvider_customer_id`, `legacyProvider_subscription_id`
- `started_at`, `current_period_start`, `current_period_end`
- `trial_start`, `trial_end`
- `cancel_at_period_end` (Boolean)
@@ -149,15 +149,15 @@ 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)
- `reported_to_legacyProvider_at` (Timestamp, nullable)
- `created_at`
- Indexe auf `(tenant_subscription_id, metric_code, period_start)`
#### `CheckoutSessionStatus`
Tracking des Stripe-Checkout-Flows pro Tenant-Anlage.
Tracking des Legacy-Provider-Checkout-Flows pro Tenant-Anlage.
- `id`, `tenant_id` (FK), `stripe_checkout_session_id`
- `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`
@@ -199,7 +199,7 @@ Status-Werte (entsprechen M27 A.5 Tenant-Status-Werten — `TenantSubscription.s
```
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)
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)
```
@@ -208,11 +208,11 @@ frozen → User pausiert Workspace, reduzierte Gebühr, Read-Only (siehe Blo
| Von | Nach | Trigger |
|---|---|---|
| `trial` | `active` | Trial-Konversion: Stripe-Checkout-Setup erfolgreich abgeschlossen |
| `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` | 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` | `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 |
@@ -222,7 +222,7 @@ frozen → User pausiert Workspace, reduzierte Gebühr, Read-Only (siehe Blo
### Übergangs-Hooks (Side-Effects)
Bei jedem Übergang wird ausgelöst:
- Audit-Log-Eintrag mit alt/neu Status, Trigger-Quelle, Stripe-Event-ID
- 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)
@@ -230,39 +230,39 @@ Bei jedem Übergang wird ausgelöst:
---
## Block C — Self-Service-Signup-Flow + Stripe-Checkout
## 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 + Stripe-Checkout
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. Stripe-Checkout-Session-Erstellung mit `intent=initial_signup`
5. Redirect auf Stripe-Checkout (extern bei Stripe gehostet)
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
- **Stripe-Customer** mit Tenant-`id` als `metadata.tenant_id`
- **Legacy-Provider-Customer** mit Tenant-`id` als `metadata.tenant_id`
- **Subscription-Setup** mit Trial (siehe Block E)
- **Steuer-Behandlung:** Stripe Tax aktiv, EU-Reverse-Charge-Logik
- **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:** Stripe Ireland Ltd. (Stripe Payments Europe DAC — EU-Vertragspartner)
- **EU-Entity-Präferenz:** Legacy-Provider Ireland Ltd. (Legacy-Provider Payments Europe DAC — EU-Vertragspartner)
### Stripe-Webhooks (Pflicht-Handling)
### 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 Stripe) |
| `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) |
@@ -271,7 +271,7 @@ Externer Pfad — siehe M27 A.1:
### Idempotenz
Webhook-Handler **Pflicht-idempotent** über `stripe_event_id` als Unique-Constraint in einer `StripeWebhookLog`-Tabelle (Schreib-Idempotenz, AV #8).
Webhook-Handler **Pflicht-idempotent** über `legacyProvider_event_id` als Unique-Constraint in einer `Legacy-ProviderWebhookLog`-Tabelle (Schreib-Idempotenz, AV #8).
---
@@ -294,10 +294,10 @@ Spiegelt LP-2 (Büro vs. Baustelle als kontextuelle Modi).
- 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
### Seat-Counting + Legacy-Provider-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)
- 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
@@ -324,7 +324,7 @@ Bei Erreichung Quota:
- **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
- **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
@@ -342,22 +342,22 @@ Bei Erreichung Quota:
### 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.
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
### Stripe-Standard-Dunning
### Legacy-Provider-Standard-Dunning
- **3 Wiederholungs-Versuche** über **14 Tage** (Stripe Smart Retries oder eigene Schedule)
- **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 Stripe-Customer-Portal
- 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`
@@ -396,14 +396,14 @@ Bei Status `past_due` ODER `frozen` ODER `cancelled` (mit `cancel_at_period_end=
| Customer-Portal-Zugang (Endkunden) | ✓ (read-only) |
| API (Read) | ✓ |
| API (Write) | ✗ (402) |
| Stripe-Customer-Portal-Zugang | ✓ (Pflicht zur Reaktivierung) |
| 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 Stripe-Webhook explizit invalidieren
- Cache der Status-Auflösung: 30 Sekunden (TTL), bei Legacy-Provider-Webhook explizit invalidieren
### Klartext-Hinweise
@@ -423,7 +423,7 @@ Tenant kann Workspace pausieren statt zu kündigen (z.B. Saison-Pause bei kleine
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)
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`
@@ -435,7 +435,7 @@ Tenant kann Workspace pausieren statt zu kündigen (z.B. Saison-Pause bei kleine
### Reaktivierungs-Flow
1. User klickt In-App-Banner „Reaktivieren"
2. Stripe-Checkout-Session mit `intent=reactivate_from_frozen` und gewähltem Standard-Plan
2. Legacy-Provider-Checkout-Session mit `intent=reactivate_from_frozen` und gewähltem Standard-Plan
3. Nach Erfolg: `frozen → active`-Übergang
### Sonderfälle
@@ -462,12 +462,12 @@ Engine baut bereits Tracking auf, **konkrete Pricing-Schwellen geparkt**:
- 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)
- Aggregation pro **Period** (entspricht Legacy-Provider-Subscription-Period — typisch monatlich)
### Reporting an Stripe
### Reporting an Legacy-Provider
- 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
- 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/`)
@@ -546,7 +546,7 @@ Permissions: `billing.read`.
- `SubscriptionProduct.setup_fee_required = true` aktiviert Pflicht-Setup-Fee
- Separater `SubscriptionPrice` mit `interval=one_time`
- Im Stripe-Checkout: zwei Items (recurring + one_time)
- Im Legacy-Provider-Checkout: zwei Items (recurring + one_time)
### Tracking
@@ -591,10 +591,10 @@ Sidebar-Hauptpunkt **Admin** (Workspace-Admin, siehe M27 A.3) → Sub-Eintrag
```
/{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/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/ → Stripe-Customer-Portal-Embed (Rechnungen + Zahlungsmethode)
/{tenant}/admin/billing/ → Legacy-Provider-Customer-Portal-Embed (Rechnungen + Zahlungsmethode)
```
### `/admin/subscription/` — Übersicht
@@ -623,7 +623,7 @@ Siehe Block I.
### `/admin/billing/`
Stripe-Customer-Portal-Embed (Stripe-gehostet, IFrame oder Redirect):
Legacy-Provider-Customer-Portal-Embed (Legacy-Provider-gehostet, IFrame oder Redirect):
- Rechnungs-Historie (PDF-Download)
- Zahlungsmethode aktualisieren
- Steuer-Daten / USt-Id editieren
@@ -695,7 +695,7 @@ Pflicht-Texte (LP-10 + AV #1):
- **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
- **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."*
@@ -703,8 +703,8 @@ Pflicht-Texte (LP-10 + AV #1):
| 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]"* |
| 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) |
@@ -718,7 +718,7 @@ 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)
- **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
@@ -732,23 +732,23 @@ Bewusst NICHT in Phase 1 (LP-8 + Apple-Compliance):
## 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 #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:** Stripe-Vertragspartner ist Stripe Payments Europe DAC (Ireland), DPA elektronisch unterzeichnet
- **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 Stripe-Price-IDs, Webhook-Endpoint-URLs, EU-Entity-Vertragsdetails kommen mit Implementierung.
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 Stripe-Smart-Retries-Konfiguration vs. eigene Schedule
- 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