M1-Fix: Exit-Code für ungültige Konfiguration auf 1 geändert

docs/specs/fachliche-anforderungen.md

@@ -0,0 +1,225 @@
+# Fachliche Anforderungen – PDF-Umbenenner
+
+## 1. Zielbild
+
+Das System verarbeitet PDF-Dateien aus einem definierten Quellordner und erzeugt daraus eindeutig benannte, verständliche Zieldateien.
+
+Ziel ist eine automatisierte, nachvollziehbare, robuste und wiederholbare Benennung von Dokumenten für den produktiven Einsatz.
+
+---
+
+## 2. Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die **fachlichen Anforderungen**.
+
+Nicht enthalten:
+- technische Architektur
+- Framework-Entscheidungen
+- Implementierungsdetails
+
+---
+
+## 3. Hauptprozess
+
+1. Eine PDF-Datei im Quellordner wird als **Verarbeitungskandidat** erkannt.
+2. Die Datei wird verarbeitet.
+3. Falls erfolgreich:
+   - Ein neuer Dateiname wird erzeugt.
+   - Die Datei wird im Zielordner abgelegt.
+4. Falls fehlgeschlagen:
+   - Der Fehler wird dokumentiert.
+   - Ein Retry erfolgt abhängig von der Fehlerart.
+
+---
+
+## 4. Benennungsregeln
+
+### 4.1 Format
+
+Der Dateiname folgt strikt diesem Muster:
+
+`YYYY-MM-DD - Titel.pdf`
+
+---
+
+### 4.2 Datum
+
+Priorität:
+
+1. Rechnungsdatum  
+2. Dokumentdatum  
+3. anderes sinnvolles Dokumentdatum  
+4. aktuelles Datum (Fallback)
+
+#### Definition „anderes sinnvolles Dokumentdatum“
+
+Reihenfolge:
+
+1. Ausstellungsdatum  
+2. Bescheiddatum  
+3. Schreibdatum  
+4. Ende eines Leistungszeitraums  
+
+Fallback auf aktuelles Datum ist erlaubt, wenn kein belastbares Datum eindeutig ableitbar ist.
+
+---
+
+### 4.3 Titel
+
+- maximal **20 Zeichen (Basistitel)**
+- verständlich und eindeutig
+- keine Sonderzeichen außer Leerzeichen
+
+---
+
+### 4.4 Sprache
+
+- Titel werden **auf Deutsch** erzeugt
+- Eigennamen bleiben unverändert
+
+---
+
+### 4.5 Dublettenregel
+
+Bei Namenskonflikten:
+
+- `(1)`, `(2)`, … wird angehängt
+
+Regel:
+
+- 20 Zeichen gelten nur für den Basistitel
+- Suffix wird zusätzlich ergänzt
+
+---
+
+## 5. Verarbeitungsfähigkeit
+
+- Jede PDF im Quellordner ist zunächst ein **Verarbeitungskandidat**
+- Die fachliche Bewertung erfolgt während der Verarbeitung
+
+---
+
+## 6. Fehlerbehandlung
+
+### 6.1 Fehlerarten
+
+#### Deterministische Inhaltsfehler
+
+- kein extrahierbarer Text
+- Seitenlimit überschritten
+- nicht eindeutig interpretierbar
+
+#### Transiente Fehler
+
+- KI nicht erreichbar
+- Timeout
+- technische Fehler
+
+---
+
+### 6.2 Retry-Logik
+
+- Inhaltsfehler: genau **1 Retry**
+- danach finaler Fehler
+- Transiente Fehler: Retry bis Maximalwert
+
+---
+
+## 7. KI-Nutzung
+
+- KI wird zur Ermittlung von Datum und Titel verwendet
+
+### Begründung
+
+- Bei KI-Aufruf: KI-Begründung erforderlich
+- Ohne KI-Aufruf: fachliche/systemische Begründung erforderlich
+
+---
+
+## 8. Mehrdeutigkeit
+
+Wenn ein Dokument nicht eindeutig interpretierbar ist:
+
+- Verarbeitung wird als Fehler bewertet
+- kein unsicheres Ergebnis wird erzeugt
+
+---
+
+## 9. Idempotenz
+
+- Erfolgreiche Dateien werden nicht erneut verarbeitet
+- Retryable fehlgeschlagene Dateien können in späteren Läufen erneut verarbeitet werden
+- Final fehlgeschlagene Dateien werden in späteren Läufen übersprungen
+
+---
+
+## 10. Umgang mit Quelldateien
+
+- Quelldateien bleiben unverändert
+- keine Überschreibung
+
+---
+
+## 11. Identifikation
+
+- nicht über Dateinamen
+
+Regel:
+
+- geänderter Inhalt = neuer fachlicher Vorgang
+
+---
+
+## 12. Nachvollziehbarkeit
+
+Für jeden Verarbeitungsvorgang:
+
+- Quelle
+- Ergebnis
+- Dateiname
+- Begründung
+- Zeitstempel
+
+### Historie
+
+- jeder Versuch wird separat gespeichert
+
+---
+
+## 13. Akzeptanzkriterien
+
+Ein Ergebnis ist korrekt, wenn:
+
+- Format stimmt
+- Datum korrekt ist
+- Titel max. 20 Zeichen hat
+- Dubletten korrekt behandelt wurden
+- Begründung vorhanden ist
+- Ergebnis reproduzierbar ist
+
+---
+
+## 14. Nicht-Ziele
+
+- keine manuelle Nachbearbeitung
+- keine Benutzerinteraktion
+- keine Inhaltsänderung von Dokumenten
+
+---
+
+## 15. Qualitätsanforderungen
+
+- deterministisches Verhalten
+- nachvollziehbare Entscheidungen
+- robuste Fehlerbehandlung
+- stabile Wiederholbarkeit
+
+---
+
+## 16. Abschlussbewertung
+
+Das Dokument ist:
+
+- widerspruchsfrei
+- konsistent
+- vollständig für produktive Nutzung