docs/ROL-02-PRUEFPROTOKOLL.md

@@ -0,0 +1,113 @@
+# ROL-02 — Prüfprotokoll Rollback-Testlauf
+
+Datum: 2026-10-15
+Umgebung: Host 204 (Dev/Test), Wegwerf-Postgres-Cluster, synthetische Testkopie
+Paket: `internal/rollbackrun` (Root-Modul), aufbauend auf `internal/cutoverorchestrator` (CUT-02) und `internal/rollbackcriteria` (ROL-01)
+
+## Ausgangslage
+
+ROL-01 liefert die Rollback-Kriterien (Schwellenwerte, Freigabe) und CUT-02
+liefert die große synthetische Testkopie des Generalprobe-Trockenlaufs.
+ROL-02 testet den eigentlichen Rollback-Mechanismus: das Altsystem (hier
+exemplarisch die archivmail-Testkopie) wird — wie am echten Stichtag — nicht
+gelöscht, sondern in einen Wartungsmodus (read-only) versetzt, während der
+NEXARCH-Tenant freigeschaltet ist. Ein Rollback muss diesen Zustand rückgängig
+machen: Wartungsmodus aufheben, Freischaltung zurücknehmen.
+
+Da es im bestehenden Code noch kein explizites Wartungsmodus-Flag für die
+Altsystem-Testkopie gab, wurde dafür eine kleine, eigenständige Tabelle
+`legacy_system_state` (Spalten `maintenance_mode`, `nexarch_enabled`) ergänzt
+sowie der Wartungsmodus real auf Datenbankebene durchgesetzt
+(`ALTER DATABASE ... SET default_transaction_read_only = on`), statt ihn nur
+als Flag zu simulieren. Dadurch prüft der Test echten Schreibschutz und echte
+Schreibfähigkeit nach dem Rollback, nicht nur eine Statuszeile.
+
+## Testaufbau
+
+- `rollbackrun.Setup`: legt eine frische Wegwerf-Datenbank an, seedet das
+  archivmail-Schema mit `cutoverorchestrator.GenerateDataset` (synthetische
+  Daten, Seed 11, Bcrypt-Kostenfaktor 4 für Testgeschwindigkeit), legt
+  `legacy_system_state`/`legacy_writeprobe` an, setzt den betroffenen Tenant
+  (ID 101, Kanzlei Musterhausen) auf `maintenance_mode=true`,
+  `nexarch_enabled=true` und aktiviert den Wartungsmodus auf DB-Ebene.
+- `rollbackrun.Rollback`: prüft die Vorbedingung (Wartungsmodus +
+  Freischaltung aktiv), hebt den Wartungsmodus auf, nimmt die Freischaltung
+  zurück, verifiziert echten Schreibzugriff (Insert in `legacy_writeprobe`)
+  und vergleicht Zeilenzahlen + Prüfsummen (`md5` über alle Spalten je
+  Tabelle) der Altsystem-Tabellen vor/nach dem Rollback.
+
+## Prüfungen und Ergebnisse
+
+### Prüfung 1: Simulierter Rollback in Testumgebung erfolgreich abgeschlossen
+
+Automatisierte Tests gegen echte Postgres-Testdatenbank auf Host 204 (kein
+Mocking), Paket `internal/rollbackrun`:
+
+```
+=== RUN   TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode
+--- PASS: TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode (0.38s)
+=== RUN   TestRollback_RestoresWriteAccessAndMeasuresDuration
+    rollbackrun_test.go:81: gemessene rollback-dauer: 23.889654ms
+--- PASS: TestRollback_RestoresWriteAccessAndMeasuresDuration (0.46s)
+=== RUN   TestRollback_RejectsWhenNotInMaintenanceMode
+--- PASS: TestRollback_RejectsWhenNotInMaintenanceMode (0.43s)
+=== RUN   TestSnapshotTables_DetectsChange
+--- PASS: TestSnapshotTables_DetectsChange (0.36s)
+PASS
+ok  	gitea.perlbach24.de/scripte/nexarch/internal/rollbackrun	1.628s
+```
+
+- `TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode` belegt, dass die
+  Testkopie im Wartungsmodus tatsächlich read-only ist (ein Schreibversuch
+  schlägt mit `SQLSTATE 25006` fehl) — ohne diese Vorbedingung wäre der
+  Rollback-Testlauf nicht aussagekräftig.
+- `TestRollback_RestoresWriteAccessAndMeasuresDuration` spielt den vollen
+  Rollback-Pfad durch: Wartungsmodus aufheben, Freischaltung zurücknehmen,
+  Schreibzugriff verifizieren, Datenverlust-Vergleich — Ergebnis: Erfolg,
+  keine Abweichung.
+- `TestRollback_RejectsWhenNotInMaintenanceMode` stellt sicher, dass ein
+  zweiter Rollback auf einen bereits zurückgenommenen Zustand kontrolliert
+  abgelehnt wird (Vorbedingungsprüfung), statt unbemerkt Status zu
+  überschreiben.
+
+### Prüfung 2: Nach Rollback kein Datenverlust im Altsystem feststellbar
+
+- Vergleichstabellen (`rollbackrun.BusinessTables`): `tenants`,
+  `tenant_domains`, `users`, `storage_objects`, `emails`, `attachments`,
+  `email_attachments`, `email_refs`, `audit_log`, `reconciliation_reports`,
+  `dsgvo_requests`.
+- Je Tabelle wird vor und nach dem Rollback Zeilenzahl + `md5`-Prüfsumme
+  über alle Zeilen gebildet und verglichen (`report.DataLossDetected`,
+  `report.MismatchedTables`).
+- `legacy_system_state` und `legacy_writeprobe` sind bewusst ausgenommen:
+  sie drücken den Wartungsmodus- bzw. Schreibtest-Zustand selbst aus, der
+  sich durch den Rollback gewollt ändert.
+- `TestSnapshotTables_DetectsChange` belegt, dass der Vergleichsmechanismus
+  echte Abweichungen tatsächlich erkennt (keine Scheinprüfung, die immer
+  grün ausfällt).
+- Ergebnis im Testlauf: `DataLossDetected = false`, keine abweichenden
+  Tabellen.
+
+## Akzeptanzkriterien
+
+1. **Rollback-Pfad in Testumgebung erfolgreich durchgespielt**: erfüllt,
+   siehe `TestRollback_RestoresWriteAccessAndMeasuresDuration`.
+2. **Altsystem nach simuliertem Rollback vollständig nutzbar**: erfüllt —
+   Wartungsmodus auf DB-Ebene aufgehoben, exemplarischer Schreibzugriff
+   (`legacy_writeprobe`-Insert im Test sowie im Rollback-Ablauf selbst)
+   erfolgreich.
+3. **Dauer des Rollback-Vorgangs gemessen und dokumentiert**: erfüllt —
+   gemessene Dauer im Testlauf: **23,89 ms** (Messzeitraum: ab
+   Wartungsmodus-Aufhebung bis einschließlich verifiziertem Schreibzugriff,
+   ohne die flankierenden Vorher-/Nachher-Datenvergleiche). Werte für
+   wiederholte Läufe liegen im niedrigen zweistelligen Millisekundenbereich,
+   da der Vorgang im Kern aus wenigen Metadaten-Änderungen (ALTER DATABASE,
+   zwei Tabellen-Updates/-Inserts) auf einer kleinen Testkopie besteht.
+
+## Fazit
+
+Der Rollback-Pfad (Wartungsmodus aufheben, NEXARCH-Freischaltung
+zurücknehmen) wurde in der isolierten Testumgebung auf Host 204 real
+durchgespielt — gegen eine echte Postgres-Testdatenbank, mit synthetischen
+Daten, ohne Produktivsysteme oder -daten. Alle drei Akzeptanzkriterien sind
+durch automatisierte, tatsächlich ausgeführte Tests belegt.

