breadcrumb-the-shire/docs/importe.md

Importe

Letzte Aktualisierung: 2026-02-22

Diese Seite beschreibt den V1 CSV-Import unter /admin/imports.

Technischer Aufbau

• Das Import-Modul ist instanzbasiert über lib/Service/Import/ImportServicesFactory.php verdrahtet.
• ImportService orchestriert Analyze/Preview/Commit.
• ImportStateStoreService kapselt den tokenbasierten Session-State (admin_imports_v1, TTL 2h).
• CsvReaderService und ImportTempFileService sind eigene Instanzservices.
• Import-Audit läuft über ImportAuditService + ImportAuditRunRepository.

Scope (V1)

• Profile: users, departments.
• Create-only: bestehende Einträge werden übersprungen.
• CSV mit , oder ;, UTF-8 (BOM wird toleriert).
• Limits: 10MB und 20.000 Datenzeilen.
• Fehlerausgabe nur in der UI (kein Download in V1).

Permissions

• imports.view: Zugriff auf die Import-Seite.
• imports.audit.view: Zugriff auf Import-Protokolle unter /admin/import-audit.
• users.import: User-Import ausführen.
• users.import_assignments: Tenant/Role/Department aus CSV verwenden.
• departments.import: Department-Import ausführen.

Ablauf

1. Upload
   • Entität wählen (Users oder Departments) und CSV hochladen.
   • Header/Delimiter/Zeilenlimit werden direkt geprüft.
2. Mapping
   • CSV-Header auf Zielfelder mappen.
   • Pflichtziele sind profilabhängig.
3. Preview (Dry run)
   • Keine DB-Schreibvorgänge.
   • Summary + erste Fehler (maximal 500 Einträge).
4. Commit
   • Zeilenweise Verarbeitung (best effort).
   • Gültige Zeilen werden erstellt, fehlerhafte reportet.

Assignment-Regeln

• Users: optional tenant, role, department (jeweils 1:1).
• Departments: optional tenant.
• Identifier-Auflösung:
  • Users: UUID zuerst, ID als Fallback.
  • Departments: tenant ist UUID-only (kein ID-Fallback).
• Nur aktive Datensätze sind gültig.
• Department muss zum Tenant passen.
• Fehlen Assignment-Werte, greifen Defaults aus Settings.
• Ohne users.import_assignments wird ein Mapping mit Assignment-Spalten sofort abgelehnt.

Duplikate und Skip-Verhalten

• In-File-Duplikate: erste Zeile gewinnt, spätere duplicate_in_file.
• Users:
  • bestehende E-Mail: email_exists
• Departments:
  • bestehender Code: code_exists
  • bestehende Kombination aus Tenant + Description: department_exists

Temporäre Dateien

• Uploads liegen unter APP_STORAGE_PATH/imports/tmp.
• Dateinamen werden randomisiert.
• Cleanup entfernt alte Temp-Dateien opportunistisch (älter als 24h).

Import-Audit (V1)

• Pro Commit-Lauf wird ein Audit-Run gespeichert (import_audit_runs).
• Analyze/Preview werden bewusst nicht protokolliert.
• Gespeichert werden nur Metadaten:
  • Profil (users/departments), Status (success/partial/failed)
  • Laufzeit, Counter (rows_total, created, skipped, failed)
  • User, aktueller Tenant, Dateiname (basename), gemappte Felder
  • aggregierte Fehlercodes (kein Zeileninhalt)
• Keine CSV-Zeilenpayload oder PII-Details im Audit.
• Retention: 90 Tage, bereinigbar über /admin/import-audit (Purge-Action mit settings.update).

Fehlercodes (V1)

• Struktur: upload_missing, upload_too_large, invalid_file_type, invalid_csv_header, empty_csv, max_rows_exceeded, mapping_required_missing, assignment_permission_required
• Zeilenvalidierung: invalid_email, invalid_tenant_uuid, duplicate_in_file, email_exists, code_exists, department_exists, invalid_locale, invalid_active, invalid_hire_date, tenant_not_found, role_not_found, department_not_found, department_tenant_mismatch, assignment_out_of_scope, create_failed, unexpected_error