presseportale/dev/archive/optimize/cutover-runbook.md

# Cutover-Runbook — Go-Live Pressekonto

> ✅ **ERLEDIGT — archiviert am 20.07.2026.** Die Migration ist vollständig
> durchgelaufen (`legacy:verify`: 0 failures, 0 warnings), die echten Domains
> sind live geschaltet, Stripe läuft im Live-Mode. Dieses Runbook bleibt als
> Referenz erhalten — z. B. für einen späteren `--since`-Delta-Lauf, falls
> das Alt-System doch noch einmal Daten liefern sollte (Abschnitt 3).
> Betriebs-Doku ab jetzt: `dev/betrieb/deploy-runbook.md`.

Stand: 2026-07-14 · Branch `fix/zeitzone-europe-berlin`

Abhakbare Checkliste für die Umschaltung vom Alt-System auf Pressekonto.
Alle Commands laufen über Sail: `vendor/bin/sail artisan …` (bzw. ohne Sail
`php artisan …`, je nach Deployment-Umgebung).

---

## 0. Grundverständnis (einmal lesen)

- **Zwei Legacy-Quellen, unterschiedlicher Charakter:**
  - **Presseecho** = echte **Live-DB** (`mysql_presseecho`). Nur hier greift die
    „offline nehmen → Delta nachziehen"-Choreografie.
  - **Businessportal24** = **statischer Snapshot-Dump** (`mysql_businessportal`).
    Ändert sich nicht mehr → einmal importieren reicht, kein Delta nötig.
- **Idempotenz:** Alle Importer schreiben per `updateOrCreate(legacy_portal, legacy_id)`
  + Crosswalk-Tabelle `legacy_import_map`. Mehrfaches Ausführen erzeugt **keine
  Duplikate**. Bei Absturz mittendrin: einfach erneut starten (kein Rollback,
  Sicherheit kommt aus Idempotenz, nicht aus Transaktionen).
- **Standard-Lauf überspringt bereits importierte Zeilen.** Zwischenzeitliche
  **Änderungen** an Altdatensätzen werden nur mit `--force` nachgezogen.
- **Kein Delete-Sync:** Im Alt-System gelöschte Datensätze bleiben im neuen
  System bestehen. Für das kurze Cutover-Fenster i. d. R. vernachlässigbar.
- ⚠️ **`migrate:presseecho` NICHT ausführen** — toter, kaputter Stub. Der einzige
  gültige Weg ist `legacy:import`.
- **Voraussetzung Timestamp-Sync:** `legacy:fix-timestamps` nutzt Cross-Schema-
  JOINs → beide Legacy-Schemas müssen auf **demselben MySQL-Server** liegen wie
  die App-DB. **Umsetzung Live (16.07.):** Die KAS-Originale (All-Inkl) sind
  von außen nicht joinbar → Dumps als lokale Snapshot-Kopien `legacy_presseecho`
  / `legacy_businessportal` auf dem Hetzner-Server eingespielt (Ploi-DBs,
  `dbUserPressekonto` hat Zugriff), `DB_*_PRESSEECHO`/`DB_*_BUSINESSPORTAL`
  zeigen auf die Kopien. Ein voller `--force`-Reimport ist als Ersatz ungeeignet:
  er setzt die `path`-Spalte bereits migrierter Bildzeilen auf den Legacy-
  Dateinamen zurück und macht die Medien-Migration kaputt.
- ⚠️ **Snapshot veraltet:** Alle Legacy-Commands lesen jetzt die lokalen Kopien.
  Beim Cutover (Abschnitt 3) und vor jedem Delta-Lauf zuerst frische KAS-Dumps
  ziehen und in die Kopien einspielen — sonst läuft das Delta gegen alte Daten.

---

## 1. Vorbereitung (Tage vorher, in Ruhe)

- [ ] Prod-`.env` gesetzt: `APP_ENV=production`, `APP_DEBUG=false`,
      `SESSION_SECURE_COOKIE=true`, `QUEUE_CONNECTION=database` (o. Ä. dauerhaft).
