major update

docs/importe.md

@@ -1,88 +1,63 @@
 # Importe
 
-Letzte Aktualisierung: 2026-02-22
+Letzte Aktualisierung: 2026-02-24
 
-Diese Seite beschreibt den V1 CSV-Import unter `/admin/imports`.
+## Ziel
 
-## Technischer Aufbau
+CSV-Import (V1) für `users` und `departments` kurz und belastbar dokumentieren.
 
-- 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`.
+## 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 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).
+- 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
 
-## Permissions
+## Berechtigungen
 
-- `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.
+- `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. 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.
+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
+## Assignment-Regeln (wichtig)
 
-- 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.
+- 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`).
 
-## Duplikate und Skip-Verhalten
+## Temp-Dateien und State
 
-- 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`
+- Temp-Pfad: `APP_STORAGE_PATH/imports/tmp`
+- Alte Temp-Dateien werden opportunistisch abgeräumt (24h)
+- Import-State-Token läuft nach 2h ab
 
-## Temporäre Dateien
+## Audit
 
-- 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`
+- Nur Commit-Läufe werden protokolliert (nicht Analyze/Preview).
+- Gespeichert: Metadaten, Counter, Fehlercodes, User/Tenant-Kontext.
+- Retention: 90 Tage.