kaffeekasse-saas/docs/billing.md

# Preis- und Abrechnungslogik

Stand: 2026-07-16

Geplante Architektur (mit dem Kunden abgestimmt): **Stripe Billing für den
Zahlungseinzug, bestehendes Dolibarr für Rechnungsstellung/Buchhaltung.**
Kein eigenes Rechnungssystem, kein zusätzliches ERP nur für Kaffeeliste –
siehe Begründung unten.

## Warum diese Aufteilung

Drei getrennte Probleme:

1. **Rechnung erzeugen** – löst Dolibarr (bereits im Einsatz für ein
   anderes Business des Kunden), fortlaufend nummeriert, GoBD-konform.
2. **Geld tatsächlich einziehen** – der eigentlich schwierige Teil
   (wiederkehrende Belastung, Fehlschlag-Wiederholung, Zahlungsmittel-
   Verwaltung). Weder ein selbstgebautes System noch Dolibarr allein lösen
   das; ein Zahlungsanbieter mit Abo-Logik schon.
3. **Tarif-/Nutzungsstand verwalten** – das übernimmt Kaffeeliste selbst,
   da die Teilnehmerzahl je Mandant ohnehin schon vorhanden ist.

Empfehlung: **Stripe Billing** statt Mollie, weil eine echte
Abo-Logik mit automatischem Stufenwechsel gebraucht wird (Stripes
Billing-Produkt ist dafür ausgereifter als Mollies Subscriptions-API);
Mollie ist bei SEPA-Lastschrift günstiger, aber weniger auf SaaS-Abos
zugeschnitten.

## Phase 1: Datenmodell und Tariflogik (umgesetzt, keine externen Zugänge nötig)

Umgesetzte Dateien:

```text
database/migrations/0014_saas_tenant_billing.sql
app/billing.php
app/saas-auth.php (Init bei Registrierung)
mandant-einstellungen.php (Anzeige "Abo & Tarif")
app/platform-admin.php, backoffice.php (Tarif-Spalte im Back-Office)
```

- Neue Tabelle `tenant_billing`: `plan_code`, `subscription_status`,
  `stripe_customer_id`, `stripe_subscription_id`, `current_period_end`,
  `dolibarr_thirdparty_id` (letztere beide vorbereitet für Phase 2/3,
  noch ungenutzt).
- `billing_plans()` ist die einzige Quelle für die Tarifstufen
  (`free`/`basic`/`plus`/`pro`/`enterprise`), synchron mit den Preisen auf
  `preise.php`.
- `billing_required_plan_code()` errechnet anhand der aktiven
  Teilnehmerzahl die günstigste ausreichende Stufe.
- `billing_check_tenant()` vergleicht gebuchten mit benötigtem Tarif;
  rein informativ – **kein Enforcement**, kein Sperren bei Überschreitung.
  Solange Stripe nicht angebunden ist, wird bei Bedarf manuell
  umgestellt (Hinweistext verweist auf Kontakt per E-Mail).
- Neue Mandanten starten automatisch mit `plan_code = 'free'`.
- Owner/Admin sehen ihren aktuellen Tarif und die aktive Teilnehmerzahl
  unter „Abo & Tarif" auf `mandant-einstellungen.php`; bei Bedarf einer
  höheren Stufe erscheint ein Hinweis.
- Das Back-Office (`backoffice.php`) zeigt zusätzlich zur Mandantenliste
  den gebuchten Tarif und, falls abweichend, den tatsächlich benötigten
  Tarif – der Betreiber sieht auf einen Blick, wer manuell hochgestuft
  werden müsste.

