Document Paddle cutover

.beads/issues.jsonl

@@ -79,7 +79,7 @@
 {"id":"fotospiel-app-mpu","title":"Checkout refactor: test coverage + rollout notes","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-01T16:06:43.488302531+01:00","created_by":"soeren","updated_at":"2026-01-01T16:06:49.13645691+01:00","closed_at":"2026-01-01T16:06:49.13645691+01:00","close_reason":"Completed in codebase (verified)"}
 {"id":"fotospiel-app-mx5","title":"Localized SEO: sitemap updated with locale alternates","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-01T16:02:15.177013722+01:00","created_by":"soeren","updated_at":"2026-01-01T16:02:20.812287917+01:00","closed_at":"2026-01-01T16:02:20.812287917+01:00","close_reason":"Completed in codebase (verified)"}
 {"id":"fotospiel-app-mxw","title":"Security review: configure env assumptions for dynamic testing","status":"open","priority":2,"issue_type":"task","created_at":"2026-01-01T16:04:29.498402235+01:00","created_by":"soeren","updated_at":"2026-01-01T16:04:29.498402235+01:00"}
-{"id":"fotospiel-app-n8q","title":"Paddle migration: draft production cutover procedure","status":"open","priority":2,"issue_type":"task","created_at":"2026-01-01T15:56:51.427425262+01:00","created_by":"soeren","updated_at":"2026-01-01T15:56:51.427425262+01:00"}
+{"id":"fotospiel-app-n8q","title":"Paddle migration: draft production cutover procedure","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-01T15:56:51.427425262+01:00","created_by":"soeren","updated_at":"2026-01-02T22:28:41.469357437+01:00","closed_at":"2026-01-02T22:28:41.469357437+01:00","close_reason":"Completed"}
 {"id":"fotospiel-app-nfi","title":"Paddle catalog sync: add Link existing Paddle entity action in admin","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-01T15:59:09.164334657+01:00","created_by":"soeren","updated_at":"2026-01-02T22:15:15.030896509+01:00","closed_at":"2026-01-02T22:15:15.030896509+01:00","close_reason":"Completed"}
 {"id":"fotospiel-app-niv","title":"Paddle catalog sync: Package model casts/fillable + factory","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-01T16:00:13.646318173+01:00","created_by":"soeren","updated_at":"2026-01-01T16:00:19.296543136+01:00","closed_at":"2026-01-01T16:00:19.296543136+01:00","close_reason":"Completed in codebase (verified)"}
 {"id":"fotospiel-app-o4n","title":"Audit PayPal SDK migration doc vs code (PayPal integration missing)","status":"open","priority":2,"issue_type":"task","created_at":"2026-01-01T16:07:34.316575518+01:00","created_by":"soeren","updated_at":"2026-01-01T16:07:34.316575518+01:00"}

docs/ops/billing-ops.md

@@ -178,3 +178,32 @@ Wenn der Katalog‑Sync fehlschlägt oder Pakete nicht mehr korrekt verknüpft s
    - Achte auf wiederkehrende Fehler (z.B. invalid product/price IDs).
 
 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.
+
+## 7. Production Cutover: Paddle Migration
+
+Diese Checkliste beschreibt den kontrollierten Wechsel auf Paddle in Produktion.
+
+1. **Vorbereitung (T‑1 Woche)**
+   - Confirm: `PADDLE_ENVIRONMENT=production`, `PADDLE_API_KEY`, `PADDLE_CLIENT_TOKEN`, `PADDLE_WEBHOOK_SECRET`.
+   - Package IDs validieren: alle aktiven Packages haben `paddle_product_id` und `paddle_price_id`.
+   - `paddle:sync-packages --dry-run` auf eine Stichprobe anwenden.
+   - Event‑Liste prüfen: `config/paddle.php` (`webhook_events`).
+2. **Staging Smoke (T‑2 Tage)**
+   - `paddle:webhooks:register --traffic-source=simulation` auf Staging ausfuehren.
+   - Testkauf via Paddle Sandbox und Webhook Replay verifizieren.
+3. **Cutover Window (T‑0)**
+   - Marketing‑Checkout kurz einfrieren (kein Checkout waehrend der Umschaltung).
+   - Production Webhook registrieren:
+     - `paddle:webhooks:register --traffic-source=platform --url=https://<prod-domain>/paddle/webhook`
+   - Queue worker laufen lassen (Queue: `webhooks`/`billing` sofern konfiguriert).
+4. **Activation**
+   - Erstes Produktions‑Checkout ausfuehren.
+   - Verify: `checkout_sessions.provider_metadata` wird mit `paddle_*` Feldern befuellt.
+   - Verify: `TenantPackage` aktiv und `subscription_status` korrekt.
+5. **Rollback (falls notwendig)**
+   - Checkout wieder deaktivieren (Marketing‑Checkout ausblenden).
+   - Paddle Webhook Destination im Paddle Dashboard deaktivieren.
+   - Status und Logs sichern (Webhooks, `paddle_sync` Log).
+6. **Post‑Cutover (T+1)**
+   - Stichproben auf neue Tenants/Packages.
+   - Monitoring: Fehlgeschlagene Webhooks, Sync‑Fehler, Support Tickets.