# Mandanten-Subscription & Kosten pro Mandant — Konzept

## Zweck und Abgrenzung

Dieses Dokument ergänzt [Billing-Konzept.md](./Billing-Konzept.md). Dort geht es um **LLM-Verbrauch** (Prepaid-Guthaben, Transaktionen, Provider-RBAC). Hier geht es um **SaaS-Lizenzierung pro Mandant**: wiederkehrende Pläne, enthaltene Kapazitäten (User, Feature-Instanzen), Stripe-Abrechnung der **Plattformgebühr**, und die Kopplung dieser Regeln an **Mandanten-Aktivität** und **Verbrauchs-Billing**.

**Ziel:** Ein Mandant ist nur dann voll **produktiv nutzbar**, wenn eine **aktive Subscription** existiert, die Kapazität und Zahlungsstatus abdeckt. Ohne gültige Subscription werden **AI-Calls blockiert**; Zugriff auf bestehende Daten (lesen, navigieren) bleibt erhalten. Das bestehende Usage-Billing (Token/Kosten) bleibt bestehen und wird um Subscription-Prüfungen erweitert.

**Kein Legacy-Modus:** Die Plattform ist noch nicht produktiv — es gibt keine Backwards Compatibility. Die Subscription ist ab Einführung **obligatorisch** für jeden Mandanten (Root-Mandant hat eine systemgenerierte Subscription).

---

## Bestand in der Codebase (Stand Analyse)

### Gateway

| Bereich | Rolle |
|--------|--------|
| `modules/serviceCenter/services/serviceBilling/` | Zentraler Billing-Service; Balance-Checks, Usage-Recording |
| `modules/serviceCenter/registry.py` | Registriert `billing` als importierbaren Service (`objectKey`: `service.billing`) |
| `modules/interfaces/interfaceDbBilling.py` | `checkBalance(mandateId, userId, estimatedCost)` — aktuell nur Prepaid-Logik (`PREPAY_USER` / `PREPAY_MANDATE`) |
| `modules/serviceCenter/services/serviceAi/mainServiceAi.py` | `_preflightBillingCheck`, `_checkBillingBeforeAiCall` — hier wird die Subscription-Prüfung integriert |
| `modules/datamodels/datamodelUam.py` | `Mandate` mit `enabled`, `isSystem` |
| `modules/datamodels/datamodelBilling.py` | `BillingSettings` pro Mandant — hier wird `stripeCustomerId` ergänzt |
| `modules/routes/routeBilling.py` | APIs inkl. Stripe Checkout für Top-Up (bestehend) |
| `modules/routes/routeAdminFeatures.py` | `create_feature_instance` — Stripe-Quantity-Sync hier einhängen |
| `modules/interfaces/interfaceDbApp.py` | `_assignUserToRootMandate`, `createUserMandate` — Stripe-Quantity-Sync hier einhängen |
| `modules/features/workspace/routeFeatureWorkspace.py` | Blockierung bei Billing-Problemen (Pattern für Subscription-Fehler nutzbar) |

### Frontend (Nyla)

| Bereich | Rolle |
|--------|--------|
| `frontend_nyla/src/pages/billing/*` | Dashboard, Mandanten-Ansicht, Admin, Stripe-Flow |
| `frontend_nyla/src/hooks/useBilling.ts` | Laden/Speichern der Billing-Settings pro Mandant |
| `frontend_nyla/src/pages/views/workspace/useWorkspace.ts` | Nutzung von `billingUiPath` / User-Actions bei Budget — gleiches Muster für **Subscription-Upgrade-Pfad** |

---

## 1. Wo die Subscription als „separater Container" leben soll

### Empfehlung

**Neuer Service parallel zu Billing:**  
`modules/serviceCenter/services/serviceSubscription/`  
mit klarer Schnittstelle zu Billing, aber **eigenem** Domänenmodell und Persistenz (Tabellen in `poweron_billing`-DB, da gemeinsamer Kontext).

**Begründung**

