M4 Ledger-Migration fuer Legacy-Buchungen starten

- ledger_entries als tenant-sichere Buchungstabelle ergaenzen - Legacy-Einzahlungen und Kaffeeverbrauch idempotent spiegeln - M4-Paritaetscheck und Datenmigrationsdoku ergaenzen
2026-07-13 20:45:28 +02:00
parent b0e21bbb0a
commit e4b0c81b48
6 changed files with 640 additions and 13 deletions
@@ -0,0 +1,150 @@
+# M4 Datenmigration Fachlicher Kern
+
+Stand: 2026-07-13
+
+M4 uebernimmt die finanznahen Legacy-Buchungen additiv in das neue
+tenant-sichere Ledger-Modell. Die bestehenden Legacy-Seiten lesen und schreiben
+weiterhin die bisherigen `kl_*`-Tabellen; das Ledger dient zunaechst als
+vergleichbare, pruefbare Zielstruktur.
+
+## Ziel
+
+- `kl_Einzahlungen` nach `ledger_entries` spiegeln.
+- `kl_Kaffeeverbrauch` nach `ledger_entries` spiegeln.
+- Legacy-IDs erhalten, damit Paritaet und spaetere Delta-Migration moeglich
+  bleiben.
+- Summen gegen den Golden Master pruefen.
+- Keine bestehenden Legacy-Buchungen loeschen oder veraendern.
+
+## Nicht-Ziele
+
+- Keine Umstellung der operativen Seiten auf das Ledger in diesem Schritt.
+- Keine Storno-/Korrektur-UI.
+- Kein CSV-Import auf neues Import-Batch-Modell.
+- Kein PDF-/Mail-/Jahresprozess-Rewrite.
+
+## Umgesetzter erster Schritt
+
+Umgesetzte Migration:
+
+```text
+database/migrations/0006_saas_ledger_entries.sql
+```
+
+Neue Tabelle:
+
+- `ledger_entries`
+
+Ergaenzende Skripte:
+
+```text
+scripts/backfill-ledger-entries.php
+scripts/check-m4-ledger-migration.php
+```
+
+Ausgefuehrter Dev-Stand:
+
+- Migration `0006_saas_ledger_entries.sql` wurde angewendet.
+- 9 Legacy-Einzahlungen wurden als `payment` gespiegelt.
+- 12 Legacy-Kaffeeverbrauch-Zeilen wurden als `consumption` gespiegelt.
+- Ein zweiter Backfill-Lauf blieb idempotent und erzeugte keine Dubletten.
+
+## Abbildungsregeln
+
+### Einzahlungen
+
+Quelle:
+
+```text
+kl_Einzahlungen
+```
+
+Ziel:
+
+```text
+ledger_entries.type = payment
+ledger_entries.amount_cents = Betrag * 100
+ledger_entries.booked_at = Datum
+ledger_entries.source = legacy_payment
+ledger_entries.legacy_table = kl_Einzahlungen
+ledger_entries.legacy_id = EinzahlungsID
+```
+
+Einzahlungen werden positiv gespeichert.
+
+### Kaffeeverbrauch
+
+Quelle:
+
+```text
+kl_Kaffeeverbrauch
+```
+
+Ziel:
+
+```text
+ledger_entries.type = consumption
+ledger_entries.amount_cents = -Kosten * 100
+ledger_entries.marks_count = AnzahlStriche
+ledger_entries.unit_price_cents = KostenproStrich * 100
+ledger_entries.booked_at = Datum
+ledger_entries.source = legacy_web bei Eintragsart = 2, sonst legacy_manual
+ledger_entries.legacy_table = kl_Kaffeeverbrauch
+ledger_entries.legacy_id = VerbrauchID
+```
+
+Verbrauch wird negativ gespeichert. Damit ergibt `SUM(amount_cents)` direkt den
+aktuellen Saldo eines Teilnehmers.
+
+## Idempotenz und Aufraeumen
+
+Das Backfill-Skript nutzt `tenant_id`, `legacy_table` und `legacy_id` als
+eindeutige Quelle. Wiederholte Laeufe aktualisieren vorhandene Ledger-Zeilen.
+
+Fuer den Default-Tenant werden nur solche Legacy-Spiegelungen entfernt, deren
+urspruengliche Legacy-Zeile nicht mehr existiert. Fachliche Daten werden dabei
+nicht aus den `kl_*`-Tabellen geloescht.
+
+## Ausfuehrung
+
+```bash
+php scripts/backfill-default-tenant.php
+php scripts/backfill-ledger-entries.php
+php scripts/check-m4-ledger-migration.php
+php scripts/check-golden-master.php
+```
+
+In der lokalen VS-Code-Server-Umgebung muss wie bei M2/M3 die lokale PHP-8.3-
+Installation aus `.local/` verwendet werden.
+
+## Akzeptanzkriterien
+
+- Migration `0006_saas_ledger_entries.sql` laeuft erfolgreich: erfuellt.
+- Jede Legacy-Einzahlung hat genau eine Ledger-Zeile: erfuellt.
+- Jeder Legacy-Kaffeeverbrauch hat genau eine Ledger-Zeile: erfuellt.
+- Legacy-IDs sind je Tenant eindeutig: erfuellt.
+- Einzahlungen sind positiv, Verbrauch ist negativ: erfuellt.
+- Verbrauch behaelt Strichanzahl und Preis pro Strich: erfuellt.
+- Web-Striche aus `Eintragsart = 2` bleiben als `source = legacy_web`
+  erkennbar: erfuellt.
+- Ledger-Summen entsprechen dem Golden Master: erfuellt.
+
+## Aktueller Pruefstatus
+
+- M4 Ledger-Migration: gruen mit 73 Assertions.
+- M3 SaaS-Basis: weiterhin gruen.
+- M3 Tenant-Aufloesung: weiterhin gruen.
+- M3 Passwort/E-Mail: weiterhin gruen.
+- M3 Auth-Flow: weiterhin gruen.
+- M3 Settings-Flow: weiterhin gruen.
+- M3 Mail-Flow: weiterhin gruen.
+- Golden Master: weiterhin gruen mit 104 Assertions.
+- HTTP-Smoke: weiterhin gruen mit 22 geprueften Seiten.
+
+## Noch offen in M4
+
+- Neues Repository/Service fuer Ledger-Abfragen der App-Seiten.
+- Tenant-sichere Dashboard-, Strich-, Einzahlungs- und Listenqueries auf Basis
+  des Ledgers.
+- Storno-/Reversal-Modell in der UI statt harter Deletes.
+- Delta-Strategie fuer den finalen Cutover.