102 lines
6.5 KiB
Markdown
102 lines
6.5 KiB
Markdown
<!-- status: done -->
|
|
<!-- started: 2026-05-09 -->
|
|
<!-- completed: 2026-05-15 -->
|
|
<!-- component: gateway | frontend-nyla | platform -->
|
|
|
|
# Enterprise Subscription
|
|
|
|
## Beschreibung und Kontext
|
|
|
|
Enterprise-Kunden wollen mit Pauschalen arbeiten statt mit nutzungsbasierter Stripe-Abrechnung.
|
|
Der Sysadmin (Platform Admin) erstellt ein individuelles Abo mit fixen Limiten (Users, Features, Storage, AI-Budget) und einem Pauschalpreis. Die Abrechnung erfolgt per E-Mail-Rechnung, nicht über Stripe. Alle Limiten sind hart — Überschreitung wird blockiert, nicht nachverrechnet.
|
|
|
|
Business-Treiber: Grosse Kunden verlangen Planbarkeit und interne Verrechnung statt Kreditkarten-Abrechnung.
|
|
|
|
## Fokus und kritische Details
|
|
|
|
- `assertCapacity` muss bei Enterprise die Custom-Felder statt den Plan-Katalog lesen
|
|
- `creditSubscriptionBudget`, `adjustAiBudgetForUserChange`, `reconcileMandateStorageBilling` brauchen Enterprise-Guards
|
|
- AI-Budget Top-Up via Stripe bleibt für Enterprise-Mandanten weiterhin möglich (separater Flow)
|
|
- `syncQuantityToStripe` ist bereits sicher (Guard auf `stripeSubscriptionId=None`)
|
|
- `SubscriptionCapacityException.userAction` darf bei Enterprise nicht `UPGRADE_SUBSCRIPTION` sein
|
|
|
|
## Ziel und Nicht-Ziele
|
|
|
|
- Ziel: Sysadmin kann Enterprise-Abo erstellen, erneuern, anpassen; fixe Limiten mit Hard-Block; Rechnung per E-Mail an Mandate Admins
|
|
- Ziel: Auto-Renewal via Cron-Job (eventManager) für Enterprise-Abos mit autoRenew=True
|
|
- Ziel: Mandate Admin sieht Enterprise-Abo readonly im Dashboard
|
|
- Explizit NICHT: PDF-Invoice-System, Frontend Enterprise-Formular (Phase 2)
|
|
- Explizit NICHT: Enterprise als Self-Service für Mandate Admin
|
|
|
|
## Betroffene Module
|
|
|
|
- Gateway: datamodelSubscription, interfaceDbSubscription, interfaceDbBilling, interfaceDbApp, mainServiceSubscription, routeSubscription, routeBilling, enterpriseRenewalScheduler (neu), app.py
|
|
- Frontend: Subscription-Status-Anzeige (readonly für Enterprise), Sysadmin-Panel Enterprise-Badge
|
|
- DB-Migration: nein (neue Felder auf MandateSubscription, auto-schema)
|
|
- Andere Komponenten: E-Mail-Versand (notifyMandateAdmins, bestehende Logik)
|
|
|
|
## Entscheidungen
|
|
|
|
| Datum | Entscheidung | Begründung |
|
|
|-------|-------------|------------|
|
|
| 2026-05-09 | Custom-Werte auf MandateSubscription statt eigene Plan-Tabelle | Einfacher, kein neues DB-Schema nötig, Plan-Katalog bleibt statisch |
|
|
| 2026-05-09 | Rechnung als strukturierte E-Mail, kein PDF | Vertrag wird extern geregelt, E-Mail reicht als Bestätigung |
|
|
| 2026-05-09 | Renew = altes Abo EXPIRED + neues ACTIVE (Duplikat) | Saubere Audit-History, Budget-Gutschrift wie bei Erstaktivierung |
|
|
| 2026-05-09 | Auto-Renewal via eventManager.registerCron (täglich 06:00 UTC) | Bestehende APScheduler-Infrastruktur nutzen, analog Audit-Log-Cleanup |
|
|
| 2026-05-09 | Rechnungs-E-Mail nur an Mandate Admins | Gleiche Logik wie bestehende Pläne, kein Sysadmin als Empfänger |
|
|
| 2026-05-09 | Storage-Overage bei Enterprise: Hard-Block statt Pool-Abzug | Konsistent mit dem Pauschalen-Konzept |
|
|
|
|
## Umsetzungs-Checkliste
|
|
|
|
- [x] Datenmodell: `ENTERPRISE` in `BUILTIN_PLANS` + `enterprise*`-Felder auf `MandateSubscription` (`isEnterprise`, `enterpriseFlatPriceCHF`, `enterpriseMaxUsers`, `enterpriseMaxFeatureInstances`, `enterpriseMaxDataVolumeMB`, `enterpriseBudgetAiCHF`, `enterpriseNote`)
|
|
- [x] Helper: `getEffectiveLimits(sub, plan)` in `datamodelSubscription.py` — liest bei `isEnterprise` die Custom-Felder
|
|
- [x] Guard: `assertCapacity` → über `getEffectiveLimits` abgedeckt (Enterprise-Felder automatisch)
|
|
- [x] Guard: `creditSubscriptionBudget` → Enterprise-Budget-Gutschrift
|
|
- [x] Guard: `adjustAiBudgetForUserChange` → bei Enterprise übersprungen
|
|
- [x] Guard: `reconcileMandateStorageBilling` → bei Enterprise übersprungen
|
|
- [x] Guard: `getDataVolumeWarning` → Enterprise-Felder
|
|
- [x] Guard: `SubscriptionCapacityException` → `userAction=CONTACT_ADMIN` bei Enterprise
|
|
- [x] Service: `createEnterprise`, `renewEnterprise`, `updateEnterprise` in `mainServiceSubscription.py`
|
|
- [x] E-Mail: `_buildEnterpriseInvoiceHtml` + `_sendEnterpriseInvoiceEmail` via `notifyMandateAdmins`
|
|
- [x] Auto-Renewal: `enterpriseRenewalScheduler.py` via `eventManager.registerCron` (täglich 06:00 UTC)
|
|
- [x] Routes: `POST enterprise/create`, `POST enterprise/renew`, `PUT enterprise/update` in `routeSubscription.py`
|
|
- [x] Admin-View: `_buildEnrichedSubscriptions` + `_computeUsage` für Enterprise
|
|
- [x] RBAC / Permissions: alle 3 Endpoints `isPlatformAdmin`-only
|
|
- [x] Neutralisierung betroffen? Nein
|
|
- [x] Billing-Impact? Ja — neue Abrechnungsform
|
|
|
|
## Akzeptanzkriterien
|
|
|
|
| # | Kriterium (Given-When-Then) | Prio |
|
|
|---|---------------------------|------|
|
|
| 1 | Given Sysadmin, When POST enterprise/create mit validen Parametern, Then Enterprise-Abo ACTIVE mit Custom-Limiten + AI-Budget gutgeschrieben + Rechnung per E-Mail an Mandate Admins + Sysadmin | must |
|
|
| 2 | Given Enterprise-Abo aktiv, When Mandate Admin User 21 hinzufügen will (Limit=20), Then Hard-Block mit Meldung "Enterprise-Limit erreicht, kontaktieren Sie den Administrator" | must |
|
|
| 3 | Given Enterprise-Abo aktiv, When User hinzugefügt wird (unter Limit), Then KEIN pro-rata AI-Budget-Adjustment | must |
|
|
| 4 | Given Enterprise-Abo aktiv, When Storage-Nutzung steigt über Limit, Then Hard-Block, KEIN Pool-Abzug | must |
|
|
| 5 | Given Enterprise-Abo aktiv, When Mandate Admin AI-Budget Top-Up via Stripe macht, Then funktioniert wie bei normalem Abo | must |
|
|
| 6 | Given Enterprise-Abo aktiv, When Sysadmin PUT enterprise/update mit neuen Limiten, Then Limiten sofort wirksam | must |
|
|
| 7 | Given Enterprise-Abo aktiv, When Sysadmin POST enterprise/renew, Then altes Abo EXPIRED + neues ACTIVE + Budget + Rechnung | must |
|
|
| 8 | Given Enterprise-Abo aktiv, When Mandate Admin GET /status, Then sieht Enterprise-Abo mit Limiten und Nutzung (readonly) | must |
|
|
| 9 | Given Enterprise-Abo aktiv, When Mandate Admin versucht Plan zu wechseln, Then nicht möglich (kein Self-Service) | must |
|
|
|
|
## Testplan
|
|
|
|
| ID | AC | Art | Automatisiert | Repo-Pfad | Status |
|
|
|----|----|-----|--------------|-----------|--------|
|
|
| T1 | 1 | api | manuell | — | done |
|
|
| T2 | 2 | api | manuell | — | done |
|
|
| T3 | 3 | api | manuell | — | done |
|
|
| T4 | 4 | api | manuell | — | done |
|
|
| T5 | 5 | api | manuell | — | done |
|
|
| T6 | 6 | api | manuell | — | done |
|
|
| T7 | 7 | api | manuell | — | done |
|
|
| T8 | 8,9 | api | manuell | — | done |
|
|
|
|
## Links
|
|
|
|
- Cursor Plan: enterprise_subscription_aca22e32.plan.md
|
|
|
|
## Abschluss
|
|
|
|
- [x] Dieses Dokument Status → `done` (2026-05-15)
|
|
- [x] Eintrag in `c-work/_CHANGELOG.md`
|