- **Billing** (`serviceBilling`) ist bereits auf **Verbrauch und Guthaben** fokussiert und wird von `ai` und Features als Dependency gezogen. Subscription ist **Vertrags- und Kapazitätslogik** (Zeiträume, Stripe Subscriptions, Limits). Vermischung in einer Klasse erhöht Komplexität und Testaufwand.
- Das **Service Center** ist der etablierte Ort für mandantenbezogene Querschnitts-Services (siehe `registry.py`). Ein Eintrag `subscription` neben `billing` erlaubt saubere Abhängigkeiten.
- Ein reines Ablegen unter `modules/subscription/` **ohne** Service-Center-Anbindung würde die bestehende Resolver-/RBAC-Konvention brechen.

### Orchestrierung

`BillingService.checkBalance` ruft intern `SubscriptionService.assertActive(mandateId)` auf. Call-Sites (z. B. `mainServiceAi`) prüfen weiterhin **eine** Methode — keine doppelten Aufrufe an 50 Stellen.

---

## 2. Lebenszyklus, Laufzeiten und Stripe

### Datenregeln

- Pro **Mandant** existieren **mehrere** Subscription-**Instanzen** (Historie, geplante Wechsel).
- Genau **eine** hat Status **aktiv** (`ACTIVE` oder `TRIALING`) für einen Zeitpunkt \(t\).
- Pflichtfeld **`startedAt`**. Optional **`endedAt`** (Kündigungs-/Enddatum).

### Laufzeiten und automatische Erneuerung

Jeder Plan hat eine **Laufzeit** (`billingPeriod`): **Monat** oder **Jahr**. Nach Ablauf einer Periode wird die Subscription **automatisch erneuert** (Stripe handhabt dies nativ über `interval: month | year`). Bei Erneuerung:

1. Stripe erstellt automatisch eine **Invoice** für die neue Periode.
2. Invoice wird eingezogen (Zahlungsmittel des Stripe Customer).
3. Bei Erfolg: Subscription bleibt `ACTIVE`, `currentPeriodEnd` wird aktualisiert.
4. Bei Fehlschlag: Subscription geht auf `PAST_DUE` → AI-Calls blockiert, E-Mail an Billing-Kontakt.

Pläne **ohne** Laufzeit (Root): `billingPeriod: none`, keine Stripe-Subscription, keine Erneuerung.

### Stripe: automatische wiederkehrende Verrechnung