internal/rollbackrun/rollbackrun.go

@@ -0,0 +1,192 @@
+package rollbackrun
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/cutoverorchestrator"
+)
+
+const legacyStateSchemaSQL = `
+CREATE TABLE legacy_system_state (
+    tenant_id        BIGINT PRIMARY KEY,
+    maintenance_mode BOOLEAN NOT NULL DEFAULT false,
+    nexarch_enabled  BOOLEAN NOT NULL DEFAULT false,
+    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE legacy_writeprobe (
+    id         BIGSERIAL PRIMARY KEY,
+    note       TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+`
+
+// BusinessTables werden fuer den Datenverlust-Vergleich herangezogen.
+// legacy_system_state/legacy_writeprobe gehoeren nicht dazu: sie druecken
+// den Wartungsmodus- bzw. Schreibtest-Zustand selbst aus, der sich durch
+// den Rollback gewollt aendert.
+var BusinessTables = []string{
+	"tenants", "tenant_domains", "users", "storage_objects", "emails",
+	"attachments", "email_attachments", "email_refs", "audit_log",
+	"reconciliation_reports", "dsgvo_requests",
+}
+
+type Testbed struct {
+	DBName   string
+	Pool     *pgxpool.Pool
+	TenantID int64
+}
+
+func Setup(ctx context.Context, cluster *cutoverorchestrator.Cluster, dbName string, tenantID int64, data cutoverorchestrator.ArchivmailData) (*Testbed, error) {
+	if err := cluster.CreateDatabase(ctx, dbName); err != nil {
+		return nil, err
+	}
+	pool, err := cluster.Connect(ctx, dbName)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := cutoverorchestrator.SeedArchivmail(ctx, pool, data); err != nil {
+		pool.Close()
+		return nil, err
+	}
+	if _, err := pool.Exec(ctx, legacyStateSchemaSQL); err != nil {
+		pool.Close()
+		return nil, fmt.Errorf("legacy_system_state anlegen: %w", err)
+	}
+	if _, err := pool.Exec(ctx, `INSERT INTO legacy_system_state (tenant_id, maintenance_mode, nexarch_enabled) VALUES ($1, true, true)`, tenantID); err != nil {
+		pool.Close()
+		return nil, fmt.Errorf("wartungszustand setzen: %w", err)
+	}
+	if _, err := pool.Exec(ctx, "ALTER DATABASE "+pgx.Identifier{dbName}.Sanitize()+" SET default_transaction_read_only = on"); err != nil {
+		pool.Close()
+		return nil, fmt.Errorf("wartungsmodus aktivieren: %w", err)
+	}
+	pool.Close()
+
+	roPool, err := cluster.Connect(ctx, dbName)
+	if err != nil {
+		return nil, fmt.Errorf("neuverbindung im wartungsmodus: %w", err)
+	}
+	return &Testbed{DBName: dbName, Pool: roPool, TenantID: tenantID}, nil
+}
+
+func DropDatabase(ctx context.Context, cluster *cutoverorchestrator.Cluster, dbName string) error {
+	conn, err := pgx.Connect(ctx, cluster.AdminDSN())
+	if err != nil {
+		return err
+	}
+	defer conn.Close(ctx)
+	_, err = conn.Exec(ctx, "DROP DATABASE IF EXISTS "+pgx.Identifier{dbName}.Sanitize()+" WITH (FORCE)")
+	return err
+}
+
+type tableSnapshot struct {
+	count    int64
+	checksum string
+}
+
+func snapshotTables(ctx context.Context, pool *pgxpool.Pool, tables []string) (map[string]tableSnapshot, error) {
+	out := make(map[string]tableSnapshot, len(tables))
+	for _, tbl := range tables {
+		q := fmt.Sprintf(`SELECT count(*), coalesce(md5(string_agg(r, '' ORDER BY r)), '') FROM (SELECT (t.*)::text AS r FROM %s t) s`,
+			pgx.Identifier{tbl}.Sanitize())
+		var snap tableSnapshot
+		if err := pool.QueryRow(ctx, q).Scan(&snap.count, &snap.checksum); err != nil {
+			return nil, fmt.Errorf("snapshot tabelle %s: %w", tbl, err)
+		}
+		out[tbl] = snap
+	}
+	return out, nil
+}
+
+type Report struct {
+	TenantID         int64
+	Start            time.Time
+	End              time.Time
+	Duration         time.Duration
+	WriteVerified    bool
+	WriteProbeID     int64
+	TablesCompared   []string
+	DataLossDetected bool
+	MismatchedTables []string
+}
+
+// Rollback hebt den Wartungsmodus des Altsystems auf und nimmt die
+// NEXARCH-Freischaltung des Tenants zurueck. Die gemessene Dauer umfasst
+// genau diese Operation (ohne die flankierenden Vorher-/Nachher-Pruefungen).
+func Rollback(ctx context.Context, cluster *cutoverorchestrator.Cluster, tb *Testbed) (Report, error) {
+	before, err := snapshotTables(ctx, tb.Pool, BusinessTables)
+	if err != nil {
+		return Report{}, err
+	}
+
+	var maint, nex bool
+	if err := tb.Pool.QueryRow(ctx, `SELECT maintenance_mode, nexarch_enabled FROM legacy_system_state WHERE tenant_id = $1`, tb.TenantID).Scan(&maint, &nex); err != nil {
+		return Report{}, fmt.Errorf("wartungszustand lesen: %w", err)
+	}
+	if !maint || !nex {
+		return Report{}, fmt.Errorf("rollback-vorbedingung verletzt: wartungsmodus=%v freischaltung=%v", maint, nex)
+	}
+
+	start := time.Now()
+
+	conn, err := tb.Pool.Acquire(ctx)
+	if err != nil {
+		return Report{}, fmt.Errorf("verbindung fuer wartungsmodus-aufhebung: %w", err)
+	}
+	// SET transaction_read_only gilt nur fuer die laufende Transaktion;
+	// ohne den Override in derselben impliziten Transaktion wie die
+	// ALTER-DATABASE-Anweisung wuerde diese als Schreibzugriff unter dem
+	// noch aktiven default_transaction_read_only=on abgelehnt (SQLSTATE 25006).
+	_, err = conn.Exec(ctx, "SET transaction_read_only = off; ALTER DATABASE "+pgx.Identifier{tb.DBName}.Sanitize()+" SET default_transaction_read_only = off;")
+	conn.Release()
+	if err != nil {
+		return Report{}, fmt.Errorf("wartungsmodus aufheben: %w", err)
+	}
+	tb.Pool.Close()
+
+	rwPool, err := cluster.Connect(ctx, tb.DBName)
+	if err != nil {
+		return Report{}, fmt.Errorf("neuverbindung nach rollback: %w", err)
+	}
+	tb.Pool = rwPool
+
+	if _, err := tb.Pool.Exec(ctx, `UPDATE legacy_system_state SET maintenance_mode = false, nexarch_enabled = false, updated_at = now() WHERE tenant_id = $1`, tb.TenantID); err != nil {
+		return Report{}, fmt.Errorf("freischaltung zuruecknehmen: %w", err)
+	}
+
+	var probeID int64
+	if err := tb.Pool.QueryRow(ctx, `INSERT INTO legacy_writeprobe (note) VALUES ('rollback-schreibtest') RETURNING id`).Scan(&probeID); err != nil {
+		return Report{}, fmt.Errorf("altsystem nach rollback nicht beschreibbar: %w", err)
+	}
+
+	end := time.Now()
+
+	after, err := snapshotTables(ctx, tb.Pool, BusinessTables)
+	if err != nil {
+		return Report{}, err
+	}
+
+	var mismatches []string
+	for _, tbl := range BusinessTables {
+		if before[tbl] != after[tbl] {
+			mismatches = append(mismatches, tbl)
+		}
+	}
+
+	return Report{
+		TenantID:         tb.TenantID,
+		Start:            start,
+		End:              end,
+		Duration:         end.Sub(start),
+		WriteVerified:    true,
+		WriteProbeID:     probeID,
+		TablesCompared:   append([]string{}, BusinessTables...),
+		DataLossDetected: len(mismatches) > 0,
+		MismatchedTables: mismatches,
+	}, nil
+}

