Daten-Import & Altdaten-Migration

Das Modul Daten-Import & Migration ermöglicht Handwerksbetrieben die schnelle und fehlersichere Übernahme bestehender Stammdaten aus branchenüblichen Fremdsystemen, Warenwirtschafts- und ERP-Lösungen oder individuellen Excel-Dateien.

Es kombiniert eine fehlertolerante Parsing-Engine mit intelligenter Spalten-Erkennung, granularen Rollenprüfungen, einer übersichtlichen Vorschau-Prüfung und einem revisionssicheren 1-Klick-Rollback.

1. Berechtigungen & Rollenverteilung

Der Daten-Import ist modulspezifisch und rollenbasiert abgesichert:

Kunden-Import:
- Erfordert die Berechtigung crm:edit oder administrative Rechte (admin:settings bzw. Inhaberstatus is_owner).
- Mitarbeiter ohne diese Berechtigung können den Kunden-Import weder aufrufen noch ausführen.
Artikel-Import:
- Erfordert die Berechtigung inventory:edit oder administrative Rechte (admin:settings bzw. Inhaberstatus is_owner).
- Monteure und Techniker vor Ort besitzen keinen Zugriff auf den Artikelimport.
Rollback & Verlauf:
- Das Rückgängigmachen von Import-Batches ist auf Benutzer mit admin:settings oder den Schreibrechten des jeweiligen Fachbereichs (crm:edit bzw. inventory:edit) beschränkt.
- Benutzer, die nur Leserechte besitzen (crm:view oder inventory:view), können den Import-Verlauf einsehen, jedoch keine Aktionen auslösen.

2. Einstiegspunkte im System (Hybride Einbindung)

Der Import steht an folgenden Stellen im System zur Verfügung:

Zentraler Hub:
- Über das Hauptmenü: Einstellungen -> Daten-Import (/settings/import).
Kundenverwaltung:
- Direkt in der Kunden-Übersicht (/customers) über die Schaltfläche Importieren neben Kunde anlegen. Öffnet den Wizard mit voreingestelltem Kundentyp.
Artikel- & Lagerverwaltung:
- Direkt im Artikelstamm (/inventory/articles) über die Schaltfläche Importieren in der oberen Aktionsleiste. Öffnet den Wizard mit voreingestelltem Artikeltyp.

3. Unterstützte Dateiformate & Parsing

Die Import-Engine verarbeitet folgende Formate bis zu 250 MB Dateigröße (optimiert für Handwerksbetriebe mit langjähriger Firmenhistorie und großen Artikelkatalogen):

Microsoft Excel (.xlsx, .xls): Direkte Extraktion aller Arbeitsblätter via ExcelJS, automatische Konvertierung von Formelergebnissen, Datumsfeldern und formatierten Zahlenwerten.
CSV- & TSV-Dateien (.csv, .tsv, .txt):
- Automatische Erkennung des Trennzeichens (Semikolon ;, Komma , oder Tabulator \t).
- Vollständige Einhaltung von RFC 4180 (mehrzeilige Felder und maskierte Anführungszeichen).
- Bereinigung von UTF-8-Byte-Order-Marks (\uFEFF) sowie Fallback-Unterstützung für ältere Windows-Codierungen (ANSI / Windows-1252).
- Robustes Parsing deutscher Zahlenformate (z. B. 1.250,50 € oder 12,50).

4. Der 3-stufige Import-Workflow

Der geführte Assistent stellt sicher, dass Altdaten vor dem eigentlichen Schreibvorgang gründlich geprüft und bereinigt werden:

Schritt 1: Dateiupload

Auswahl des Import-Typs (Kundenstamm oder Artikelverzeichnis).
Drag-and-Drop oder Dateidialog mit Unterstützung für große Dateien bis 250 MB (.xlsx, .xls, .csv, .tsv).
Keine verwirrenden Vorab-Einstellungen nötig: Die Datei wird direkt eingelesen.

Schritt 2: Intelligente Spaltenzuordnung (Mapping)

Unmittelbar nach dem Upload führt das System einen automatischen Spaltenabgleich durch (intelligente Mustererkennung anhand deutscher und englischer Standard-Feldnamen und branchenüblicher Aliase wie Kdnr, Name1, Bez1, EK, VK1 etc.).
Tabellarische Gegenüberstellung aller Zielfelder im System mit den erkannten Spalten der Importdatei.
Jedes Pflichtfeld (z. B. Kundenname oder Artikelbezeichnung) ist eindeutig markiert.
Durchsuchbare Dropdown-Auswahl (CustomSelect) mit Option zum Ändern oder Überspringen nicht benötigter Spalten.
Live-Vorschau des ersten Beispielwerts aus der Originaldatei für jedes zugeordnete Feld.
Schnellauswahl zur Neuzuordnung (Automatisch neu zuordnen) oder zum vollständigen Zurücksetzen (Zuordnung leeren).

Schritt 3: Vorschau, Validierung & Duplikatsbehandlung

Vor dem Schreiben in die Datenbank wird jede Zeile geprüft und klassifiziert:

