# 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 **konfigurierbare Anzahl Zeichen (Basistitel, Default 60, gültiger Bereich 10..120)**
- verständlich und eindeutig
- keine Sonderzeichen außer Leerzeichen, Bindestrichen, Punkten, Kommas und Ampersands

---

### 4.4 Sprache

- Titel werden **auf Deutsch** erzeugt
- Eigennamen bleiben unverändert

---

### 4.5 Dublettenregel

Bei Namenskonflikten:

- `(1)`, `(2)`, … wird angehängt

Regel:

- die konfigurierte maximale Titellänge gilt 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 die konfigurierte maximale Länge einhält
- Dubletten korrekt behandelt wurden
- Begründung vorhanden ist
- Ergebnis reproduzierbar ist

---

## 14. Nicht-Ziele

- kein manueller Verarbeitungslauf durch den Benutzer (die KI-Verarbeitungskette
  läuft ausschließlich automatisiert)
- keine Inhaltsänderung von Dokumenten

---

## 14a. Manuelle Korrektur des Dateinamens nach automatischer Verarbeitung

Nach Abschluss eines automatisierten Verarbeitungslaufs kann der Benutzer den von der
KI vorgeschlagenen Dateinamen der Zieldatei **manuell korrigieren**.

Verbindliche Regeln:

- Die Korrektur ist **optional** und ersetzt keinen erneuten KI-Aufruf.
- Der geänderte Dateiname muss denselben Formatregeln genügen wie ein automatisch
  erzeugter Name (`YYYY-MM-DD - Titel.pdf`, zulässige Sonderzeichen, Titellänge).
- Namenskonflikte im Zielordner werden durch Dubletten-Suffix aufgelöst
  (analog zur automatischen Verarbeitung).
- Die Umbenennung ist **atomar**: entweder Dateisystem und Datenbank werden
  konsistent aktualisiert, oder die Aktion wird vollständig zurückgerollt.
- Die Quelldatei bleibt unverändert.
- Ein manuell korrigierter Dateiname wird in der Versuchshistorie persistiert.

---

## 15. Qualitätsanforderungen

- deterministisches Verhalten
- nachvollziehbare Entscheidungen
- robuste Fehlerbehandlung
- stabile Wiederholbarkeit

---

## 16. Abschlussbewertung

Das Dokument ist:

- widerspruchsfrei
- konsistent
- vollständig für produktive Nutzung
