docs: MAP-01-Pruefprotokoll (Tenant-Export & Slug/Domain-Abgleich)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/MAP-01-PRUEFPROTOKOLL.md

@@ -0,0 +1,69 @@
+# MAP-01 — Prüfprotokoll: Tenant-Export & Slug/Domain-Abgleich
+
+Datum: 2026-10-13
+Testhost: root@192.168.1.204 (Wegwerf-Postgres-Cluster, `TEST_ADMIN_DSN` aus `/etc/nexarch-dev/core-dev.env`, eigenes Test-Schema pro Testlauf über `internal/testdb`, kein Bezug zu `dms_dev`/`archivdms`)
+
+## Synthetische Testdaten — Substitutionsentscheidung
+
+Der Ticket-Auftrag verlangt einen SQL-Export der tenants-Tabellen aus den echten Altsystemen archivmail und archivdms. Es wurde **zu keinem Zeitpunkt** eine Verbindung zu einer echten archivmail- oder archivdms-Datenbank aufgebaut und kein echter Export/Dump gelesen. Stattdessen:
+
+- `internal/tenantmatch/export_test.go` legt eine eigene, synthetische `tenants`-Tabelle (Spalten `id`, `slug`, `name`, `domain`) im isolierten Test-Schema an und befüllt sie mit frei erfundenen Zeilen (Slugs `synth-mandant-a`/`b`/`c`, Namen „Synthetische GmbH A/B/C“, Domains `synth-a.example` usw.).
+- `internal/tenantmatch/match_test.go` verwendet ausschließlich synthetische Tenant-Paare (Slugs `synth-mandant-*`, `synth-conflict`, `synth-false-positive` usw., Namen „Synthetische GmbH …“, „Konflikt GmbH“, „Firma A GmbH“).
+- Die produktive `ExportTenants`-Funktion ist schemagenerisch: sie liest `SELECT id, slug, name, domain FROM tenants` über einen beliebigen, von außen übergebenen DSN. Gegen welche Datenbank sie läuft, entscheidet ausschließlich der Aufrufer (`MAP01_ARCHIVMAIL_DSN`/`MAP01_ARCHIVDMS_DSN` im CLI-Einstiegspunkt `cmd/map01-tenant-match`) — dieser Agent hat diese Umgebungsvariablen nie auf eine echte archivmail-/archivdms-Instanz gesetzt und auch keinen Zugriff darauf angefordert.
+
+Diese Substitution folgt demselben Muster wie COR-01/COR-02: Logik bauen und mit synthetischen, aber strukturell identischen Fixtures testen, keine realen Mandantendaten im Repository oder in Prompts.
+
+## Ausgangslage geprüft
+
+- Keine internen Vorbedingungen im Code — MAP-01 ist laut Auftrag sofort startbar.
+- `migrations/0019_tenant_migration_map.up.sql` (von COR-01 als Stub angelegt, eigentlich MAP-02-Scope) wurde gelesen: Zielschema erwartet `archivmail_tenant_id`, `archivdms_tenant_id`, `slug`, `name`, `approved_by`, `approved_at`. Die Kandidatenausgabe von MAP-01 liefert bewusst exakt die Spalten `archivmail_tenant_id`/`archivdms_tenant_id`/`slug`/`name`, ergänzt um `confidence`/`source`/`conflict`/`conflict_reason` für die menschliche Freigabeprüfung — `approved_by`/`approved_at` bleiben, wie in COR-01 dokumentiert, Sache des (noch zu bauenden) MAP-02-Freigabe-Workflows.
+- Kein vorhandenes Schema für archivmail-/archivdms-`tenants`-Tabellen im Repository gefunden; das Ticket selbst nennt nur `slug`, `name`, `Domain` als Pflichtfelder — dieses Minimalschema wurde für Export/Fixtures übernommen (Spaltenname `domain`, da keine andere Konvention im Code vorgefunden wurde).
+
+## Umsetzung
+
+- Neues Paket `internal/tenantmatch`:
+  - `export.go`: `ExportTenants` (generischer SQL-Export aus einer `tenants`-Tabelle, parametrisiert nur über Pool und Quellsystem-Namen) und `CountTenants` (Zeilenzahl für die Vollständigkeitsprüfung).
+  - `manual.go`: `LoadManualDecisions` liest die manuelle Kunden-Zuordnungsliste aus CSV (`archivmail_slug,archivdms_slug,match,note`).
+  - `match.go`: `Match` erzeugt die Kandidatenliste. Automatischer Abgleich zuerst per exaktem Slug (Konfidenz 1.0), dann per exakter Domain (Konfidenz 0.7) als Fallback. Die manuelle Liste übersteuert: bestätigt sie den automatischen Vorschlag, bleibt die Konfidenz hoch und es gibt keinen Konflikt; weicht sie ab (anderes Ziel oder explizites „kein Match“ trotz automatischem Treffer), wird der Kandidat mit `Conflict = true` und einer `ConflictReason` ausgegeben — **nie** eine stille automatische Entscheidung. Tenants ohne jeden Treffer (weder automatisch noch manuell) werden als einseitiger Kandidat (nur eine der beiden IDs gesetzt, Konfidenz 0) ausgegeben, damit sie in der Freigabeprüfung sichtbar bleiben statt zu verschwinden.
+  - `csv_out.go`: `WriteCandidatesCSV` schreibt die Kandidatenliste im Format `archivmail_tenant_id,archivdms_tenant_id,slug,name,confidence,source,conflict,conflict_reason`.
+- Neuer CLI-Einstiegspunkt `cmd/map01-tenant-match` (liest `MAP01_ARCHIVMAIL_DSN`, `MAP01_ARCHIVDMS_DSN`, optional `MAP01_MANUAL_LIST_CSV` aus der Umgebung, keine Zugangsdaten im Code, schreibt Kandidatenliste nach stdout).
+
+## Akzeptanzkriterien
+
+| # | Kriterium | Ergebnis |
+|---|---|---|
+| 1 | Beide tenants-Tabellen vollständig exportiert, inkl. slug/name/Domain | Erfüllt — `ExportTenants` liest alle Spalten, `TestExportTenants_Vollstaendigkeit` prüft Export-Zeilenzahl gegen `CountTenants` der Quelltabelle |
+| 2 | Automatischer Abgleichsvorschlag erzeugt Kandidatenliste mit Konfidenzwert | Erfüllt — jeder `Candidate` trägt `Confidence` (1.0 Slug-Match, 0.7 Domain-Fallback, 0.0 unmatched), `TestMatch_ZehnBekannteDuplikateKorrektVorgeschlagen` deckt 10 synthetische Duplikat-Paare ab |
+| 3 | Manuelle Zuordnungsliste kann Konflikte des automatischen Abgleichs übersteuern | Erfüllt — `TestMatch_KonfliktZwischenAutoUndManuellSichtbarMarkiert` und `TestMatch_ManuelleListeKannAutomatischenVorschlagAlsKeinMatchMarkieren` zeigen, dass die manuelle Entscheidung das Ergebnis bestimmt, der Konflikt aber als solcher markiert bleibt |
+
+## Prüfungen vor der Abnahme
+
+1. **Export-Vollständigkeit gegen Quelltabellen-Zeilenzahl geprüft.**
+   Ergebnis: erreicht — `TestExportTenants_Vollstaendigkeit`, 3 synthetische Zeilen eingefügt, `len(ExportTenants(...)) == CountTenants(...) == 3`, alle Felder (`slug`/`name`/`domain`/`id`) stimmen exakt.
+
+2. **Stichprobe von 10 bekannten Duplikat-Tenants korrekt vorgeschlagen.**
+   Ergebnis: erreicht — `TestMatch_ZehnBekannteDuplikateKorrektVorgeschlagen`, 10 synthetische Tenant-Paare mit identischem Slug auf beiden Seiten, alle 10 werden mit korrekten IDs, Konfidenz 1.0, `Source = "slug"`, `Conflict = false` vorgeschlagen.
+
+3. **Konflikt zwischen automatischem Vorschlag und manueller Liste wird sichtbar markiert, nicht stillschweigend aufgelöst.**
+   Ergebnis: erreicht — zwei Szenarien getestet: (a) automatischer Slug-Match vs. abweichende manuelle Zuordnung (`TestMatch_KonfliktZwischenAutoUndManuellSichtbarMarkiert`) — manuelle Zuordnung gewinnt, `Conflict = true`, `ConflictReason` nennt den automatischen Vorschlag; (b) automatischer Slug-Match vs. manuelles „kein Match“ (`TestMatch_ManuelleListeKannAutomatischenVorschlagAlsKeinMatchMarkieren`) — Kandidat bleibt einseitig, `Conflict = true`.
+
+Zusätzlich (Regression/Build):
+```
+go build ./...                                            -> keine Fehler
+go vet ./internal/tenantmatch/... ./cmd/map01-tenant-match/... -> keine Befunde
+TEST_ADMIN_DSN=... go test ./internal/tenantmatch/... -v  -> alle 7 Tests PASS
+```
+
+## Entscheidungen (dokumentiert, keine Rückfrage nötig)
+
+- Schema-Annahme `tenants(id, slug, name, domain)` für beide Altsysteme, da im Repository kein vorhandenes Schema für archivmail-/archivdms-`tenants` gefunden wurde und das Ticket selbst nur diese drei fachlichen Felder nennt. Falls das reale Schema abweicht (andere Spaltennamen, zusätzliche Felder), muss `ExportTenants` vor dem echten Cutover angepasst werden — das ist hier dokumentiert, keine Produktentscheidung dieser Kachel.
+- Matching-Reihenfolge Slug (hart, Konfidenz 1.0) vor Domain (weicher Fallback, Konfidenz 0.7): folgt der Produkt-DNA „Freitext-Firmennamen sind zu unreliable“ — Name wird bewusst **nicht** als Matching-Kriterium verwendet, nur zur Anzeige im Kandidaten.
+- Manuelle Liste ist slug-indiziert auf archivmail-Seite (ein Eintrag pro archivmail-Slug). Mehrdeutige manuelle Zuordnungen (mehrere Entscheidungen für denselben archivmail-Slug) werden nicht unterstützt; das CSV-Format geht von einer gepflegten, eindeutigen Liste aus, wie im Ticket beschrieben.
+- Kein Schreibzugriff auf `tenant_migration_map` in dieser Kachel: MAP-01 liefert ausschließlich die Kandidatenliste (CSV nach stdout), die Übernahme in die Freigabe-Tabelle inkl. UI/Workflow bleibt MAP-02-Scope (wie in COR-01 bereits für die Freigabe-Oberfläche dokumentiert).
+- Keine echte Verbindung zu archivmail/archivdms aufgebaut oder versucht — CLI-DSNs blieben während der gesamten Session ungesetzt, alle Tests liefen gegen synthetische Fixtures auf dem Wegwerf-Testhost.
+
+## Offene Punkte für MAP-02 / die echte Cutover-Vorbereitung
+
+- MAP-02 muss die Kandidatenliste von MAP-01 einlesen und daraus die Freigabe-Oberfläche/den Workflow bauen, der `approved_by`/`approved_at` in `tenant_migration_map` befüllt — MAP-01 selbst schreibt nichts in diese Tabelle.
+- Vor dem echten Export muss das tatsächliche Schema der archivmail-/archivdms-`tenants`-Tabellen gegen die hier getroffene Annahme (`id, slug, name, domain`) geprüft werden.
+- Die Konfidenzschwellen (1.0 Slug, 0.7 Domain) sind ein Startwert; ob MAP-02 z.B. eine Mindestkonfidenz für automatische Vorauswahl in der UI verlangt, ist eine Produktentscheidung für MAP-02, nicht für MAP-01.