fotospiel-app/docs/ops/howto-tenant-package-not-active.md

id, title, sidebar_label

id	title	sidebar_label
howto-tenant-package-not-active	How-to – Zahlung erfolgreich, Paket nicht aktiv	Zahlung ok, Paket nicht aktiv

Dieses How‑to beschreibt, wie du vorgehst, wenn ein Tenant meldet: „Zahlung war erfolgreich, aber mein Paket ist nicht aktiv / Galerie bleibt limitiert.“

1. Informationen vom Tenant einsammeln

Bevor du nachschaust:

• Tenant‑ID oder Tenant‑Slug.
• Betroffenes Paket (Name oder Beschreibung, z.B. „Pro‑Paket 79 €“).
• Zeitpunkt der Zahlung (Datum/Uhrzeit, ggf. Screenshot).
• Ggf. Auszug aus der Lemon Squeezy‑Bestätigung (ohne vollständige Kartendaten!).

Diese Infos erlauben dir, die korrekte Transaktion sowohl in Lemon Squeezy als auch im Backend zu finden.

2. Lemon Squeezy-Status prüfen

1. Im Lemon Squeezy‑Dashboard:
   • Suche nach E‑Mail, Tenant‑Name oder der vom Tenant genannten Order‑ID.
   • Stelle sicher, dass die Zahlung dort als „paid“/„completed“ markiert ist.
2. Notiere:
   • Lemon Squeezy‑Order‑ID und ggf. Checkout‑ID.
   • Status (paid/processing/failed/cancelled).

Wenn Lemon Squeezy die Zahlung nicht als erfolgreich zeigt, ist dies primär ein Finance‑/Customer‑Topic – ggf. mit Customer Support klären, ob eine neue Zahlung oder Klärung mit dem Kunden notwendig ist.

3. Backend-Status prüfen

Mit bestätigter Zahlung in Lemon Squeezy:

1. checkout_sessions:
   • Suche nach Sessions des Tenants (tenant_id) mit dem betroffenen package_id:
   • Achte auf status (erwartet completed) und provider = lemonsqueezy.
   • Prüfe provider_metadata auf lemonsqueezy_last_event, lemonsqueezy_status, lemonsqueezy_checkout_id, lemonsqueezy_order_id.
   • Wenn du die Session über Lemon Squeezy‑Metadaten finden möchtest:
     • lemonsqueezy_checkout_id oder lemonsqueezy_order_id verwenden.
2. package_purchases:
   • Prüfe, ob ein Eintrag für (tenant_id, package_id) mit passender Provider‑Referenz existiert:
     • z.B. provider = 'lemonsqueezy', provider_id = Order‑ID.
3. tenant_packages:
   • Prüfe, ob es einen aktiven Eintrag für (tenant_id, package_id) gibt:
     • active = 1, expires_at in der Zukunft.

4. Webhook-/Verarbeitungsstatus untersuchen

Wenn checkout_sessions noch nicht auf completed steht oder tenant_packages nicht aktualisiert wurden:

1. Logs prüfen:
   • storage/logs/laravel.log und ggf. billing‑Channel.
   • Suche nach Einträgen von LemonSqueezyWebhookController / CheckoutWebhookService rund um den Zahlungszeitpunkt.
2. Typische Ursachen:
   • Webhook nicht zugestellt (Netzwerk/SSL).
   • Webhook konnte die Session nicht auflösen ([CheckoutWebhook] Lemon Squeezy session not resolved).
   • Idempotenz‑Lock (Lemon Squeezy lock busy) hat dazu geführt, dass Event nur teilweise verarbeitet wurde.

5. Korrektur-Schritte

5.1 Automatischer Replay (empfohlen)

1. Im Lemon Squeezy‑Dashboard:
   • Den betreffenden order_*‑Event finden.
   • Webhook‑Replay auslösen.
2. In den Logs beobachten:
   • Ob CheckoutWebhookService::handleLemonSqueezyEvent() diesmal die Session findet und CheckoutAssignmentService::finalise() ausführt.
3. Nochmal checkout_sessions und tenant_packages prüfen:
   • Session sollte auf completed stehen, Paket aktiv sein.

5.2 Manuelle Korrektur (Notfall)

Nur anwenden, wenn klare Freigabe vorliegt und Lemon Squeezy die Zahlung eindeutig als erfolgreich listet.

1. tenant_packages aktualisieren:
   • Entweder neuen Eintrag anlegen oder bestehenden für (tenant_id, package_id) so setzen, dass:
   • active = 1,
   • purchased_at und expires_at zu Lemon Squeezy‑Daten passen.
2. package_purchases ergänzen:
   • Sicherstellen, dass die Zahlung als Zeile mit provider = 'lemonsqueezy', provider_id = Order‑ID und passender price existiert (für spätere Audits).
3. Konsistenz prüfen:
   • Admin UI für Tenant öffnen und prüfen, ob Limits/Paketstatus jetzt korrekt angezeigt werden.
4. Dokumentation:
   • Den Vorgang im Ticket oder als bd-Issue (falls wiederkehrend) dokumentieren.

6. Kommunikation mit dem Tenant

• Sobald der Backend‑Status korrigiert ist:
  • Kurz bestätigen, dass das Paket aktiv ist und welche Auswirkungen das hat (z.B. neue Limits, verlängerte Galerie).
• Falls Lemon Squeezy die Zahlung nicht als erfolgreich führt:
  • Ehrlich kommunizieren, dass laut Zahlungsprovider noch keine endgültige Zahlung vorliegt und welche Optionen es gibt (z.B. neue Zahlung, Klärung mit Bank/Kreditkarte).

Dieses How‑to sollte dem Support/On‑Call helfen, den gängigsten Billing‑Fehlerfall strukturiert abzuarbeiten. Für tiefere Ursachenanalysen siehe docs/ops/billing-ops.md.