nexarch/MIGRATIONSKONZEPT.md

NEXARCH 2.0 – Migrationskonzept

Stand: 2026-08-26. Grundlage: dms-kanban/known-issues-archivdms.md, dms-kanban/known-issues-archivmail.md (Tabellenaufnahme archivmail/archivdms), dms-kanban/, mail-kanban/, core-kanban/, archive-kanban/, workflow-kanban/ (Boards inzwischen aus dem Repo entfernt, Ticket-Historie liegt in der Gitea-PR-Historie).

1. Ausgangslage

• Zwei produktive Altsysteme: archivmail (21 Tabellen, langer Produktivbetrieb laut Ticket-Historie) und archivdms (32 Tabellen, 26 dokumentierte GoBD-Migrationen, funktional reifer).
• Mandanten überschneiden sich teilweise — manche Kunden nutzen beide Systeme parallel. Migration muss dieselbe Organisation als EIN Tenant in NEXARCH zusammenführen, nicht als zwei getrennte.
• Entscheidung: Big Bang — alle Mandanten wechseln zu einem Stichtag. Das verkürzt die Übergangszeit, verlangt aber eine vollständig geprobte Migration vor dem echten Stichtag (siehe Abschnitt 5).
• Zielsysteme: Core (Tenant/User/Rollen/Audit/Token), DMS (Dokumente/Ordner/ACL/Metadaten), Mail (Postfächer/Nachrichten/Anhänge), Archive (Retention/WORM/Löschworkflow/Backup), Workflow (Genehmigungen/Aufgaben/Routing).

2. Grundprinzip: Tenant-Zusammenführung vor allem anderen

Da Mandanten in beiden Altsystemen unabhängig entstanden sind (eigene tenants-Tabelle je System, eigene IDs), ist der erste und riskanteste Schritt die Tenant-Identitätsauflösung:

1. Export beider tenants-Tabellen (archivmail + archivdms) mit slug/name.
2. Abgleich per Slug/Domain-Matching (Firmenname, gepflegte Kunden-Zuordnungsliste als manuelle Fallback-Quelle — automatisches Matching allein ist bei Freitextnamen nicht zuverlässig genug für GoBD-relevante Daten).
3. Für jedes Ergebnis ein tenant_migration_map-Arbeitsblatt: archivmail_tenant_id, archivdms_tenant_id (kann leer sein), nexarch_tenant_id (neu vergeben).
4. Menschliche Freigabe Pflicht für jede Zusammenführung — kein automatischer Merge ohne Bestätigung, da eine falsche Zusammenführung zwei Kunden' Daten sichtbar vermischen würde (Compliance-Vorfall).
5. Ergebnis der Tenant-Map ist eine feste Referenztabelle, die JEDE weitere Migrationsstufe verwendet, um tenant_id-Fremdschlüssel umzuschreiben.

Gleiches Prinzip, eine Ebene tiefer, für Benutzer: ein Mensch kann in archivmail und archivdms mit derselben E-Mail-Adresse, aber unterschiedlicher user_id existieren. Abgleich per E-Mail-Adresse innerhalb desselben zusammengeführten Tenants, gleiche Freigabepflicht. user_migration_map: archivmail_user_id, archivdms_user_id, nexarch_user_id.

3. Tabellen-Mapping nach Zielsystem

→ NEXARCH Core

