breadcrumb-the-shire/docs/howto-importe.md

Importe

Letzte Aktualisierung: 2026-03-06

Ziel

CSV-Import (V1) für users und departments kurz und belastbar dokumentieren.

Architektur

• Einstieg: /admin/imports
• Orchestrierung: ImportService
• Upload/Temp: ImportTempFileService
• CSV-Analyse/Stream: CsvReaderService
• State (tokenbasiert, Session): ImportStateStoreService
• Audit: ImportAuditService

Scope (V1)

• Profile: users, departments
• Create-only: bestehende Datensätze werden übersprungen
• CSV-Delimiter: , oder ;
• BOM wird toleriert
• Limits:
  • 10 MB Upload
  • 20.000 Datenzeilen
  • max. 500 Fehlerzeilen in der UI

Berechtigungen

• imports.view
• users.import
• departments.import
• users.import_assignments (nur wenn Assignment-Spalten gemappt werden)
• imports.audit.view (Audit lesen)
• settings.update (Audit-Purge)

Ablauf

1. Analyze: Upload + Header/Delimiter/Limit prüfen.
2. Mapping: CSV-Spalten auf Zielfelder mappen.
3. Preview: Dry-Run ohne DB-Write.
4. Commit: zeilenweise Verarbeitung mit Fehleraggregation.

Assignment-Regeln (wichtig)

• Users: optionale tenant/role/department-Zuordnung.
• Users: Auflösung über UUID, numerische ID als Fallback.
• Departments: tenant ist UUID-only.
• Ohne gültige Assignment-Werte greifen Defaults aus Settings.
• Out-of-scope Tenants werden blockiert (assignment_out_of_scope).

Temp-Dateien und State

• Temp-Pfad: APP_STORAGE_PATH/imports/tmp
• Alte Temp-Dateien werden opportunistisch abgeräumt (24h)
• Import-State-Token läuft nach 2h ab

Audit

• Nur Commit-Läufe werden protokolliert (nicht Analyze/Preview).
• Gespeichert: Metadaten, Counter, Fehlercodes, User/Tenant-Kontext.
• Retention: 90 Tage.