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
This commit is contained in:
@@ -6,6 +6,9 @@ M3 fuehrt Mandanten, Benutzer, Mitgliedschaften und Grundeinstellungen additiv
|
||||
ein. Die bestehende Legacy-App bleibt dabei lauffaehig und wird noch nicht auf
|
||||
das neue Modell umgestellt.
|
||||
|
||||
Status: abgeschlossen fuer den M3-Scope. M4 startet mit der additiven
|
||||
Migration von Einzahlungen und Kaffeeverbrauch nach `ledger_entries`.
|
||||
|
||||
## Ziel
|
||||
|
||||
- Einen Default-Tenant fuer den aktuellen Bestand erzeugen.
|
||||
@@ -272,5 +275,14 @@ Umgesetzter Umfang:
|
||||
16. Golden-Master und HTTP-Smoke ausfuehren: erledigt.
|
||||
17. Mail-Transport-Abstraktion und Mail-Flow-Kontrollskript bauen: erledigt.
|
||||
18. Public-Landingpage mit erstem Hero-Asset vorbereiten: erledigt.
|
||||
19. M3-Abschlusscheck dokumentieren und M4-Datenmigration starten:
|
||||
naechster Schritt.
|
||||
19. M3-Abschlusscheck dokumentieren und M4-Datenmigration starten: erledigt.
|
||||
|
||||
## Uebergabe an M4
|
||||
|
||||
M4 ist in `docs/m4-data-migration.md` dokumentiert. Der erste M4-Schritt ist
|
||||
bewusst additiv:
|
||||
|
||||
- `ledger_entries` wird als neue tenant-sichere Buchungstabelle angelegt.
|
||||
- Legacy-Einzahlungen und Legacy-Kaffeeverbrauch werden gespiegelt.
|
||||
- Bestehende Seiten bleiben vorerst auf den `kl_*`-Tabellen.
|
||||
- Summen werden gegen den Golden Master verglichen.
|
||||
|
||||
@@ -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.
|
||||
@@ -283,8 +283,8 @@ Uebersicht:
|
||||
| M0 | Baseline | Bestand, Sicherheit und Designreferenz sind dokumentiert |
|
||||
| M1 | Golden Master | Legacy-Ergebnisse sind als Vergleichsbasis eingefroren; HTTP-Smoke prueft sichere Seiten |
|
||||
| M2 | Technisches Fundament | Abgeschlossen: Migrationen, Bootstrap, Session, CSRF-Helper und Legacy-Schreibseitenschutz stehen |
|
||||
| M3 | SaaS-Basis | Tenants, User, Registrierung, Login, Rollen, Mail-Links und zentrale Mandantenauswahl funktionieren |
|
||||
| M4 | Datenmigration | Legacy-Daten sind tenant-sicher im Zielmodell abgebildet |
|
||||
| M3 | SaaS-Basis | Abgeschlossen: Tenants, User, Registrierung, Login, Rollen, Mail-Links und zentrale Mandantenauswahl funktionieren |
|
||||
| M4 | Datenmigration | Gestartet: Ledger-Tabelle, Legacy-Backfill und Paritaetscheck sind umgesetzt |
|
||||
| M5 | App-Kern | Dashboard, Striche, Einzahlungen, Mitglieder und Liste laufen |
|
||||
| M6 | Betriebsflows | Import, Export, Mail und Jahresprozesse sind auditierbar |
|
||||
| M7 | Landingpage | Erste werbliche Seite ist oeffentlich nutzbar; spaetere Ausbaustufen folgen |
|
||||
@@ -434,6 +434,7 @@ Ergebnis:
|
||||
- Rollen und Tenant-Kontext sind serverseitig verfuegbar.
|
||||
- Reset- und Verifikationslinks koennen im Dev-Modus geloggt und produktiv ueber
|
||||
einen konfigurierten Mail-Transport versendet werden.
|
||||
- Status: abgeschlossen fuer den M3-Scope.
|
||||
|
||||
Abhaengigkeiten:
|
||||
|
||||
@@ -446,18 +447,23 @@ Bestehende Kaffeelisten-Daten tenant-sicher uebernehmen.
|
||||
|
||||
Schritte:
|
||||
|
||||
- Initialen Tenant fuer den bisherigen Bestand anlegen.
|
||||
- `kl_Mitarbeiter` nach `participants` migrieren.
|
||||
- `admin`-Informationen in `tenant_memberships` oder Admin-Rollen ueberfuehren.
|
||||
- `kl_config` nach `tenant_settings` migrieren.
|
||||
- `kl_Einzahlungen` und `kl_Kaffeeverbrauch` nach `ledger_entries` migrieren.
|
||||
- Legacy-IDs speichern.
|
||||
- Salden gegen Golden-Master vergleichen.
|
||||
- Initialen Tenant fuer den bisherigen Bestand anlegen: erledigt in M3.
|
||||
- `kl_Mitarbeiter` nach `participants` migrieren: erledigt in M3.
|
||||
- `admin`-Informationen in `tenant_memberships` oder Admin-Rollen ueberfuehren:
|
||||
erledigt in M3.
|
||||
- `kl_config` nach `tenant_settings` migrieren: erledigt in M3.
|
||||
- `ledger_entries` als tenant-sichere Buchungstabelle anlegen: erledigt.
|
||||
- `kl_Einzahlungen` und `kl_Kaffeeverbrauch` additiv nach `ledger_entries`
|
||||
spiegeln: erster Backfill erledigt.
|
||||
- Legacy-IDs speichern: erledigt ueber `legacy_table` und `legacy_id`.
|
||||
- Salden gegen Golden-Master vergleichen: Kontrollskript erledigt.
|
||||
|
||||
Ergebnis:
|
||||
|
||||
- Bestehender Datenbestand ist im neuen Modell abgebildet.
|
||||
- Saldenparitaet ist nachweisbar.
|
||||
- Bestehender Datenbestand kann im neuen Modell abgebildet werden.
|
||||
- Saldenparitaet ist ueber `scripts/check-m4-ledger-migration.php`
|
||||
nachweisbar.
|
||||
- Dokumentation: `docs/m4-data-migration.md`.
|
||||
|
||||
Abhaengigkeiten:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user