pdf-umbenenner/docs/freigabe-v3_2.md

Freigabedokument V3.2 – PDF-Umbenenner

Geprüfter Stand

• Git-Branch: main
• Versionsnummer: 3.2.300
• Freigabedatum: 2026-05-07
• Status: freigegeben

---

Zielsetzung von V3.2

V3.2 ist der Übergang vom manuellen Batch-Tool zur autonomen Dauerläufer-Anwendung. Ein einziges, klar abgegrenztes Hauptfeature:

#22 – Automatischer Scheduler: Die Anwendung überwacht den konfigurierten Quellordner dauerhaft im Hintergrund und startet die Verarbeitungspipeline automatisch, sobald neue PDF-Dateien erkannt werden. Der Nutzer steuert den Scheduler ausschließlich über den neuen Tab „Scheduler".

V3.2 ist eine reine Scheduler-Veranstaltung. Token- und Kosten-Tracking (#74) wurde bewusst herausgelöst und bekommt eine eigene saubere Spezifikation in V3.x – inklusive Modell-Preistabelle, Persistenz-Strategie und EUR-Währung.

Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt vollständig unverändert. Hexagonale Architektur, Modulstruktur, headless-Betrieb, .properties-Konfigurationswahrheit und Flyway-DB-Evolution bleiben unangetastet.

---

Umgesetzte Features

#	Kategorie	Beschreibung
#22	Hauptfeature	Automatischer Scheduler: ScheduledExecutorService-Polling mit scheduleWithFixedDelay; Initial Delay 0 (erster Tick sofort); konfigurierbares Intervall (Minimum 30 s); neuer Tab „Scheduler" mit Start/Stop, Statusanzeige, Countdown, letzter Lauf, Gesamtzähler; OS-Lock auf .properties während Scheduler läuft; Konfig-Tab read-only bei aktivem Lock; manuelle Läufe bei aktivem Scheduler gesperrt; App-Schließen-Guard

Neue Architektur-Komponenten

Neu	Anzahl	Bemerkung
Neues Maven-Modul	1	pdf-umbenenner-adapter-in-scheduler
Inbound-Port-Interfaces	1	SchedulerControlUseCase
Application-Use-Cases	1	DefaultSchedulerControlUseCase
Outbound-Ports	3	SchedulerPort, ConfigurationFileLockPort, SchedulerSettingsPort
Funktionale Interfaces	1	BatchRunTrigger mit sealed BatchRunTriggerResult
Neue Adapter	2	ScheduledExecutorServiceSchedulerAdapter, FileChannelConfigurationAccessAdapter
GUI-Komponenten neu	2	GuiSchedulerTab, GuiStatusRefreshTimeline
Bootstrap-Refactoring	–	Init/Run-Trennung: GuiShellContext immer, ApplicationRunContext bei valider Config; GuiApplicationContextInitializer-Callback für Auto-Load-Pfad
Flyway-Migration	0	Keine DB-Migration in V3.2

Kontrollierte Architekturausnahme: CLAUDE.md wurde um die Scheduler-Ausnahme erweitert. „Keine Dauerlauf-Anwendung" und „kein interner Scheduler" gelten ab V3.2 nur noch für den headless-Pfad.

Zusätzliche Verbesserungen (Produkttest-Nachbesserungen)

Beschreibung
ApplicationRunContext wird nun auch beim Auto-Load-Pfad (ohne --config) korrekt aufgebaut via GuiApplicationContextInitializer-Callback
Double-Lock-Bug im BatchRunTrigger-Lambda behoben: kein eigenes tryAcquire() mehr, Lock ausschließlich in execute()
Stop-Button-Wiring-Bug behoben: GuiStatusRefreshTimeline liest jetzt den Live-Use-Case aus dem Workspace statt aus dem unveränderlichen GuiStartupContext
installSchedulerCloseGuard analog gefixt (gleiches Wiring-Problem)
loadHistoryOverviewForGui und 6 weitere GUI-Methoden im BootstrapRunner nutzen bei vorhandenem ApplicationRunContext direkt den Repository-Adapter statt Config neu zu laden – verhindert IOException bei aktivem Config-Lock
Autostart-Feature entfernt: Scheduler startet nie automatisch, immer nur auf explizite Nutzeraktion
RunSummary-Zählung im Scheduler-Tab korrigiert: PROPOSAL_READY zählt korrekt als Erfolg; Gesamtzähler seit Scheduler-Start eingeführt
Java-Preferences-Knoten auf fixen String de/gecheckt/pdf-umbenenner umgestellt – verhindert Verlust des gespeicherten Config-Pfads nach Code-Änderungen

---

Verbindlich verifizierte Spec-Punkte

• Scheduler startet nur auf explizite Nutzeraktion – kein Autostart
• Erster Tick läuft sofort nach Scheduler-Start (Initial Delay 0)
• scheduleWithFixedDelay: nächster Tick erst N Sekunden nach Laufende
• Laufkollision via nicht-blockierendem RunLockPort.tryAcquire() – kein Queuing
• Manuelle Läufe bei aktivem Scheduler gesperrt (deterministisches Verhalten)
• OS-Lock auf .properties während Scheduler läuft: Konfig-Tab read-only, Speichern-Button deaktiviert, Eingabefelder nicht editierbar
• Verlauf-Tab funktioniert korrekt bei aktivem Config-Lock
• Stop während aktivem Lauf: Batch läuft zu Ende, danach STOPPED
• App-Schließen bei aktivem Scheduler: Hinweisdialog, App schließt nicht
• SchedulerStatus als immutable Snapshot via AtomicReference
• SchedulerState mit 5 Werten: STOPPED, STARTING, RUNNING_IDLE, RUNNING_BATCH_ACTIVE, STOPPING_BATCH_ACTIVE
• No-op-Lauf (keine Kandidaten): „keine neuen Dokumente"; kein Fehlerstatus
• Scheduler-Tab zeigt korrekte Anzeige: letzter Lauf + Gesamtzähler
• Exception im Tick: gefangen, ERROR-geloggt, Executor läuft weiter
• Non-Daemon-Thread; sauberer Shutdown via awaitTermination
• Kein JavaFX im Modul adapter-in-scheduler
• PIT im neuen Modul explizit deaktiviert
• Code-Kommentare auf Deutsch; Logging auf Deutsch
• JavaDoc auf allen neuen öffentlichen Ports, Use-Cases und Adapter-Methoden
• Flyway ist die einzige Schema-Evolutionsquelle – keine Migration in V3.2

---

Headless-Kompatibilität

Der bestehende Batch-Betrieb über --headless bleibt vollständig erhalten. Scheduler-Properties (scheduler.enabled, scheduler.interval.seconds) werden im headless-Modus weder gelesen noch validiert. Der headless-Pfad verwendet keinen Scheduler-Codepfad und keinen Config-Lock.

---

Datenbank-Migration

Keine. Das DB-Schema bleibt unverändert auf V1 (V1__initial_schema.sql). Es wurden keine neuen Spalten und keine neuen Tabellen angelegt.

---

Produkttest

Produkttest: bestanden

Manueller GUI-Produkttest gegen echten KI-Provider mit echten PDFs abgeschlossen. Der Scheduler hat PDFs automatisch erkannt, per KI benannt und in den Zielordner verschoben – vollautomatisch ohne Nutzeraktion. Alle wesentlichen Szenarien (Start/Stop, No-op-Lauf, aktive Verarbeitung, Verlauf-Tab bei aktivem Scheduler, App-Schließen-Guard) wurden verifiziert.

---

Bekannte Einschränkungen

Einschränkung	Bewertung
JavaFX NullPointerException beim Schließen (GraphicsPipeline.getPipeline() == null)	JavaFX-interner Fehler nach Shutdown; kein Fehler im Anwendungscode; kein Datenverlust; kein Handlungsbedarf
Unvollständige PDFs (noch im Kopiervorgang) können temporär FAILED_RETRYABLE erzeugen	Erwartet; bestehende Retry-Semantik behandelt das korrekt beim nächsten Tick

---

Nicht in V3.2

• Token- und Kosten-Tracking (#74) → V3.x (eigene Spezifikation mit Modell-Preistabelle, Persistenz-Strategie, EUR-Währung)
• Headless-Daemon-Betrieb des Schedulers (--watch-Flag) → V3.x
• Java WatchService (ereignisgesteuerte Ordnerüberwachung) → V3.x
• Windows-Service-Integration (WinSW o.ä.) → V3.x
• Modell-Filterung (OpenAI-Snapshots ausblenden) → V3.x
• Dark Mode (#70) → V3.x
• F1-Hilfe (#69) → V3.x
• Log-Viewer in der GUI (#72) → V3.x
• Excel-Export (#75) → V3.x
• Automatische Update-Prüfung (#76) → V3.x
• Neue KI-Provider, Architekturbrüche
• Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners

---

Nächste Version

V3.x – Token- und Kosten-Tracking als eigenständiges, vollständig durchdachtes Feature: Modell-Preistabelle (pro Modell, nicht pro Provider), EUR-Währung, Kostenanzeige im Summary-Banner, Modell-Filterung für OpenAI-kompatible Provider.

---

Freigabeaussage

V3.2 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen Architektur sind eingehalten. Das neue Modul adapter-in-scheduler ist korrekt eingebunden (kein JavaFX, PIT deaktiviert, flatten aktiv). Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt unverändert gegenüber V3.1. Headless-Betrieb vollständig unberührt. Manueller Produkttest bestanden. Keine Release-Blocker.