- [ ] Legacy-Zugangsdaten in `.env` eingetragen:
      `DB_HOST_PRESSEECHO / DB_DATABASE_PRESSEECHO / DB_USERNAME_PRESSEECHO / DB_PASSWORD_PRESSEECHO`
      und `DB_*_BUSINESSPORTAL` (Snapshot-Dump auf denselben Server eingespielt).
- [ ] Secrets rotiert (OpenAI / Google / Mail) — nicht die Alt-Keys übernehmen.
- [ ] Legacy-Medien ins lokale Staging kopiert:
      `dev/migration/<portal>/uploads/...` (rsync vom Alt-System).
- [ ] DB-Migrationen ausgeführt: `artisan migrate --force`.
      Vorher prüfen: keine Duplikate in `invoices.stripe_invoice_id`
      (Unique-Migration bricht sonst bewusst ab).
- [ ] Rollen/Permissions ausgerollt: `artisan db:seed --class=RolesAndPermissionsSeeder`.ç
- [ ] **Verbindungstest / Zählwerte:** `artisan legacy:import --source=all --dry-run`
      → erwartete Zeilenzahlen plausibel?

---

## 2. Bulk-Import (Presseecho noch live, ohne Downtime)

Reihenfolge ist in `legacy:import --step=all` hart verdrahtet
(categories → users → companies → contacts → press-releases → link-associations).

- [ ] `artisan legacy:import --source=all`
      (idempotent — beliebig oft wiederholbar).
- [ ] `artisan legacy:migrate-media --portal=all`
      (Datei-Bytes aus `dev/migration/...` → **public**-Disk + Varianten).
- [ ] **`artisan press-releases:privatize-media --prune-missing`**
      (verschiebt PM-Medien public → **private** Disk — Security-Hardening;
      MUSS nach `legacy:migrate-media` laufen). `--prune-missing` löscht
      Legacy-Bildzeilen, deren Datei im Alt-System verloren ging (Import legt
      pro Legacy-Bild eine Zeile an; ohne Datei bleibt sie sonst als Leiche
      liegen und hält die Betriebsüberwachungs-Kachel rot).
- [ ] `artisan legacy:fix-timestamps`
      (created_at/updated_at + published_at per Cross-DB-JOIN).
- [ ] Satelliten-Migrationen (Reihenfolge unkritisch, jeweils `--dry-run` zuerst):
  - [ ] `artisan legacy:import-api-keys`
  - [ ] `artisan legacy:archive-invoices`
  - [ ] `artisan legacy:grandfather-subscriptions`
  - [ ] `artisan legacy:import-billing-addresses`
  - [ ] `artisan legacy:migrate-agency-names`
  - [ ] `artisan companies:retire-agency-type` (läuft NACH `legacy:migrate-agency-names`;
        Reports unter `storage/app/private/migration/` prüfen — Mehrfach-Namen,
        Owner-lose Agentur-Firmen, geschützte Fälle; s. Deploy-Runbook §7)
- [ ] **Gate:** `artisan legacy:verify` → JSON-Report prüfen. Go / No-Go.

---

## 3. Cutover-Fenster (kurze Downtime)

Ziel: nur die seit dem Bulk-Import geänderten/neuen **Presseecho**-Daten
nachziehen. Businessportal24 braucht hier nichts (Dump ist statisch).

- [ ] **Presseecho** in **Read-Only / Wartung** schalten — **Lesezugriff behalten**,
      der Delta-Import muss noch aus der Legacy-DB lesen können.
- [ ] **Frische KAS-Dumps ziehen und die lokalen Snapshot-Kopien neu einspielen**
      (`legacy_presseecho`; Businessportal24 nur falls sich dort doch etwas
      geändert hat) — die Legacy-Connections lesen die Kopien, nicht KAS direkt.
