# Migration Steps – aktuelles Runbook Stand: 2026-06-17. Spiegelt den aktuell implementierten Command-Stand. Details und Go-Live-Kontext stehen in `05-DATABASE-MERGE.md` und `08-PROGRESS.md`; die Live-Settings/Commands rund um den Go-Live in `../../docs/weiteres/Live-Deployment-Checkliste (WS-7).md`. ## Zwei-Phasen-Strategie (kurzer Ausfall) Der Import ist **wiederholbar**. Vorgesehener Ablauf: 1. **Phase 1 – Voll-Import (jetzt):** Neues System auf `pressekonto.com` aufsetzen, Schema migrieren, kompletten Bestand mit `--force` importieren, Frontends auf Test-Domain verifizieren. 2. **Phase 2 – Delta-Lauf (beim Cutover):** Altsystem kurz einfrieren, dieselben Commands **ohne `--force`** erneut laufen lassen → bestehende Datensätze bleiben unangetastet, nur neue/zwischenzeitlich entstandene werden nachgezogen. Danach DNS umstellen. > **Die `--force`-Disziplin ist entscheidend:** > - **MIT `--force`** (nur Phase 1): überschreibt bestehende Datensätze. > - **OHNE `--force`** (Phase 2): überspringt bereits importierte Datensätze (`legacy_import_map`), importiert ausschließlich Neue. Genau das Verhalten für einen sauberen Delta-Lauf. --- ## Phase 0 – Schema (einmalig, vor dem ersten Import) ```bash php artisan migrate --force ``` Ohne das Schema schlägt jeder Import-Schritt fehl. Auf dem Live-System ist das Teil der WS-7-Checkliste. ## Dry-Run (vor jedem echten Lauf) ```bash php artisan legacy:import --source=all --dry-run php artisan legacy:archive-invoices --dry-run php artisan legacy:grandfather-subscriptions --dry-run php artisan legacy:verify --no-report php artisan legacy:migrate-media --portal=all --type=all --base-path=dev/migration --dry-run ``` Hinweis: `legacy:archive-invoices` importiert die Legacy-Rechnungen vollständig in `legacy_invoices`, inkl. Status/User-Zuordnung, `raw_snapshot`, `pdf_payload` und Report. Die PDF-Erzeugung erfolgt im Customer-Bereich bei Abruf aus diesen Archivdaten. --- ## Phase 1 – Voll-Import (mit `--force`, korrekte Reihenfolge) ```bash php artisan legacy:import --source=presseecho --step=categories --force php artisan legacy:import --source=all --step=users --force php artisan legacy:import --source=presseecho --step=companies --force php artisan legacy:import --source=businessportal24 --step=companies --force php artisan legacy:import --source=presseecho --step=contacts --force php artisan legacy:import --source=businessportal24 --step=contacts --force php artisan legacy:import --source=presseecho --step=press-releases --force php artisan legacy:import --source=businessportal24 --step=press-releases --force php artisan legacy:import --step=link-associations --force php artisan legacy:archive-invoices php artisan legacy:grandfather-subscriptions php artisan legacy:fix-timestamps php artisan legacy:migrate-media --portal=all --type=all --base-path=dev/migration php artisan legacy:verify ``` Reihenfolge ist wegen FKs Pflicht (companies vor contacts vor press-releases; users zuerst). Der Schritt `--step=users` importiert neben `sf_guard_user` auch `sf_guard_user_profile` in die neue Tabelle `profiles`. ### Datums-Migration der Pressemitteilungen (wichtig für die Frontend-Sortierung) Das Frontend sortiert/clustert nach `published_at`. Der Importer setzt daher: - `created_at`/`updated_at` = Legacy-`created_at`/`updated_at` (per `forceFill`, da nicht fillable) — das echte Anlage-/Bearbeitungsdatum, **nicht** das Importdatum. - `published_at` = Legacy-`created_at` (Publikationsdatum) für veröffentlichte Meldungen. Bewusst **nicht** `updated_at` — dort steht bei vielen Alt-Datensätzen der Massen-/Migrationsstempel (z. B. `2026-04-…`), der sonst als „frisches" Veröffentlichungsdatum erschiene. `legacy:fix-timestamps` ist der schnelle Cross-DB-Resync (gleicher MySQL-Server) und korrigiert `created_at`, `updated_at` **und** `published_at` (für `status=published`) authoritativ. Bei einem reinen Delta-Lauf ohne Re-Import diesen Schritt mitlaufen lassen. --- ## Phase 2 – Delta-Lauf beim Cutover (OHNE `--force`) Altsystem einfrieren, dann: ```bash # Vorab sehen, was neu dazukommt php artisan legacy:import --source=all --dry-run # Nur neue Datensätze nachziehen (kein --force!) php artisan legacy:import --source=all php artisan legacy:archive-invoices php artisan legacy:grandfather-subscriptions # replay-fähig: aktualisiert bestehende, ergänzt neue php artisan legacy:fix-timestamps # korrigiert created_at/updated_at/published_at php artisan legacy:verify # Medien NICHT mit --force – würde im neuen System gepflegte Logos/Bilder überschreiben. # Nur falls neue Medien fehlen, gezielt ohne --force nachladen: # php artisan legacy:migrate-media --portal=all --type=all --base-path=dev/migration ``` Danach DNS auf das neue System umstellen. `legacy:grandfather-subscriptions` läuft **nach** `legacy:archive-invoices`, weil es die aktiven, jährlich wiederkehrenden Zahlungsvereinbarungen aus dem Rechnungsarchiv ableitet (jüngste Rechnung pro Vereinbarung mit `payment_option.type = recurring` und `user_payment_option.status = active`) und als `grandfathered` in `user_payment_options` schreibt (Beträge netto in `legacy_conditions.net_cents`). Die nächste Rechnung stellt danach der tägliche MAN-Kreis-Lauf (`billing:generate-manual-invoices`) zum gewohnten Rhythmus aus. Optionen: `--dry-run`, `--as-of=`, `--grace-months=12` (älter überfällige Vereinbarungen gelten als stale und bleiben reines Archiv). --- ## Idempotenz / Replay-Sicherheit (Kurzreferenz) Alle Schritte schreiben per `updateOrCreate`/`insertOrIgnore` über `(legacy_portal, legacy_id)` bzw. `legacy_import_map`; **kein Truncate, kein Delete**. Re-Run-Verhalten: | Schritt | ohne `--force` | mit `--force` | zieht Neue nach | |---|---|---|---| | categories / users / companies / contacts | SKIP | UPDATE | ja | | press-releases | SKIP | UPDATE (uuid + slug bleiben erhalten) | ja | | link-associations | `insertOrIgnore` (idempotent) | — | ja | | archive-invoices | SKIP | UPDATE | ja | | grandfather-subscriptions | UPDATE/INSERT je Vereinbarung | — | ja | | fix-timestamps | Raw-UPDATE (idempotent) | — | ja | | migrate-media | SKIP (Pfad-Check) | **OVERWRITE** (Vorsicht) | ja | Vor Phase 2 immer `legacy:verify` laufen lassen, um Lücken aus Phase 1 (z. B. fehlgeschlagene User-Importe → verwaiste Rechnungen) zu erkennen. --- ## Noch nicht finalisiert - Medien-/Bilddateien-Transfer: Scope/Command vorhanden (`legacy:migrate-media`), finale Base-Path-Strategie auf Live noch festzulegen. - Staging-Rehearsal mit aktuellem Produktiv-Snapshot bleibt Pflicht vor Go-Live. ## Legacy-Rechnungsreport `legacy:archive-invoices` schreibt standardmäßig: ```bash storage/app/private/migration/legacy-invoices-*.json ``` Der Report enthält pro Portal: Source-Count, importierte/übersprungene/fehlerhafte Rechnungen, Summe in Cent, Statusverteilung, Anzahl unzugeordneter Legacy-User, Anzahl erzeugter PDF-Payloads.