Mit [Stripe Billing](https://stripe.com/docs/billing) (Products, Prices, **Subscriptions**) werden wiederkehrende Zahlungen **automatisch** eingezogen. Webhooks (`invoice.paid`, `invoice.payment_failed`, `customer.subscription.updated`, …) synchronisieren den Status in die eigene Datenbank.

### Source of Truth: App → Stripe

**Die App ist führend für Preis-Definitionen und Entitlements.** Stripe ist das Inkasso-System.

- Pläne und Preise werden in der App definiert und über die Stripe API als Products/Prices angelegt.
- Änderungen an Plänen **immer** über die App → Stripe-API. Nie manuell im Stripe Dashboard editieren.
- Stripe ist Source of Truth für den **Zahlungsstatus** (bezahlt, fehlgeschlagen, Rechnungs-PDF). Webhooks schreiben diesen Status in unsere DB.

---

## 3. Nutzungsbasierte Abrechnung (Usage-Based Quantity)

### Grundprinzip

**Es wird immer abgerechnet, was effektiv aktiv ist.** Der User wählt keinen festen maxUsers/maxFeatureInstances-Wert — die Subscription skaliert automatisch mit der tatsächlichen Nutzung. Wenn User oder Instanzen hinzukommen, wird **sofort nachverrechnet** (Stripe Proration).

### Mechanismus

Die Stripe-Subscription hat **zwei Subscription Items** mit dynamischer **Quantity**:

- **User-Seats Item:** `quantity` = Anzahl aktive `UserMandate` für diesen Mandanten
- **Instance Item:** `quantity` = Anzahl aktive `FeatureInstance` für diesen Mandanten

### Ablauf bei Mutations

```
User/Instanz wird hinzugefügt oder entfernt
    │
    ├─ 1. Lokale DB aktualisieren (UserMandate / FeatureInstance)
    │
    ├─ 2. Effektive Anzahl zählen:
    │     activeUsers = COUNT(UserMandate WHERE mandateId=X AND enabled=true)
    │     activeInstances = COUNT(FeatureInstance WHERE mandateId=X AND enabled=true)
    │
    ├─ 3. Stripe Subscription Items Quantity aktualisieren:
    │     stripe.subscription_items.update(userItemId, quantity=activeUsers)
    │     stripe.subscription_items.update(instanceItemId, quantity=activeInstances)
    │
    └─ 4. Stripe berechnet automatisch:
          - Proration für die laufende Periode (Teilperiode wird nachverrechnet)
          - Nächste Rechnung reflektiert die neue Quantity
```

### Proration

Stripe prorated **sofort** bei Quantity-Änderungen (Standardverhalten `proration_behavior: create_prorations`):

- **User hinzugefügt** Mitte des Monats → Nachverrechnung für die verbleibenden Tage auf der nächsten Rechnung.
- **User entfernt** Mitte des Monats → Gutschrift für die verbleibenden Tage auf der nächsten Rechnung.

### Kein manuelles Limit für Standard-Pläne

Beim Standard-Plan gibt es **keine harte Obergrenze** für Users oder Instanzen — der Mandant zahlt, was er nutzt. Die einzigen Limitierungen sind:

- **Trial:** harte Caps (`maxUsers: 1`, `maxFeatureInstances: 3`)
- **Root:** keine Limits, keine Abrechnung
- **Standard/Enterprise:** keine Plan-Caps, rein nutzungsbasiert

Das `maxUsers`/`maxFeatureInstances` auf dem Plan bleibt als **optionales** Feld für Pläne die harte Caps brauchen (Trial, zukünftige Budget-Pläne). Bei `None` = unbegrenzt = rein nutzungsbasiert.

---

## 4. Mandant nur „aktiv", wenn Subscription aktiv

### Semantik: Was wird blockiert?

Bei **fehlender oder inaktiver Subscription** (inkl. `PAST_DUE`, `EXPIRED`, `CANCELLED`) wird:

- **AI-Calls blockiert** — `_checkBillingBeforeAiCall` in `mainServiceAi.py` gibt strukturierten Fehler zurück.
- **Daten bleiben lesbar** — Workspace öffnen, Dokumente ansehen, Navigation, Export: alles weiterhin möglich. Nur **kostenverursachende Operationen** (AI) werden gesperrt.

Das bestehende Pattern in `routeFeatureWorkspace.py` (Zeile 807, Billing-Block) kann als Vorlage dienen, muss aber differenzieren: AI-Block ja, Read-Zugriff nein.

### `Mandate.enabled` vs. Subscription-Status

- **`Mandate.enabled`** bleibt für technische Admin-Sperren (z. B. Missbrauch).
- **Subscription-Status** steuert die geschäftliche Nutzbarkeit. Beides muss `true`/`ACTIVE` sein für volle Funktion.

### Root-Mandant

- Jeder neu registrierte User liegt im **Root-Mandanten** mit der **Root-Subscription**:
  - **Keine** Verrechnung über Stripe für diese Subscription.
  - **Unbegrenzt** für User und Feature-Instanzen.
  - Usage-Billing kann wie heute **PREPAY_USER** mit Startguthaben bleiben — Subscription blockiert Root nicht.
  - Root-Subscription wird beim **Bootstrap** automatisch erstellt.

---

## 5. E-Mail bei jeder Subscription-Änderung und bei Verrechnung

### Ereignisse (mindestens)

- Subscription **aktiviert**, **gewechselt**, **gekündigt** (Enddatum gesetzt), **erneuert**, **reaktiviert**.
- **Trial-Ende** → automatische Transition zu Standard (inkl. erster Rechnung).
- Stripe **Invoice paid** (Buchhaltungs-relevante Daten: Betrag, Periode, Steuern falls vorhanden, Stripe-Invoice-URL/PDF, Positionen inkl. User-Seats und Instance-Count).
- **Zahlung fehlgeschlagen** / Subscription **past_due**.
- **Quantity-Änderung** (User/Instanz hinzugefügt/entfernt) — optional als Zusammenfassung statt pro Einzelereignis.

### Empfänger

- **Mandanten-Billing-Kontakt** (bestehendes Feld aus `BillingSettings.notifyEmails`).

### Inhalt

- Maschinenlesbare Kurzfassung + **human-readable** für Buchhaltung (Referenznummern, Zeitraum, CHF, Positionen mit Quantity, Link zu Stripe-Invoice wo zulässig).

Technisch: analog zu `billingExhaustedNotify.py` einen **SubscriptionNotify**-Pfad; Templates über `serviceMessaging`.

---

## 6. Pydantic-Modelle (Definition + Verrechnung + mehrsprachige UI-Texte)

### A) SubscriptionPlan (Katalog)

Beschreibt **was** verkauft wird. Nicht pro Mandant dupliziert; sysadmin-gepflegt, versionierbar.

- `planKey: str` (z. B. `STANDARD_MONTHLY`, `STANDARD_YEARLY`, `TRIAL_7D`, `ROOT`)
- `selectableByUser: bool` — `false` für Root, zukünftige interne Pläne
- **Mehrsprachige Texte:** `title: dict[str, str]`, `description: dict[str, str]` (`en` / `de` / `fr` …)
- **Verrechnungsparameter:**
  - `currency: str` (fix `CHF`)
  - `billingPeriod: str` (`monthly` | `yearly` | `none`)
  - `pricePerUserCHF: float` (Beispiel: 200.00 pro Periode)
  - `pricePerFeatureInstanceCHF: float` (Beispiel: 400.00 pro Periode)
  - `autoRenew: bool` (default `true` — Stripe erneuert automatisch)
- **Optionale Kapazitäts-Caps** (nur für Pläne mit harten Grenzen):
  - `maxUsers: Optional[int]` — `None` = unbegrenzt (Standard, Root)
  - `maxFeatureInstances: Optional[int]` — `None` = unbegrenzt (Standard, Root)
  - `trialDays: Optional[int]` — nur bei Trial-Plänen (z. B. 7)
  - `successorPlanKey: Optional[str]` — Plan, auf den bei Trial-Ende automatisch gewechselt wird (z. B. `STANDARD_MONTHLY`)
- **Stripe-Mapping:**
  - `stripeProductId: Optional[str]`
  - `stripePriceIdUsers: Optional[str]` (Price für User-Seat Item, mit `recurring.interval`)
  - `stripePriceIdInstances: Optional[str]` (Price für Instance Item, mit `recurring.interval`)

### B) MandateSubscription (Instanz am Mandanten)

- `id: str`, `mandateId: str`
- `planKey: str` — Referenz zum SubscriptionPlan
- **Snapshot** der Plan-Parameter bei Aktivierung (für Rechnungshistorie):
  - `snapshotPricePerUserCHF`, `snapshotPricePerInstanceCHF`
- **Status und Laufzeit:**
  - `status: str` — `ACTIVE | CANCELLED | EXPIRED | PAST_DUE | TRIALING`
  - `startedAt: datetime` (Pflicht), `endedAt: Optional[datetime]`
  - `currentPeriodStart: datetime`, `currentPeriodEnd: datetime` — aktuelle Abrechnungsperiode (synchron mit Stripe)
  - `trialEndsAt: Optional[datetime]`
- **Stripe:** `stripeSubscriptionId: Optional[str]`, `stripeItemIdUsers: Optional[str]`, `stripeItemIdInstances: Optional[str]`

### Stripe-Customer gehört zum Mandant, nicht zur Subscription

**`stripeCustomerId`** wird auf **`BillingSettings`** ergänzt (1:1 pro Mandant, existiert bereits). Begründung: Ein Stripe Customer repräsentiert die **Organisation**. Wenn Mandant A Subscription 1 kündigt und Subscription 2 startet, nutzen beide denselben Stripe Customer — Zahlungsmittel, Rechnungshistorie und Kontaktdaten bleiben erhalten.

```
BillingSettings (existierend, erweitert)
├── stripeCustomerId: Optional[str]  ← NEU
├── billingModel (PREPAY_MANDATE | PREPAY_USER)
├── notifyEmails, warningThreshold, ...

MandateSubscription (neu)
├── stripeSubscriptionId  ← auf Subscription-Ebene
├── stripeItemIdUsers, stripeItemIdInstances
├── currentPeriodStart, currentPeriodEnd  ← Laufzeit-Tracking
```

### C) Effective Usage (für Abrechnung, nicht eigenes Modell)

- Aktuelle Anzahl **aktive User** mit Mandantenzugriff: `COUNT(UserMandate WHERE mandateId = X AND enabled)`
- Aktuelle Anzahl **aktive Feature-Instanzen** des Mandanten: `COUNT(FeatureInstance WHERE mandateId = X AND enabled)`

Diese Werte werden bei jeder Mutation als **Stripe Quantity** synchronisiert → Abrechnung stets korrekt.

---

## 7. Getrennte Prüfzeitpunkte (Hot Path vs. Mutations)

### Designprinzip

Subscription-Prüfungen müssen an **zwei klar getrennten Stellen** erfolgen — **nicht** alles in einem einzigen Gate bei jedem AI-Call:

| Prüfzeitpunkt | Was wird geprüft | Warum getrennt |
|---|---|---|
| **AI-Call** (hot path, jeder Request) | 1. Subscription aktiv? 2. Budget ausreichend? | Schnell, gecacht; ändert sich selten |
| **User-Add / Instance-Create** (Mutation) | 1. Kapazitäts-Cap (nur bei Plänen mit harten Limits, z. B. Trial) 2. Stripe-Quantity aktualisieren | Nur bei strukturellen Änderungen |
| **Periodischer Job** (Konsistenz) | Stripe-Quantity vs. DB-Count abgleichen | Sicherheitsnetz für Drift |

**Kapazität wird bewusst NICHT im AI-Hot-Path geprüft**, weil:

- User- und Instanz-Zahlen ändern sich nicht zwischen AI-Calls
- Das Zählen von DB-Records bei jedem AI-Call wäre teuer und sinnlos
- Enforcement an den Mutations-Endpunkten ist vollständig und ausreichend

### 7a. AI-Call Gate (Hot Path)

In `mainServiceAi._checkBillingBeforeAiCall`:

1. **Subscription-Status prüfen** (gecacht, siehe Caching unten)  
   → `ACTIVE` oder `TRIALING`? weiter. Sonst: blockieren.
2. **Budget prüfen** (bestehende `checkBalance`-Logik)  
   → ausreichend? weiter. Sonst: blockieren wie bisher.

**Erweiterung von `BillingCheckResult`:**

- `reason`: bestehende (`INSUFFICIENT_BALANCE`) + neue (`SUBSCRIPTION_INACTIVE`, `SUBSCRIPTION_PAYMENT_REQUIRED`, `SUBSCRIPTION_EXPIRED`)
- `upgradeRequired: bool`
- `subscriptionUiPath: Optional[str]` — z. B. `/billing?tab=subscription`
- `userAction`: bestehende (`TOP_UP_SELF`, `CONTACT_MANDATE_ADMIN`) + neue (`UPGRADE_SUBSCRIPTION`, `REACTIVATE_SUBSCRIPTION`, `ADD_PAYMENT_METHOD`)

**Implementierung:** `BillingService.checkBalance` ruft intern zuerst `SubscriptionService.assertActive(mandateId)` auf. Wenn Subscription nicht aktiv → sofort `BillingCheckResult(allowed=False, reason=...)` zurückgeben, ohne Budget-DB-Roundtrip.

### Caching des Subscription-Status

Der Subscription-Status ändert sich selten (Plan-Wechsel, Zahlung fehlgeschlagen). Für den AI-Hot-Path:

- **In-Memory Cache** mit TTL (z. B. 60 Sekunden)
- **Cache-Key:** `mandate:{mandateId}:subscription_status`
- **Invalidierung:** Stripe-Webhook-Handler und lokale Mutations (Plan-Wechsel, Kündigung, Trial-Ablauf) setzen den Cache zurück
- **Fallback:** Bei Cache-Miss → DB-Query, Result cachen

### 7b. Mutations-Gate (User-Add, Instance-Create, Remove)

**Bei User-Add / Instance-Create:**

1. **Falls Plan harte Caps hat** (z. B. Trial: `maxUsers: 1`, `maxFeatureInstances: 3`):  
   Prüfen `currentActive + 1 <= plan.maxUsers/maxFeatureInstances`.  
   Bei Überschreitung: HTTP 402 mit strukturiertem Error.

2. **Lokale DB aktualisieren** (UserMandate / FeatureInstance).

3. **Stripe-Quantity synchronisieren** (nur bei Plänen mit Stripe-Subscription):  
   `stripe.subscription_items.update(itemId, quantity=newActiveCount)`  
   → Proration wird automatisch erstellt.

**Bei User-Remove / Instance-Deaktivieren:**

1. Lokale DB aktualisieren.
2. Stripe-Quantity reduzieren → Gutschrift auf nächster Rechnung.

**Error-Response bei Cap-Überschreitung (Trial):**

```python
{
    "error": "SUBSCRIPTION_USER_LIMIT",
    "currentCount": 1,
    "maxAllowed": 1,
    "message": "...",
    "userAction": "UPGRADE_SUBSCRIPTION",
    "subscriptionUiPath": "/billing?tab=subscription"
}
```

### 7c. Downgrade-Regeln

Wenn ein Mandant auf einen Plan **mit harten Caps** wechseln will (z. B. von Standard auf einen zukünftigen Budget-Plan):

**Regel:** Downgrade ist **nur erlaubt**, wenn `effective <= new entitlement`.

- Bevor der Plan-Wechsel committed wird: prüfen `currentActiveUsers <= newPlan.maxUsers` AND `currentActiveInstances <= newPlan.maxFeatureInstances`.
- Wenn nicht erfüllt: Fehler mit klarer Meldung.
- Stripe-Subscription wird **erst** aktualisiert, wenn die lokale Prüfung bestanden ist.

### 7d. UI: Upgrade und Subscription-Management

Wenn `reason` eine Subscription-Kategorie ist:

- API-Responses (HTTP 402 oder strukturiertes SSE-Error-Objekt) enthalten `subscriptionUiPath` und `userAction` (analog bestehendem `TOP_UP_SELF` / `billingUiPath` in `useWorkspace.ts`).
- Frontend zeigt Call-to-Action und **Navigation** zur Subscription-/Billing-Seite.
- Auf der Subscription-Seite: Plan-Auswahl (nur `selectableByUser: true`), aktuelle Nutzung (Users / Instanzen), Kosten-Vorschau, Stripe Checkout/Update-Flow.

---

## 8. Checks bei User-Zuordnung und Feature-Instanzen

### Triggerpunkte (Gateway)

- **User zum Mandanten hinzufügen** (`interfaceDbApp.createUserMandate`, `routeInvitations` bei Einladungsannahme):
  1. Cap-Check (nur bei Plänen mit `maxUsers`)
  2. DB Insert
  3. Stripe-Quantity-Sync
- **Feature-Instanz erstellen** (`routeAdminFeatures.create_feature_instance`):
  1. Cap-Check (nur bei Plänen mit `maxFeatureInstances`)
  2. DB Insert
  3. Stripe-Quantity-Sync
- **User entfernen / Instanz deaktivieren:**
  1. DB Update
  2. Stripe-Quantity-Sync (reduzieren → Gutschrift)

### Was zählt als „aktiv"?

- **User:** nur `UserMandate`-Einträge mit `enabled = true`. Einladungen zählen **nicht**.
- **Feature-Instanzen:** nur Instanzen mit `enabled = true`. Entwürfe/deaktivierte zählen **nicht**.

### Periodische Konsistenz

Job, der Stripe-Quantity vs. DB-Count vergleicht und bei Abweichung:

1. Stripe-Quantity korrigieren (auf den DB-Count setzen)
2. **Warn-Mail** an `notifyEmails`
3. Log-Eintrag mit Details

---

## Beispiel-Pläne

| Plan | planKey | selectableByUser | billingPeriod | maxUsers | maxInstances | Preis pro Periode | Bemerkung |
|------|---------|-------------------|---------------|----------|--------------|-------------------|-----------|
| **Standard monatlich** | `STANDARD_MONTHLY` | ja | `monthly` | unbegrenzt | unbegrenzt | CHF `activeInstances * 400 + activeUsers * 200` | Nutzungsbasiert, Stripe-Quantity = aktive Anzahl |
| **Standard jährlich** | `STANDARD_YEARLY` | ja | `yearly` | unbegrenzt | unbegrenzt | CHF `activeInstances * 4'000 + activeUsers * 2'000` | Gleich wie monatlich, Jahresdiscount möglich |
| **Trial 7 Tage** | `TRIAL_7D` | ja | `none` | 1 | 3 | 0 CHF | Nach Ablauf → automatisch `STANDARD_MONTHLY` |
| **Root** | `ROOT` | nein | `none` | unbegrenzt | unbegrenzt | keine Stripe-Subscription | Bootstrap; Default für Root-Mandant |
| **Enterprise** (zukünftig) | `ENTERPRISE_DEFAULT` | nein | `yearly` | per Vertrag | per Vertrag | individuell | Default bei neuem Mandanten durch SysAdmin |

### Trial-Ende: automatischer Wechsel zu Standard

Wenn `trialEndsAt` erreicht ist:

1. Trial-Subscription erhält Status `EXPIRED`.
2. **Automatisch** wird eine neue `STANDARD_MONTHLY`-Subscription erstellt (der Plan aus `successorPlanKey`).
3. Stripe-Subscription wird angelegt mit `quantity` = aktuelle aktive User / Instanzen.
4. **Erste Rechnung** wird von Stripe erstellt und eingezogen.
5. E-Mail an Billing-Kontakt: „Ihre Testphase ist abgelaufen. Ihr Mandant wurde automatisch auf den Standard-Plan umgestellt."

**Voraussetzung:** Beim Trial-Signup wird bereits ein **Zahlungsmittel** hinterlegt (Stripe Customer mit PaymentMethod). Falls kein Zahlungsmittel hinterlegt ist:

- Stripe-Subscription wird trotzdem erstellt, erste Invoice **schlägt fehl**.
- Subscription geht auf `PAST_DUE` → AI-Calls blockiert.
- UI zeigt prominenten Hinweis: „Bitte hinterlegen Sie ein Zahlungsmittel, um den Standard-Plan zu aktivieren."
- `userAction: ADD_PAYMENT_METHOD`

---

## Abhängigkeiten und Reihenfolge (Implementierung)

1. **Datenmodell + DB** für `SubscriptionPlan` (Katalog mit `billingPeriod`, `successorPlanKey`) und `MandateSubscription` (Instanzen mit `currentPeriodStart/End`) + `stripeCustomerId` auf `BillingSettings`.
2. **Bootstrap:** Root-Plan und Root-Subscription für den Root-Mandanten automatisch erstellen.
3. **SubscriptionService** mit `assertActive(mandateId)` (gecacht) und `assertCapacity(mandateId, resourceType, delta)` (nur für Pläne mit Caps).
4. **AI-Gate:** `BillingService.checkBalance` ruft `SubscriptionService.assertActive` auf; erweiterte `BillingCheckResult`.
5. **Mutations-Hooks:** In `createUserMandate` und `create_feature_instance`: Cap-Check + Stripe-Quantity-Sync. Analog bei Remove/Deaktivieren.
6. **Stripe:** Customer-Erstellung bei erstem bezahltem Plan; Subscription-Erstellung mit zwei Items (User + Instance); Webhook-Handler für `invoice.paid`, `invoice.payment_failed`, `customer.subscription.updated`, `customer.subscription.deleted`, `customer.subscription.trial_will_end`.
7. **Trial-Ende-Handler:** Cron oder Stripe-Webhook `customer.subscription.trial_will_end` → automatischer Plan-Wechsel zu `successorPlanKey`.
8. **Downgrade-Prüfung** in Plan-Wechsel-Endpunkt.
9. **Frontend:** Subscription-Tab unter Billing, Plan-Auswahl, aktuelle Nutzung, Kosten-Vorschau, Stripe Checkout/Update-Flow, Deep-Links aus Fehler-Responses.
10. **E-Mails** und Buchhaltungs-Payloads.

---

## Geklärte fachliche Entscheide

- **Kündigung:** Zugriff bis **Ende der bezahlten Periode**. Umsetzung via Stripe `cancel_at_period_end: true` — Subscription bleibt bis Periodenende `ACTIVE`, wechselt dann auf `CANCELLED`. Keine sofortige Sperre.
- **Feature-Instanz-Limit im Trial:** maximal **3** Feature-Instanzen. Bestätigt.
- **Proration bei Seat-Änderungen:** **sofort** nachverrechnet. Stripe `proration_behavior: create_prorations` (Default) — Teilperiode wird auf der nächsten Rechnung nachbelastet bzw. gutgeschrieben.

- **Jahresdiscount:** Vorerst **kein** Discount für den Jahresplan. Jahrespreis = 12 × Monatspreis. Kann später als Incentive eingeführt werden.

Das Konzept ist damit **implementierungsreif** — keine offenen fachlichen Punkte.

---

## Verwandte Dokumente

- [Billing-Konzept.md](./Billing-Konzept.md) — LLM-Verbrauch, Prepaid, Transaktionen
- `wiki/implementation/Saas Multi Tenant Mandate/` — Mandanten-RBAC und UI-Hintergrund

---

## Anhang: Relevante Code-Pfade (Referenz)

### Bestehend (zu erweitern)

```
gateway/modules/serviceCenter/services/serviceBilling/mainServiceBilling.py  # checkBalance → + assertActive
gateway/modules/serviceCenter/services/serviceAi/mainServiceAi.py           # _checkBillingBeforeAiCall
gateway/modules/interfaces/interfaceDbBilling.py                            # checkBalance
gateway/modules/interfaces/interfaceDbApp.py                                # createUserMandate → + Cap-Check + Stripe-Quantity
gateway/modules/routes/routeAdminFeatures.py                                # create_feature_instance → + Cap-Check + Stripe-Quantity
gateway/modules/routes/routeBilling.py                                      # Stripe-Webhooks erweitern
gateway/modules/serviceCenter/registry.py                                   # subscription-Service registrieren
gateway/modules/datamodels/datamodelBilling.py                              # BillingSettings + stripeCustomerId
                                                                            # BillingCheckResult + neue reasons
frontend_nyla/src/pages/billing/                                            # Subscription-Tab
frontend_nyla/src/hooks/useBilling.ts                                       # Subscription-Daten laden
frontend_nyla/src/pages/views/workspace/useWorkspace.ts                     # subscriptionUiPath / userAction
```

### Neu

```
gateway/modules/datamodels/datamodelSubscription.py                         # SubscriptionPlan, MandateSubscription
gateway/modules/interfaces/interfaceDbSubscription.py                       # CRUD + assertActive + assertCapacity
gateway/modules/serviceCenter/services/serviceSubscription/
    mainServiceSubscription.py                                              # Service mit Cache, Stripe-Sync, Trial-Handler
gateway/modules/routes/routeSubscription.py                                 # Plan-Auswahl, Wechsel, Status-Abfrage
```