- [ ] Neues System in Wartung: `artisan down`.
- [ ] **Delta-Import mit `--force` + `--since`** (zieht auch geänderte
      Bestandsdatensätze nach; uuid + slug von PMs bleiben stabil → öffentliche
      URLs brechen nicht). `--since` auf das Datum des **Bulk-Imports minus
      1 Tag Sicherheitsmarge** setzen — dann scannt der Lauf nur die seither
      angelegten/geänderten Legacy-Zeilen (Sekunden statt Volldurchlauf):
      `artisan legacy:import --source=presseecho --force --since="2026-07-19"`
      Die Importer setzen Timestamps inzwischen selbst korrekt (forceFill) —
      `legacy:fix-timestamps` danach ist Absicherung, kein Muss mehr.
      ⚠️ Für neue PM-Bilder vorher auch die **Medien** vom Alt-Server nachsyncen
      (rsync-Delta nach `dev/migration/presseecho/…`), sonst werden ihre
      Bildzeilen mangels Datei von `--prune-missing` entsorgt.
- [ ] Medien-Delta: `artisan legacy:migrate-media --portal=presseecho --force`
      (`--force` erzwingt Neukopie + Varianten geänderter Bilder) →
      danach erneut `artisan press-releases:privatize-media --prune-missing`
      (der `--force`-Reimport legt die Bildzeilen verlorener Legacy-Dateien
      erneut an — das Pruning räumt sie wieder ab).
- [ ] `artisan legacy:fix-timestamps --portal=presseecho`
- [ ] **Gate:** `artisan legacy:verify --portal=presseecho`.
- [ ] **DNS umstellen** auf das neue System.
- [ ] Queue-Worker läuft & wird überwacht → Admin ▸ **Reports ▸ Betriebsüberwachung**
      (alle Kacheln grün, besonders „Queue-Worker" und „Medien-Privatisierung").
- [ ] `artisan up` — neues System live.
- [ ] Alt-System **komplett offline**.

---

## 4. Go-Live-Kommunikation

- [ ] Passwort-Reset-Mails versenden (Importer setzt **bewusst keine Passwörter**):
      erst `artisan auth:send-go-live-mails --dry-run` (Anzahl prüfen),
      dann `artisan auth:send-go-live-mails`.
  - ⚠️ **Massen-Mailversand über die Queue** → vorher Worker-Status grün prüfen,
      während des Versands Betriebsüberwachung im Blick behalten
      (pending/failed jobs).

---

## 5. Nachlauf / Verifikation

- [ ] Stichproben: Login mit Reset-Link, PM-Detailseite (Bild + Anhang laden),
      Newsroom-Übersicht, Archiv-Sichtbarkeit.
- [ ] Betriebsüberwachung: keine `failed_jobs`, kein „gestoppter Worker".
- [ ] `storage/logs` auf Fehler prüfen.
- [ ] Backup der neuen Prod-DB direkt nach erfolgreichem Cutover.

---

## Offene Punkte / bewusste Entscheidungen

- **Verlorene Presseecho-PM-Bilder akzeptiert (16.07.):** ~22k von ~32k Legacy-
  Bilddateien existieren im Alt-System nicht mehr (nur Alt-Thumbnails retteten
  ~4,5k). Entscheidung: ohne Bild importieren — betrifft alte Archiv-Meldungen;
  betroffene PMs erscheinen bildlos, kaputte Referenzen entstehen nicht
  (`press-releases:privatize-media --prune-missing` räumt die Datensatz-Leichen ab).

- **Gelöschte Legacy-Datensätze** werden nicht synchronisiert (kein Delete-Sync).
  Falls im Parallelbetrieb im Alt-System gelöscht wird → im neuen System nachher
  manuell prüfen (i. d. R. vernachlässigbar bei kurzem Fenster).
- **`legacy:fix-timestamps`** setzt voraus, dass beide Legacy-Schemas auf demselben
  MySQL-Server liegen. Andernfalls voller `--force`-Reimport statt Timestamp-Fix.