Alt (archivmail)	Alt (archivdms)	Ziel	Hinweis
tenants	tenants	Core TEN-01 Tenant-Datenmodell	via Tenant-Map zusammengeführt
users	users	Core IAM-01 Benutzer-Datenmodell	via User-Map zusammengeführt, password_hash (bcrypt) 1:1 übernehmbar, kein Rehash nötig
users.role (Textspalte)	users.role + permission_groups/*_grants	Core RBAC-01/RBAC-03	archivdms hat das reifere Modell — als Vorlage für die Zielstruktur nehmen, archivmail-Rollen einfach hineinmappen (Textrolle → passende Core-Rolle)
LDAP-Felder (source)	LDAP-Felder (ldap_uid, ldap_synced_at)	Core IAM-05 LDAP-Anbindung	archivdms-Feldtiefe als Zielschema, archivmail-Konten nachträglich angereichert (fehlende Felder leer/nachsynchronisiert)
audit_log	audit_log	Core AUD-01/AUD-02	beide Systeme nutzen dasselbe Append-only-Trigger-Muster — Zusammenführen ist mechanisch, KEINE inhaltliche Veränderung der historischen Einträge (Audit-Integrität: alte Einträge bleiben mit altem Zeitstempel, nur tenant_id/user_id über die Mapping-Tabellen umgeschrieben)
token_blacklist	token_blacklist	Core IAM-02	wird NICHT migriert — beim Cutover sind alle Alt-Sessions ohnehin ungültig, neue JWTs werden nach dem Login in NEXARCH ausgestellt
API-Keys mit Rate-Limit	Buchhaltungs-API-Keys	Core IAM-09 API-Token	neu ausgestellt, nicht migriert (Secrets werden grundsätzlich nicht kopiert, nur die Berechtigung neu vergeben)

→ NEXARCH DMS

Alt (archivdms)	Ziel	Hinweis
Dokumente + Datei-Revisionen	DMS DOC-01/VER-01-Bereich	Binärdaten per Objekt-Storage-Kopie (nicht per DB-Migration), Metadaten per SQL-Export/Import
akten (Ordner/Aktenstruktur)	DMS DOC-09 Ordner- & Kabinettmodell	1:1 strukturell übernehmbar
document_visibility, permission_groups, *_grants	DMS-Tickets referenzieren Core RBAC-02/RBAC-04	ACL-Daten wandern inhaltlich nach Core-Rechtemodell, nicht in DMS selbst
Custom Fields, Klassifikationsvorlagen	DMS MET-02/MET-04	1:1
ML-Klassifikator (trainiertes Modell)	DMS MET-06	Modell selbst wird NICHT migriert — DMS ist Neubau ohne Codeimport, Trainingsdaten (nicht das archivdms-Binärmodell) können als Grundlage für ein neues Training dienen, falls Trainingsdaten-Export vorliegt
document_shares (Freigabelinks)	DMS DOC-07	aktive, nicht abgelaufene Links migrieren, abgelaufene verwerfen
Gespeicherte Ansichten, Erinnerungen	DMS-UX-Bereich bzw. Workflow TSK-01	Erinnerungen mit offenem Fälligkeitsdatum → Workflow-Board

→ NEXARCH Mail

Alt (archivmail)	Ziel	Hinweis
IMAP/POP3/SMTP-Kontenverwaltung	Mail IMP-07 Mehrfach-Postfach-Verwaltung	Zugangsdaten NICHT kopieren, Postfach-Konfiguration neu anlegen und Verbindung neu testen
Nachrichten + Anhänge (email_refs)	Mail ARC-01/ARC-04	Binärdaten per Objekt-Storage-Kopie, Referenzen per SQL-Export/Import, indexed_at-Statusfeld wird verworfen (Mail-Board indexiert nach der Migration komplett neu, siehe Abschnitt 4)
DSGVO-Löschanfragen (eigene Tabelle)	Archive CMP-02	offene/unbearbeitete Anfragen migrieren, abgeschlossene als historischer Audit-Eintrag
Reconciliation-Reports	Archive BAK-05	historische Reports als Nachweis archivieren, kein aktiver Datenbestand

→ NEXARCH Archive

Alt (beide Systeme)	Ziel	Hinweis
retain_until-Feld auf Kernobjekten	Archive RET-01 generisches Retention-Objektmodell	wichtigster Einzelschritt für GoBD-Kontinuität — Fristen dürfen beim Umzug NICHT zurückgesetzt werden, sonst Compliance-Bruch
Vier-Augen-Löschworkflow (document_delete_requests, nur archivdms)	Archive CMP-06	offene Löschanfragen migrieren, bereits vollzogene Löschungen bleiben nur als Audit-Eintrag bestehen (Objekt existiert nicht mehr)

→ NEXARCH Workflow

Alt (archivdms)	Ziel	Hinweis
Workflows/Automatisierung, Processing-Queue	Workflow ENG-01/RTE-01	laufende Workflow-Instanzen NICHT migrieren (Zustandsmaschine ist Board-spezifisch neu) — nur abgeschlossene Vorgänge als Historie, offene Vorgänge werden vor dem Stichtag bewusst zu Ende geführt oder im Altsystem abgebrochen

4. Was bewusst NICHT migriert wird

• Suchindex (Manticore): kein DB-Sync-Table in beiden Altsystemen vorhanden → nach der Migration wird der komplette Suchindex aus den migrierten Metadaten NEU aufgebaut (Reindexierung), nicht aus dem alten Manticore-Index kopiert.
• Sessions/Tokens: siehe oben, neu ausgestellt.
• ML-Klassifikator-Binärmodell: DMS ist Neubau, kein Codeimport — nur Trainingsdaten (falls vorhanden) als Ausgangspunkt für neues Training.
• Laufende Workflow-Instanzen: vor dem Stichtag im Altsystem abschließen, nicht in einem "halb migrierten" Zustand übernehmen.

5. Ablauf (Big Bang, mit Geprobter Vorbereitung)

"Big Bang" heißt: ein Stichtag für alle Mandanten — es heißt NICHT, den Migrationscode ungetestet gegen die Produktivdaten laufen zu lassen. Vorgeschlagener Ablauf:

1. Trockenlauf 1 (Entwicklung): Migrationsskripte gegen anonymisierte Kopie der Produktivdaten, iterativ.
2. Trockenlauf 2 (Generalprobe): vollständiger Lauf gegen eine reale, aktuelle Kopie beider Produktivdatenbanken, in einer isolierten NEXARCH-Testumgebung. Ergebnis wird stichprobenartig gegen die Quelle geprüft (Anzahl Dokumente/Mails je Tenant, Stichproben-Volltextvergleich, Retention-Fristen-Abgleich).
3. Tenant- und User-Mapping final freigeben (Abschnitt 2) — spätestens hier, nicht erst am Stichtag.
4. Stichtag: Altsysteme in Wartungsmodus (read-only) versetzen, finalen Datenexport ziehen, Migrationsskripte laufen lassen, Verifikation (Abschnitt 6), NEXARCH freischalten.
5. Parallelbetrieb read-only: Altsysteme bleiben für einen definierten Zeitraum (Vorschlag: 90 Tage) lesend erreichbar, für den Fall dass eine Diskrepanz erst nach dem Stichtag aktiv genutzten Daten auffällt.
6. Abschaltung der Altsysteme nach Ablauf der Parallelbetriebsfrist und einer zweiten, schriftlich festgehaltenen Freigabe.

6. Verifikation

Pflicht je Tenant, vor Freischaltung von NEXARCH für diesen Tenant:

• Zeilenzahl je migrierter Kerntabelle (Dokumente, Mails, Benutzer) alt vs. neu deckungsgleich (abzüglich bewusst nicht migrierter Kategorien, siehe Abschnitt 4).
• Stichprobenweiser Hash-Vergleich migrierter Binärdateien (Objekt-Storage) gegen Quelle.
• Retention-Fristen: für eine Stichprobe von Objekten mit retain_until in der Zukunft prüfen, dass die Frist nach der Migration identisch ist.
• Audit-Log-Kontinuität: ältester und neuester Eintrag je Tenant nach Migration mit Quelle abgleichen (keine Lücke, keine Zeitverschiebung).
• Login-Test mit migrierten Zugangsdaten für eine Stichprobe von Benutzern je Tenant.

7. Rollback

Da Big Bang gewählt wurde, muss der Rollback-Pfad vor dem Stichtag feststehen, nicht danach improvisiert werden:

• Altsysteme werden am Stichtag NICHT gelöscht, nur in Wartungsmodus versetzt (siehe Abschnitt 5) — Rollback heißt: Wartungsmodus aufheben, NEXARCH-Freischaltung zurücknehmen.
• Rollback-Entscheidung an klare Kriterien binden (z.B. Verifikation in Abschnitt 6 schlägt für mehr als X % der Tenants fehl) statt Einzelfallentscheidung unter Zeitdruck am Stichtag selbst.

8. Offene Punkte

• Tenant-Matching-Liste (Abschnitt 2) muss von der Geschäftsseite gepflegt werden, nicht rein technisch ableitbar — braucht personelle Zuständigkeit.
• Dauer des Parallelbetriebs (90 Tage vorgeschlagen) ist noch nicht mit Vertrags-/Compliance-Anforderungen abgeglichen.
• Migrations-Tickets selbst (konkrete Kachel-Boards für die Migrationsskripte je Zielsystem) sind noch nicht angelegt — dieses Dokument beschreibt das Konzept, keine Umsetzungs-Kacheln.