further rework to the documentation

docs/ops/billing-ops.md

@@ -0,0 +1,133 @@
+---
+title: Billing & Zahlungs-Operationen
+sidebar_label: Billing-Runbook
+---
+
+Dieses Runbook beschreibt, wie mit Zahlungsproblemen, Paddle/RevenueCat‑Webhooks und Paket‑Inkonsistenzen operativ umzugehen ist.
+
+## 1. Komponentenüberblick
+
+- **Paddle**
+  - Abwicklung von Web‑Checkout, Paketen und Subscriptions.
+  - Webhooks für Käufe, Verlängerungen, Stornos.
+- **Fotospiel Backend**
+  - Modelle wie `Tenant`, `Packages`, `tenant_packages`, `event_packages`.
+  - Services/Jobs zur Paket‑Zuweisung, Limit‑Berechnung und Nutzungstracking.
+
+> Details zur Architektur findest du in den PRP‑Kapiteln (Billing/Freemium) sowie in den TODO‑Dokumenten unter `docs/process/todo/paddle-migration.md` und `docs/process/todo/paddle-catalog-sync.md`.
+
+## 2. Typische Problemszenarien
+
+- **Webhook kommt nicht an / schlägt fehl**
+  - Symptom: Paddle zeigt Zahlung „completed“, Tenant‑Paket im Backend bleibt unverändert.
+  - Checkliste:
+    - Logs der Webhook‑Routes prüfen (Statuscodes, Exceptions).
+      - Endpoint: `POST /paddle/webhook` → `PaddleWebhookController::handle()`.
+      - Controller ruft `CheckoutWebhookService::handlePaddleEvent()` auf.
+    - Webhook‑Replay über das Paddle Dashboard auslösen (für einzelne Events).
+    - Queue‑Status prüfen:
+      - Falls Webhooks über Queues verarbeitet werden, auf `default`/`billing`‑Queues achten (je nach Konfiguration).
+- **Doppelte oder fehlende Abbuchungen**
+  - Abgleich von Zahlungsprovider‑Daten (Paddle/RevenueCat) mit internem Ledger.
+  - Bei doppelten Buchungen: Prozess definieren (Refund via Paddle, Anpassung im Ledger).
+  - Bei fehlenden Buchungen: ggf. manuelle Paketzuweisung nach erfolgter Zahlung.
+- **Pakete/Limits passen nicht zur Realität**
+  - Tenant meldet: „Paket falsch“, „Galerie schon abgelaufen“ o.Ä.
+  - Prüfen:
+    - Aktives Paket (`tenant_packages`, `event_packages`).
+    - Limit‑Zähler (`used_photos`, `used_events`) und aktuelle Nutzung.
+    - Letzte relevante Webhooks/Jobs (z.B. vor kurzem migriert?).
+
+## 3. Operative Schritte bei Payment Incidents
+
+1. **Event/Tenant identifizieren**
+   - IDs und relevante Paket‑Infos aus DB/Admin UI holen.
+2. **Provider-Status prüfen**
+    - Paddle‑Dashboard: ist die Zahlung dort korrekt verbucht? (Transaktions‑/Abonnement‑Ansicht).
+3. **Backend-Status prüfen**
+    - Paketzuweisung und Limits in der DB (Read‑only!) inspizieren:
+      - `checkout_sessions` – wurde die Session korrekt auf `completed` gesetzt? (`provider = paddle`, `paddle_transaction_id` gefüllt?)
+      - `package_purchases` – existiert ein Eintrag für Tenant/Package mit erwarteter Provider‑Referenz?
+      - `tenant_packages` – stimmt der `active`‑Status und `expires_at` mit dem erwarteten Abostatus überein?
+4. **Entscheidung**
+    - Automatische Nachverarbeitung via Webhook‑Replay/Job‑Retry:
+      - Paddle‑Events erneut senden lassen, ggf. `tests/api/_testing/checkout/sessions/{session}/simulate-paddle` (in Test‑Umgebungen) nutzen.
+    - Notfall: manuelle Paket‑Anpassung (nur mit klar dokumentierter Begründung):
+      - Paket in `tenant_packages` aktivieren/verlängern und `package_purchases` sauber nachziehen.
+5. **Dokumentation**
+   - Vorgang im Ticket / `docs/process/changes/*` festhalten, falls wiederkehrend.
+
+> TODO: Ergänze konkrete Tabellen-/Modellnamen und die relevanten Jobs/Artisan Commands, sobald Paddle/RevenueCat Migration finalisiert ist.
+
+## 4. Zusammenarbeit mit Finance/Support
+
+- Klar definieren, wer Rückerstattungen freigibt und durchführt.
+- Playbook für Support:
+  - Welche Informationen sie sammeln sollen, bevor sie an Ops eskalieren (Tenant‑ID, Event‑ID, Payment‑Provider‑Referenz, Zeitstempel).
+  - Welche Standardantworten es gibt (z.B. „Zahlung in Prüfung, Paket kurzfristig manuell freigeschaltet“).
+
+## 5. Hinweise zur Implementierung
+
+- **Konfiguration**
+  - Paddle‑Keys, Webhook‑Secrets und Feature‑Flags sollten ausschließlich in `.env`/Config‑Dateien liegen und niemals im Code/Logs landen.
+  - Sandbox vs. Live‑Keys klar trennen; Ops sollte wissen, welche Umgebung gerade aktiv ist.
+- **Sicherheit**
+  - Webhook‑Signaturen und Timestamps prüfen; bei verdächtigen Mustern (z.B. Replay‑Angriffe) Security‑Runbooks konsultieren.
+  - Keine sensiblen Payment‑Details in Applikations‑Logs ausgeben.
+
+Diese Sektion ist bewusst generisch gehalten, damit sie auch nach Implementation der finalen Billing‑Architektur noch passt. Details zu Tabellen/Jobs sollten ergänzt werden, sobald die Paddle‑Migration abgeschlossen ist.
+
+## 6. Konkrete Paddle-Flows im System
+
+### 6.1 Checkout-Erstellung
+
+- Marketing-Checkout / API:
+  - `MarketingController` und `PackageController` nutzen `PaddleCheckoutService::createCheckout()` (`App\Services\Paddle\PaddleCheckoutService`).
+  - Der Service:
+    - Stellt sicher, dass ein `paddle_customer_id` für den Tenant existiert (`PaddleCustomerService::ensureCustomerId()`).
+    - Baut Metadaten (`tenant_id`, `package_id`, optional `checkout_session_id`) für spätere Zuordnung.
+    - Ruft `POST /checkout/links` im Paddle‑API auf und erhält eine `checkout_url`.
+- Ops-Sicht:
+  - Wenn `paddle_price_id` bei einem Package fehlt, wird kein Checkout erzeugt – Marketing‑UI zeigt entsprechende Fehlertexte (siehe `resources/lang/*/marketing.php`).
+  - Bei wiederkehrenden „checkout failed“‑Fehlern die Logs (`PaddleCheckoutService`, Controller) und Package‑Konfiguration prüfen.
+
+### 6.2 Webhook-Verarbeitung & Idempotenz
+
+- Endpoint: `POST /paddle/webhook` → `PaddleWebhookController::handle()`.
+- Service: `CheckoutWebhookService` (`App\Services\Checkout\CheckoutWebhookService`):
+  - Unterscheidet zwischen **Transaktions‑Events** (`transaction.*`) und **Subscription‑Events** (`subscription.*`).
+  - Idempotenz:
+    - Nutzt ein Cache‑Lock (`checkout:webhook:paddle:{transaction_id|session_id}`), um parallele Verarbeitung desselben Events zu verhindern.
+    - Schreibt Metadaten (`paddle_last_event`, `paddle_status`, `paddle_checkout_id`) in `checkout_sessions.provider_metadata`.
+- Ergebnis:
+  - Bei `transaction.completed`:
+    - `CheckoutSession` wird als `processing` markiert.
+    - `CheckoutAssignmentService::finalise()` weist Paket/Tenant zu.
+    - Session wird auf `completed` gesetzt.
+  - Bei `transaction.failed` / `transaction.cancelled`:
+    - Session wird auf `failed` gesetzt, Coupons werden als fehlgeschlagen markiert.
+
+### 6.3 Subscriptions & TenantPackages
+
+- Subscription‑Events (`subscription.*`) werden ebenfalls von `CheckoutWebhookService` behandelt:
+  - Tenant wird aus `metadata.tenant_id` oder `paddle_customer_id` ermittelt.
+  - Package wird über `metadata.package_id` oder `paddle_price_id` aufgelöst.
+  - `TenantPackage` wird erstellt/aktualisiert (`paddle_subscription_id`, `expires_at`, `active`).
+  - `Tenant.subscription_status` und `subscription_expires_at` werden gesteuert.
+- Ops-Sicht:
+  - Bei abweichenden Abostatus (z.B. Paddle zeigt „active“, Tenant nicht):
+    - Subscription‑Events im Paddle‑Dashboard prüfen.
+    - Letzte `subscription.*`‑Events in den Logs, `TenantPackage`‑ und `Tenant`‑Felder gegenprüfen.
+
+### 6.4 Paket- & Coupon-Synchronisation
+
+- Pakete:
+  - Artisan‑Command `paddle:sync-packages` (`App\Console\Commands\PaddleSyncPackages`) stößt für ausgewählte oder alle Pakete `SyncPackageToPaddle`/`PullPackageFromPaddle` Jobs an.
+  - Sync‑Jobs nutzen `PaddleCatalogService`, um Produkte/Preise in Paddle zu erstellen/aktualisieren und `paddle_product_id`/`paddle_price_id` lokal zu pflegen.
+- Coupons:
+  - `SyncCouponToPaddle`‑Job spiegelt interne Coupon‑Konfiguration in Paddle Discounts (`PaddleDiscountService`).
+- Ops-Sicht:
+  - Bei Katalog‑Abweichungen `paddle:sync-packages --dry-run` verwenden, um Snapshots zu prüfen, bevor tatsächliche Änderungen gesendet werden.
+  - Fehlgeschlagene Syncs in den Logs (`Paddle package sync failed`, `Paddle discount sync failed`) beobachten.
+
+Diese Untersektion soll dir als Operator helfen zu verstehen, wie Paddle‑Aktionen im System abgebildet sind und an welchen Stellen du im Fehlerfall ansetzen kannst.