Gültig (Grün): Alle Pflichtfelder vorhanden, Datentypen korrekt, keine Kollisionen.
Hinweis / Duplikat (Gelb): Bestehende Datensätze mit identischer Kundennummer, Artikelnummer (SKU), EAN/GTIN oder gleichem Firmen-/Artikelnamen erkannt.
Fehlerhaft (Rot): Fehlende Pflichtangaben oder ungültige Werte, die einen Import verhindern.

Globale Duplikatsbehandlung:

Bei erkannten Duplikaten kann der Benutzer mit einem Klick die gewünschte Strategie festlegen:

Duplikate überspringen: Bestehende Datensätze bleiben unverändert; doppelte Zeilen werden ignoriert.
Bestehende Einträge aktualisieren: Vorhandene Datensätze werden mit den Werten aus der Importdatei überschrieben (unter Erstellung eines Revisions-Snapshots).
Als neue Einträge anlegen: Es wird ein zusätzlicher Datensatz mit neuer automatischer Nummer erzeugt.

5. Revisionssicheres 1-Klick-Rollback

Jeder Import-Lauf wird als atomarer Stapel (import_batches) protokolliert. Für jede geschriebene Zeile speichert das System eine Zuordnung in import_batch_items:

Vorheriger Zustand (previous_data): Bei Aktualisierungen wird der vollständige JSONB-Snapshot des ursprünglichen Datenstands vor der Änderung gesichert.
Atomare Stored Procedure (rollback_import_batch):
- Klickt ein berechtigter Benutzer im Tab Import-Verlauf auf Import rückgängig machen, wird der gesamte Batch in umgekehrter Reihenfolge zurückgesetzt.
- Neu angelegte Kunden, Kontakte, Standorte oder Artikel werden entfernt.
- Falls ein importierter Kunde oder Artikel zwischenzeitlich bereits in einem Angebot, einer Rechnung oder einem Auftrag verwendet wurde, verhindert eine Foreign-Key-Schutzlogik Fehlermeldungen: Der Datensatz wird stattdessen revisionssicher archiviert (soft-delete).
- Aktualisierte Datensätze erhalten ihren exakten früheren Zustand zurück.

6. Zusammenspiel mit dem Globalen GTIN-Stammkatalog

Das System verfügt über einen mandantenübergreifenden GTIN-Stammkatalog (master_products und master_brands), der beim Artikelimport wie folgt interagiert:

A. Automatische Datenanreicherung (Global -> Lokal)

Besitzt ein importierter Artikel eine valide EAN / GTIN, gleicht das System diese automatisch mit dem globalen Katalog ab.
Fehlen in der Excel-Datei Beschreibungen, Warengruppen oder der Herstellername, werden diese Angaben automatisch aus dem globalen Katalog übernommen und lokal verknüpft (master_product_id).
Der Handwerksbetrieb spart sich das manuelle Nachtragen technischer Detailbeschreibungen.

B. Kontragestützte Katalogpflege (Lokal -> Global)

Sofern in den Organisationseinstellungen die Option zur Katalogteilnahme aktiv ist (contribute_to_global_catalog = true), werden neu importierte physische Handelsartikel mit GTIN neutral an den globalen Katalog gemeldet (syncMasterProduct).
Strikter Schutz von Betriebsgeheimnissen: Es werden zu keinem Zeitpunkt Einkaufspreise, Verkaufspreise, Margen, Rabatte, Lagerbestände, interne Notizen oder Kundendaten übertragen. Der globale Katalog enthält ausschließlich herstellerneutrale Stammdaten (GTIN, Markenname, Artikelbezeichnung).
Dienstleistungsausschluss: Lohn- und Dienstleistungspositionen (type = 'service') sind ausnahmslos vom globalen Katalog ausgeschlossen.

C. Entkopplung bei Rollback

Wird ein lokaler Artikelimport zurückgerollt, verbleiben die neutralen Produktinformationen im globalen Katalog. Sie stehen dem gesamten System weiterhin zum schnellen Scannen und Nachschlagen zur Verfügung.

7. Cloudbasierte Direktanbindung (OData-Schnittstelle)

Für Betriebe, die mobile Serviceberichte und digitale Kundendienstaufträge über cloudbasierte Plattformen abwickeln, bietet das System eine automatisierte Direktanbindung:

Vollautomatischer Datenabruf: Direkte Abfrage von Kunden- und Artikelstammdaten über standardisierte HTTPS/OData-Schnittstellen ohne vorherigen manuellen Dateiexport.
Schonender Stufenabruf (Paging & Rate-Limiting): Um Serverlast und Timeouts bei älteren Cloud-Infrastrukturen zu vermeiden, werden Datensätze seitenweise mit intelligentem Backoff und Wiederholungslogik abgerufen.
Sicherer Testlauf: Betriebe können vorab einen Probelauf über 25 oder 100 Datensätze wählen, um Feldverknüpfungen und Datenqualität in der Vorschau risikofrei zu verifizieren.
Datenschutz & Revisionssicherheit: Alle Authentifizierungsdaten werden flüchtig ausschließlich für den Abruf verwendet und zu keinem Zeitpunkt in der Datenbank gespeichert. Alle importierten Daten durchlaufen die identische Duplikats- und Revisionsprüfung wie Dateiuploads.