Live getestet: Tarifgrenzen-Berechnung (10/25/50/150) mit einem Mandanten
knapp unter und einem mit 12 Teilnehmern (über dem Freikontingent, korrekt
als „basic" erkannt) geprüft; UI-Anzeige in Mandant-Einstellungen und
Back-Office live verifiziert. Alle bestehenden M8-Isolationstests und der
Rollen-Matrix-Test bleiben unverändert grün.

## Phase 2: Stripe-Anbindung (umgesetzt)

Umgesetzte Dateien:

```text
app/stripe.php
app/billing.php (Stripe-Preis-Auflösung ergänzt)
abo-upgrade.php
abo-portal.php
stripe-webhook.php
mandant-einstellungen.php (Upgrade-/Portal-Buttons)
```

- `app/stripe.php`: minimaler REST-Client für die Stripe-API auf Basis von
  PHP-Streams (`file_get_contents` + `stream_context_create`), **kein**
  vendortes SDK und **kein** composer.json nötig – diese PHP-Installation
  hat ohnehin keine curl-Extension, Streams sind portabler.
- Für jeden bezahlten Tarif (`basic`/`plus`/`pro`) wurde per API ein
  Stripe-Produkt mit monatlichem Preis angelegt, referenziert über einen
  stabilen `lookup_key` (`kaffeeliste_basic`/`_plus`/`_pro`) statt einer
  hartcodierten Price-ID – `stripe_find_or_create_price()` ist idempotent,
  ein erneuter Aufruf legt nichts doppelt an.
- `abo-upgrade.php`: erstellt eine Stripe-Checkout-Session (Modus
  `subscription`) für den vom Kunden gewählten Tarif und leitet dorthin
  weiter. `tenant_id`/`plan_code` werden sowohl auf der Checkout-Session
  als auch auf der Subscription selbst als Metadaten gesetzt, damit spätere
  Subscription-Events (die kein Checkout-Session-Objekt mehr enthalten)
  trotzdem einem Mandanten zugeordnet werden können.
- `abo-portal.php`: öffnet das Stripe Customer Portal für den bestehenden
  Stripe-Kunden (Zahlungsmittel ändern, Abo kündigen) – Self-Service ohne
  eigene UI dafür.
- `stripe-webhook.php`: verifiziert die `Stripe-Signature` nach dem von
  Stripe dokumentierten HMAC-SHA256-Schema (inklusive Zeitstempel-Toleranz
  gegen Replay), verarbeitet `checkout.session.completed`,
  `customer.subscription.updated`/`.deleted`,
  `invoice.paid`/`.payment_failed` und hält `tenant_billing` aktuell.
  Bewusst kein `app_require_csrf()`/`saas_require_login()` (Stripe ruft
  unauthentifiziert von außen auf), stattdessen ausschließlich die
  Signaturprüfung als Echtheitsnachweis.
- `mandant-einstellungen.php`: zeigt bei Bedarf einen echten
  „Jetzt upgraden"-Button (führt zu Stripe Checkout) sowie, sobald ein
  Stripe-Kunde existiert, „Zahlungsmethode verwalten / Abo kündigen"
  (führt zum Customer Portal).

**Noch nicht umgesetzt:** automatischer Stufenwechsel bei wachsender
Teilnehmerzahl (aktuell muss der Kunde selbst erneut auf „Upgraden"
klicken, wenn `billing_check_tenant()` einen höheren Bedarf anzeigt).

### Live getestet (Testmodus, kein echtes Geld)

- Checkout-Session-Erstellung direkt über die API sowie über den vollen
  Seiten-Flow (Login → Mandant-Einstellungen zeigt Upgrade-Button bei 13
  Teilnehmern → Klick → echter 302-Redirect zu einer
  `checkout.stripe.com`-URL).
- Webhook-Verarbeitung durch selbst erzeugte, korrekt signierte
  Test-Ereignisse (da diese Dev-Umgebung keine öffentlich erreichbare URL
  für echte Stripe-Zustellung hat): `checkout.session.completed` setzt
  `tenant_billing` korrekt (Tarif, Status, Stripe-IDs) und wird im
  Mandanten-Audit-Log protokolliert; `customer.subscription.deleted`
  setzt den Mandanten korrekt auf `free`/`canceled` zurück.
- Signaturprüfung: eine Anfrage mit falscher Signatur wird korrekt mit
  `400` abgelehnt.
- Customer Portal: mit einem echten, per API angelegten Stripe-Test-Kunden
  liefert `abo-portal.php` einen echten 302-Redirect zu
  `billing.stripe.com`.
- Alle bestehenden Regressionstests (Golden Master, M8-Isolation,
  M8-Rollenmatrix, HTTP-Smoke mit 36 Seiten) weiterhin grün.
- Alle Testdaten (Stripe-Testobjekte kosten nichts und wurden im
  Stripe-Testmodus belassen; lokale DB-Testdaten wurden entfernt)
  aufgeräumt.

### Für den Produktivbetrieb noch zu tun

- Echten Webhook-Endpunkt im Stripe-Dashboard (oder per API) auf die
  produktive Domain (`https://app.kaffeeliste.de/stripe-webhook.php`)
  eintragen und das dortige Signing-Secret als `STRIPE_WEBHOOK_SECRET`
  hinterlegen – das aktuelle Secret ist nur ein lokal erzeugter Platzhalter
  für die Simulation in dieser Dev-Umgebung.
- Von Test- auf Live-API-Keys wechseln, sobald ein echter Stripe-Account
  mit Bankverbindung eingerichtet ist.

## Phase 3: Dolibarr-Anbindung (umgesetzt)

**Ausgangslage:** Der Kunde betreibt nur eine einzige Dolibarr-Instanz,
und das ist die produktive für sein anderes Business – keine separate
Sandbox verfügbar (Dolibarr 23.0.3, `https://verwaltung.ctb-it.de`).
Der ursprüngliche Plan „erst gegen Sandbox testen" wurde daher ersetzt
durch sicheres Testen **innerhalb** der einen produktiven Instanz.

Umgesetzte Dateien:

```text
app/dolibarr.php
stripe-webhook.php (invoice.paid ruft dolibarr_sync_invoice_paid())
```

- `app/dolibarr.php`: minimaler REST-Client nach demselben Muster wie
  `app/stripe.php` (PHP-Streams, kein SDK). `dolibarr_find_or_create_thirdparty()`
  legt bei Erstkontakt einen Dolibarr-Kunden für den Mandanten an
  (`Kaffeeliste - <Mandantenname>`, E-Mail des Owners) und cached die
  Dolibarr-Kunden-ID in `tenant_billing.dolibarr_thirdparty_id`.
  `dolibarr_create_and_validate_invoice()` legt eine Rechnung mit einer
  Freitext-Position an (kein eigenes Dolibarr-Produkt pro Tarif nötig),
  fügt die Position hinzu und validiert die Rechnung sofort (vergibt die
  permanente, fortlaufende Nummer). `tva_tx = 0` durchgängig, da
  Kleinunternehmer nach § 19 UStG.
- `stripe-webhook.php`: `invoice.paid` löst jetzt zusätzlich zum
  Audit-Log-Eintrag `dolibarr_sync_invoice_paid()` aus. Ein Fehlschlag
  dort (Netzwerk, Dolibarr down, ungültige Daten) wird **nicht** an
  Stripe als Fehler zurückgemeldet – Stripe hat das Geld bereits
  erfolgreich eingezogen, das ist unabhängig vom Dolibarr-Spiegel. Der
  Fehler landet stattdessen als `billing.dolibarr_invoice_failed` im
  Mandanten-Audit-Log (sichtbar sowohl unter „Protokoll" in
  Mandant-Einstellungen als auch im Back-Office) zur manuellen
  Nachbearbeitung.
- Rechnungen werden **automatisch validiert** (nicht als Entwurf für
  manuelle Prüfung liegen gelassen) – bewusste Entscheidung des Kunden,
  um den Prozess vollautomatisch zu halten.
- Das automatische **Erfassen der Zahlung** in Dolibarr (Rechnung als
  bezahlt markieren) ist bewusst **nicht** umgesetzt – erfordert
  Kenntnis der Bankkonto-/Zahlungsart-IDs der Dolibarr-Instanz. Rechnungen
  erscheinen offen und werden vom Kunden manuell abgeglichen.
- Stripe bleibt alleiniger Zahlungsweg; Dolibarr wird nur als Buchhaltungs-
  Spiegel befüllt, nicht selbst zum Auslösen von Zahlungen verwendet.

### Live getestet

- **Verbindung/Lesezugriff**: `GET /status`, `/thirdparties`,
  `/invoices` gegen die echte Instanz erfolgreich geprüft (Version,
  Erreichbarkeit, Rechte des API-Keys).
- **Schreibzugriff (mit expliziter Freigabe des Kunden)**: ein eindeutig
  benannter Test-Kunde („TEST – Kaffeeliste Integration") sowie eine
  Entwurfs-Rechnung mit Position wurden über die API angelegt und die
  Struktur verifiziert (`status: 0` = Entwurf, `ref: (PROVx)` = noch
  keine permanente Nummer, korrekter Betrag, korrekte Verknüpfung).
  **Nicht validiert** – der Kunde hat die beiden Testdatensätze danach
  manuell in der Dolibarr-Oberfläche gelöscht (der beschränkte API-Key
  hat kein Lösch-Recht, `DELETE` liefert `403`).
- **Bewusst nicht live getestet**: der eigentliche `validate()`-Aufruf,
  der die permanente Rechnungsnummer vergibt – das hätte einen
  unlöschbaren Testeintrag in der produktiven Buchhaltung hinterlassen.
  Auf Wunsch des Kunden ist die erste echte Stripe-Zahlung nach dem
  Go-Live der erste echte Test dieses Schritts. Das Risiko ist durch die
  fehlertolerante Webhook-Verarbeitung begrenzt (siehe oben).
- Alle bestehenden Regressionstests (Golden Master, M8-Isolation,
  M8-Rollenmatrix, HTTP-Smoke mit 36 Seiten) weiterhin grün.

### Für den Produktivbetrieb noch zu tun

- Nach dem ersten echten `invoice.paid`-Ereignis in Produktion das
  Mandanten-Audit-Log prüfen (`billing.dolibarr_invoice_created` bzw.
  `billing.dolibarr_invoice_failed`), um den `validate()`-Aufruf einmal
  scharf zu bestätigen.
- Zahlungserfassung in Dolibarr (Rechnung als bezahlt markieren) als
  möglicher Ausbau, sobald Bankkonto-/Zahlungsart-IDs bekannt sind.