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

@@ -636,7 +636,7 @@ Activity-Typen produziert von Modul 6:
- **Reminder-Mails:** 24h/1h vor Termin automatisch
- **SMS-Reminder:** via Twilio/Sipgate (kostenpflichtige Add-on-Funktion)
- **Custom-Domain für Booking-Pages:** `termine.{tenant-domain}` statt `app.hivegrid.de/buch/{tenant}/...` (nur Enterprise)
- **Pre-Payment / Deposit:** Stripe-Vorauszahlung beim Buchen
- **Pre-Payment / Deposit:** Legacy-Provider-Vorauszahlung beim Buchen
- **Round-Robin mit Gewichtung:** Provider mit höherem Faktor bekommt mehr Termine
- **Workload-Cap pro Provider:** „max. 5 Termine pro Tag"
- **Tenant-Branding-Customization** auf öffentlicher Page (Logo, Farben — kommt aus Modul 31 in Phase 2)
@@ -991,7 +991,7 @@ PortalUser hat **keine** atomaren Permissions im M27-Stil. Stattdessen wirken im
- **Blog/CMS im Portal** (Tenant kann redaktionelle Inhalte für Endkunden veröffentlichen — Wartungs-Tipps, News)
- **Mehrere Portale pro Tenant** mit unterschiedlichem Branding/Slug (z.B. Privatkunden vs. Bauträger)
- **Portal-eigenes Branding** (eigenes Logo + Farben + Custom-Domain `portal.geerkens.de`)
- **PortalSubscription** (Wartungs-Abos, Service-Pakete im Portal abschließbar mit Stripe-Integration)
- **PortalSubscription** (Wartungs-Abos, Service-Pakete im Portal abschließbar mit Legacy-Provider-Integration)
- **Multi-Faktor-Auth für PortalUser** (TOTP-optional)
- **In-App-Notifications im Portal** (statt nur Email)
- **Bulk-Download** (ZIP) aller freigegebenen Dokumente
@@ -129,7 +129,7 @@ Status-Werte:
```
trial → Self-Service-Tenant in Trial-Phase (5-7 Tage)
active → Bezahlend
past_due → Stripe-Zahlung gescheitert, Read-Only-Modus
past_due → Legacy-Provider-Zahlung gescheitert, Read-Only-Modus
frozen → Tenant zahlt reduzierte Gebühr, Workspace read-only, jederzeit reaktivierbar
suspended → Manuell gesperrt von Plattform-Admin (z.B. AGB-Verstoß)
deletion_pending → Kündigung läuft, 30-Tage-Grace
@@ -138,7 +138,7 @@ deleted → Hard-Delete erfolgt
**Übergänge:**
- `trial → active`: nach Zahlungs-Setup
- `active → past_due`: Stripe-Webhook bei Fehlversuch
- `active → past_due`: Legacy-Provider-Webhook bei Fehlversuch
- `past_due → active`: nach Nachzahlung
- `past_due → deletion_pending`: nach 30 Tagen Read-Only
- `active → frozen`: User klickt „Workspace pausieren" + reduzierten Plan bestätigen
@@ -444,7 +444,7 @@ Wenn der zu deaktivierende User noch zugewiesene Entitäten hat, wird ein Bestä
```
SubscriptionProduct (z.B. "Cloud", "Cloud+", "Enterprise")
├── enthält viele SubscriptionFeatures (z.B. "crm", "automation", "kwp_integration")
└── verknüpft mit Stripe-Price
└── verknüpft mit Legacy-Provider-Price
TenantSubscription
└── verweist auf SubscriptionProduct + Status
```
@@ -493,7 +493,7 @@ Bezug aus Master-Session-Datei (Architektur-Vorschriften):
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 27. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep). Bei Implementierung dann konkrete Permission-IDs, RLS-Policy-SQL, Stripe-Price-IDs ergänzen.
Erste vollständige Detail-Spec für Modul 27. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep). Bei Implementierung dann konkrete Permission-IDs, RLS-Policy-SQL, Legacy-Provider-Price-IDs ergänzen.
**Offene Detail-Punkte (nicht-blockierend, beim Bau zu klären):**
- Konkrete Permission-IDs pro Modul (entstehen modulweise mit den jeweiligen Detail-Specs)
@@ -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
@@ -144,7 +144,7 @@ Tracking der Mitarbeiter-Einladungen (Verbindung zu M27 D.1 `TenantUserInvitatio
### Aufruf-Pfad
1. User schließt Self-Service-Signup ab (M27 A.1) → Tenant + Stripe-Subscription angelegt (M28)
1. User schließt Self-Service-Signup ab (M27 A.1) → Tenant + Legacy-Provider-Subscription angelegt (M28)
2. Bei erstem Login auf Tenant-Slug-Route: Auto-Redirect nach `/onboarding/setup/`
3. Wizard läuft → bei Abschluss Redirect nach `/{tenant}/`
@@ -11,7 +11,7 @@ spec_style: requirements-pur
# Modul 33a — Apps-Engine / Adapter-Layer
> **Detail-Spec gemäß LP-9.** Foundation für alle externen Integrationen (LP-11). Wenn das sauber ist, hängen sich KWP, AirCall, Gmail, Stripe, Calendar konsistent dran.
> **Detail-Spec gemäß LP-9.** Foundation für alle externen Integrationen (LP-11). Wenn das sauber ist, hängen sich KWP, AirCall, Gmail, Legacy-Provider, Calendar konsistent dran.
## Themenblöcke
@@ -152,7 +152,7 @@ User sieht nur Apps mit:
### Connect-Flow (pro Connection-Type unterschiedlich, aber UI einheitlich)
- **OAuth2** (Gmail, Microsoft, Google Calendar): Redirect-Flow → Auto-Token-Speicherung → Health-Check
- **API-Key** (PandaDoc, Stripe, Mistral): User trägt Key in Form ein → Validation → Speicherung
- **API-Key** (PandaDoc, Legacy-Provider, Mistral): User trägt Key in Form ein → Validation → Speicherung
- **Username/Password** (Legacy): User trägt Credentials → Validation
- **Windows-Client** (KWP): User lädt `kwpsync.exe` aus Setup-Wizard, konfiguriert lokal Server-DB-Connection-String, kwpsync.exe registriert sich beim Cloud-API mit Token
@@ -348,7 +348,7 @@ tenant-export-{tenantSlug}-{YYYY-MM-DD}.zip
- Nach 30 Tagen Hard-Delete aller Tenant-Daten inkl. Files
- Ab Hard-Delete: nicht wiederherstellbar
3. **Step 2 — Datensicherung-Hinweis:** *„Vor Lösch-Bestätigung empfehlen wir: Tenant-Daten-Export starten. [Export jetzt starten] [Habe ich bereits] [Daten brauche ich nicht]"*
4. **Step 3 — Stripe-Hinweis:** Klartext über Restbetrag, Pro-rata-Erstattung, letzte Rechnung
4. **Step 3 — Legacy-Provider-Hinweis:** Klartext über Restbetrag, Pro-rata-Erstattung, letzte Rechnung
5. **Step 4 — Identitäts-Bestätigung:** Pwd + 2FA falls aktiv
6. **Step 5 — Final-Klick** mit Tenant-Slug-Eingabe als Confirm-Phrase (User muss `geerkens-gmbh` eintippen, nicht nur einen Knopf drücken)
7. `TenantDeletionRequest` mit `reason=voluntary`, `grace_period_ends_at = now + 30 Tage` wird angelegt
@@ -360,7 +360,7 @@ tenant-export-{tenantSlug}-{YYYY-MM-DD}.zip
- Jeder Tenant-Admin kann mit einem Klick rückgängig machen → Status zurück auf `active` (oder vorherigen Status)
- Audit-Eintrag: wer hat gekündigt, wer hat zurückgezogen
- Stripe-Subscription wird bei Cancel reaktiviert (siehe Modul 28)
- Legacy-Provider-Subscription wird bei Cancel reaktiviert (siehe Modul 28)
### Hard-Delete-Cron (nach 30 Tagen)
@@ -385,13 +385,13 @@ tenant-export-{tenantSlug}-{YYYY-MM-DD}.zip
### Was bleibt nach Hard-Delete
- Audit-Metadata in `AdminAuditLog` (Modul 37): Tenant-ID, Slug, Lösch-Datum, Reason, Akteur
- Stripe-Records (von Stripe-Seite, gemäß deren Aufbewahrungs-Pflichten)
- Legacy-Provider-Records (von Legacy-Provider-Seite, gemäß deren Aufbewahrungs-Pflichten)
- Email-Logs vom Email-Provider (gemäß deren Retention)
- **Keine** PII, **keine** User-Inhalte
### Reasons außer `voluntary`
- `non_payment` — automatisch nach 30 Tagen `past_due` (Trigger: Stripe-Webhook-Logik in Modul 28); `TenantDeletionRequest` wird automatisch angelegt
- `non_payment` — automatisch nach 30 Tagen `past_due` (Trigger: Legacy-Provider-Webhook-Logik in Modul 28); `TenantDeletionRequest` wird automatisch angelegt
- `suspended_violation` — Plattform-Admin kündigt manuell wegen AGB-Verstoß; ggf. verkürzte Grace-Period
- `admin_initiated` — Plattform-Admin kündigt im Auftrag des Tenant-Admins (z.B. Email-Anfrage); Tenant-Admin bekommt Bestätigungs-Email mit Cancel-Link
@@ -399,7 +399,7 @@ tenant-export-{tenantSlug}-{YYYY-MM-DD}.zip
- Hard-Delete-Cron schlägt mittendrin fehl: Status `failed`, Resume-fähig (idempotente Lösch-Aktionen)
- Tenant-Daten-Export läuft noch beim Hard-Delete: Export-Job wird abgebrochen, ZIP gelöscht, Klartext im Audit
- Tenant-Admin kündigt während aktiver Subscription: Stripe-Cancel wird beim Hard-Delete-Cron getriggert (nicht beim Anlegen der `TenantDeletionRequest` — User soll noch zurückziehen können ohne Stripe-Doppel-Abbuchung)
- Tenant-Admin kündigt während aktiver Subscription: Legacy-Provider-Cancel wird beim Hard-Delete-Cron getriggert (nicht beim Anlegen der `TenantDeletionRequest` — User soll noch zurückziehen können ohne Legacy-Provider-Doppel-Abbuchung)
- Last-Tenant-Admin kündigt Tenant: erlaubt (anders als bei User-Löschung — Tenant-Kündigung ist explizit das Ende)
---
@@ -385,7 +385,7 @@ admin.hivegrid.de/settings/security → 2FA, Sessions
- Kontakt-Info (Email, Telefon, Adresse aus Signup)
- Tenant-Admins-Liste (welche User haben `tenant.admin`)
- Activity-Indikatoren: letzte 7/30 Tage, MAU, Speicher-Nutzung, KWP-Sync-Status
- Subscription-Detail: Plan, Seats, MRR, nächste Rechnung, Stripe-Customer-ID (mit Link zu Stripe-Dashboard)
- Subscription-Detail: Plan, Seats, MRR, nächste Rechnung, Legacy-Provider-Customer-ID (mit Link zu Legacy-Provider-Dashboard)
- Trial-Info (falls Trial): Restdauer, manuelle Verlängerung möglich
- Feature-Flag-Auswertungen für diesen Tenant (siehe Modul 32)
- Subprozessoren-Status (welche AVV-Version akzeptiert)
@@ -498,7 +498,7 @@ admin.hivegrid.de/settings/security → 2FA, Sessions
### Liste (`admin.hivegrid.de/subscriptions`)
**Zu zeigende Daten pro Eintrag:**
- Tenant-Name, Plan, MRR, Status (active, trialing, past_due, canceled), Renewal-Datum, Stripe-Sync-Status
- Tenant-Name, Plan, MRR, Status (active, trialing, past_due, canceled), Renewal-Datum, Legacy-Provider-Sync-Status
**Benötigte UI-Elemente:**
- Tabellarische Liste mit Filter (Plan, Status, MRR-Range)
@@ -508,14 +508,14 @@ admin.hivegrid.de/settings/security → 2FA, Sessions
### Detail (`admin.hivegrid.de/subscriptions/:id`)
**Zu zeigende Daten:**
- Stripe-Customer-ID, Subscription-ID (mit Link zu Stripe-Dashboard)
- Legacy-Provider-Customer-ID, Subscription-ID (mit Link zu Legacy-Provider-Dashboard)
- Aktueller Plan, Seats (Office + Field), MRR
- Trial-Status, Trial-Ende
- Rechnungs-History
- Override-Vermerke (manueller Plan / Sonderpreis)
**Operationen:**
- **Stripe-Sync forcieren** (zieht aktuellen Stripe-Stand und gleicht ab)
- **Legacy-Provider-Sync forcieren** (zieht aktuellen Legacy-Provider-Stand und gleicht ab)
- **Manuelle Override** für Enterprise-Kunden:
- Plan überschreiben
- Seats-Limit überschreiben
@@ -525,14 +525,14 @@ admin.hivegrid.de/settings/security → 2FA, Sessions
- Klartext-Hinweis im Tenant-Detail: *„Manuelle Konditionen aktiv — siehe Override-Vermerk"*
- **Trial verlängern** (analog Block G)
- **Manuelle Rechnung anstoßen** (für Setup-Fees, Custom-Onboarding)
- **Abo kündigen** (Stripe-Cancel + Tenant-Lösch-Workflow-Trigger)
- **Refund anstoßen** (mit Reason-Text + Stripe-Sync)
- **Abo kündigen** (Legacy-Provider-Cancel + Tenant-Lösch-Workflow-Trigger)
- **Refund anstoßen** (mit Reason-Text + Legacy-Provider-Sync)
**Permissions:** Lese `admin.subscriptions.read`, Schreib-Aktionen `admin.subscriptions.admin`.
### Stripe-Webhook-Sync
### Legacy-Provider-Webhook-Sync
- Events von Stripe (Subscription-Update, Payment-Failed, Invoice-Paid) werden automatisch in Tenant-Daten gespiegelt (Modul 28)
- Events von Legacy-Provider (Subscription-Update, Payment-Failed, Invoice-Paid) werden automatisch in Tenant-Daten gespiegelt (Modul 28)
- Manuelle Re-Sync-Funktion in diesem Bereich, falls Webhook ausgefallen war
---
@@ -814,12 +814,12 @@ admin.hivegrid.de/settings/security → 2FA, Sessions
- Tenant-Status-Wechsel ohne Reason-Text: Block mit Klartext *„Bitte Reason-Text angeben — wird im Audit-Log dauerhaft gespeichert."*
- Impersonate ohne Reason: Block analog
- Subscription-Override ohne Bestätigung: Modal *„Diese Konditionen weichen vom Standard-Plan ab. Stripe wird nicht angepasst — manuelle Rechnungs-Erstellung erforderlich. [Verstanden, fortfahren]"*
- Subscription-Override ohne Bestätigung: Modal *„Diese Konditionen weichen vom Standard-Plan ab. Legacy-Provider wird nicht angepasst — manuelle Rechnungs-Erstellung erforderlich. [Verstanden, fortfahren]"*
- AdminUser-Anlegen mit existierender Email: Klartext *„Diese Email gehört bereits zu einem AdminUser ‚X' — bitte direkt diesen verwalten."*
- Self-Permission-Schutz: *„Du bist der einzige Super-Admin. Permission-Entzug nicht möglich. Bitte zuerst weiteren Super-Admin anlegen."*
- AdminUser-Lockout durch zu viele Fehlversuche: Klartext *„Account gesperrt nach 10 Fehlversuchen. Bitte anderen Super-Admin um Reaktivierung bitten."*
- Tenant-Lösch-Anstoß im Auftrag: *„Du startest die Kündigung für Tenant ‚X' im Auftrag. Bestätigung-Email geht an alle Tenant-Admins mit Cancel-Link."*
- Stripe-Sync-Konflikt: *„Stripe-Stand und HiveGrid-Stand weichen ab. Bitte manuell prüfen: [Stripe-Wert] vs. [HiveGrid-Wert]."*
- Legacy-Provider-Sync-Konflikt: *„Legacy-Provider-Stand und HiveGrid-Stand weichen ab. Bitte manuell prüfen: [Legacy-Provider-Wert] vs. [HiveGrid-Wert]."*
- Worker-Queue-Pause: *„Queue ‚X' pausiert. Neue Jobs werden eingereiht aber nicht verarbeitet. Vergiss nicht zu reaktivieren!"*
- Cross-Tenant-Email-Bulk: *„Diese Email geht an X Tenant-Admins. Bitte nochmal Subject + Body prüfen. [Senden]"*
- Lead-Promote-to-Tenant: *„Tenant wird angelegt mit Initial-Admin [Email]. Bitte Subscription + Trial-Dauer wählen vor Anlage."*
@@ -862,7 +862,7 @@ Erste vollständige Detail-Spec für Modul 37. Bewusst breit, da Modul ein Hub f
- Konkrete AdminPermission-IDs final mit Modulen 32 und 35 abstimmen
- Impersonate-Mechanik technisch ausarbeiten (Cookie-Scope, Banner-Anzeige im App-Workspace)
- Inbound-Email-Parser für Support-Tickets (Provider-Wahl)
- Stripe-Webhook-Sync-Detail in Modul 28
- Legacy-Provider-Webhook-Sync-Detail in Modul 28
- Worker-Queue-Steuerungs-API (BullMQ-spezifisch)
- AVV-PDF-Templating (Template-Engine-Wahl)
- Subframe-UI-Designs separat
@@ -101,7 +101,7 @@ Index wird im Build geprüft (jede Kategorie-Referenz aus Frontmatter muss exist
**Mitarbeiter:** HR-Hub-Übersicht, Krankmeldung/Urlaubsantrag stellen
**Integrationen:** KWP-Setup, Google-Kalender verbinden, AirCall-Setup, Email-Integration (Gmail/Outlook)
**Mobile:** Mobile-App-Setup, Offline-Modus auf Baustelle
**Abrechnung:** Stripe-Setup, Plan wechseln, Rechnungen einsehen
**Abrechnung:** Legacy-Provider-Setup, Plan wechseln, Rechnungen einsehen
**Tutorials:** Form-Builder-Tutorial, Automation-Builder-Tutorial
(Konkrete Liste wird mit Plattform-Team beim Bau finalisiert.)