internal/rollbackrun/rollbackrun_test.go

@@ -0,0 +1,144 @@
+package rollbackrun
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/cutoverorchestrator"
+	"gitea.perlbach24.de/scripte/nexarch/internal/testdb"
+)
+
+const testTenantID int64 = 101
+
+func testCluster(t *testing.T) *cutoverorchestrator.Cluster {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	c, err := cutoverorchestrator.NewCluster(adminDSN)
+	if err != nil {
+		t.Fatalf("NewCluster: %v", err)
+	}
+	return c
+}
+
+func setupTestbed(t *testing.T) (*cutoverorchestrator.Cluster, *Testbed) {
+	t.Helper()
+	cluster := testCluster(t)
+	ctx := context.Background()
+
+	ds, err := cutoverorchestrator.GenerateDataset(11, time.Date(2026, 10, 14, 9, 0, 0, 0, time.UTC), 4)
+	if err != nil {
+		t.Fatalf("GenerateDataset: %v", err)
+	}
+
+	dbName := "rol02_" + testdb.Suffix()
+	tb, err := Setup(ctx, cluster, dbName, testTenantID, ds.Archivmail)
+	if err != nil {
+		t.Fatalf("Setup: %v", err)
+	}
+	t.Cleanup(func() {
+		tb.Pool.Close()
+		if err := DropDatabase(context.Background(), cluster, dbName); err != nil {
+			t.Logf("aufraeumen %s fehlgeschlagen: %v", dbName, err)
+		}
+	})
+	return cluster, tb
+}
+
+// AK1 (Pruefung 1): Altsystem im Wartungsmodus ist read-only -- der
+// simulierte Rollback muss diesen Zustand erst aufheben, bevor Schreiben
+// wieder moeglich ist.
+func TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode(t *testing.T) {
+	ctx := context.Background()
+	_, tb := setupTestbed(t)
+
+	_, err := tb.Pool.Exec(ctx, `INSERT INTO legacy_writeprobe (note) VALUES ('sollte scheitern')`)
+	if err == nil {
+		t.Fatal("schreibzugriff im wartungsmodus haette fehlschlagen muessen")
+	}
+}
+
+// AK1/AK2/AK3: Rollback durchspielen, danach Altsystem wieder nutzbar,
+// Dauer gemessen und sinnvoll (kein Timeout, keine Nullzeit durch Fehler).
+func TestRollback_RestoresWriteAccessAndMeasuresDuration(t *testing.T) {
+	cluster, tb := setupTestbed(t)
+	ctx := context.Background()
+
+	report, err := Rollback(ctx, cluster, tb)
+	if err != nil {
+		t.Fatalf("Rollback: %v", err)
+	}
+	if report.Duration <= 0 {
+		t.Fatalf("erwarte gemessene dauer > 0, habe %v", report.Duration)
+	}
+	if report.Duration > 30*time.Second {
+		t.Fatalf("rollback hat unerwartet lange gedauert: %v", report.Duration)
+	}
+	t.Logf("gemessene rollback-dauer: %v", report.Duration)
+	if !report.WriteVerified || report.WriteProbeID == 0 {
+		t.Fatalf("schreibzugriff nach rollback nicht verifiziert: %+v", report)
+	}
+	if report.DataLossDetected {
+		t.Fatalf("datenverlust erkannt, erwartet keiner: %+v", report.MismatchedTables)
+	}
+
+	var maint, nex bool
+	if err := tb.Pool.QueryRow(ctx, `SELECT maintenance_mode, nexarch_enabled FROM legacy_system_state WHERE tenant_id = $1`, testTenantID).Scan(&maint, &nex); err != nil {
+		t.Fatalf("zustand nach rollback lesen: %v", err)
+	}
+	if maint || nex {
+		t.Fatalf("wartungsmodus/freischaltung nach rollback nicht zurueckgenommen: maintenance=%v nexarch=%v", maint, nex)
+	}
+
+	if _, err := tb.Pool.Exec(ctx, `INSERT INTO legacy_writeprobe (note) VALUES ('exemplarischer schreibzugriff nach rollback')`); err != nil {
+		t.Fatalf("altsystem nach rollback nicht voll nutzbar: %v", err)
+	}
+}
+
+// AK1/Pruefung 2: Rollback ohne vorherigen Wartungsmodus wird abgelehnt --
+// verhindert, dass ein bereits zurueckgenommener Zustand erneut "zurueck"-
+// genommen wird und dabei unbemerkt Status verliert.
+func TestRollback_RejectsWhenNotInMaintenanceMode(t *testing.T) {
+	cluster, tb := setupTestbed(t)
+	ctx := context.Background()
+
+	if _, err := Rollback(ctx, cluster, tb); err != nil {
+		t.Fatalf("erster rollback sollte gelingen: %v", err)
+	}
+
+	if _, err := Rollback(ctx, cluster, tb); err == nil {
+		t.Fatal("zweiter rollback haette an der vorbedingung scheitern muessen")
+	}
+}
+
+// Pruefung "kein Datenverlust": Snapshot-Vergleich erkennt eine
+// zwischenzeitliche Aenderung tatsaechlich, statt immer gleich auszufallen.
+func TestSnapshotTables_DetectsChange(t *testing.T) {
+	ctx := context.Background()
+	cluster, tb := setupTestbed(t)
+	if _, err := Rollback(ctx, cluster, tb); err != nil {
+		t.Fatalf("rollback zur vorbereitung (schreibzugriff fuer testaenderung): %v", err)
+	}
+
+	before, err := snapshotTables(ctx, tb.Pool, BusinessTables)
+	if err != nil {
+		t.Fatalf("snapshot vorher: %v", err)
+	}
+
+	if _, err := tb.Pool.Exec(ctx, `UPDATE tenants SET name = name || ' geaendert' WHERE id = $1`, testTenantID); err != nil {
+		t.Fatalf("testaenderung: %v", err)
+	}
+
+	after, err := snapshotTables(ctx, tb.Pool, BusinessTables)
+	if err != nil {
+		t.Fatalf("snapshot nachher: %v", err)
+	}
+
+	if before["tenants"] == after["tenants"] {
+		t.Fatal("aenderung an tenants haette im snapshot sichtbar sein muessen")
+	}
+}