From eaf9b2900353548ba668294c7be4343ef335c253 Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Thu, 7 May 2026 16:09:26 +0200 Subject: [PATCH] =?UTF-8?q?Freigabedoku=20f=C3=BCr=20V3.2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/freigabe-v3_2.md | 170 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 docs/freigabe-v3_2.md diff --git a/docs/freigabe-v3_2.md b/docs/freigabe-v3_2.md new file mode 100644 index 0000000..c3988d5 --- /dev/null +++ b/docs/freigabe-v3_2.md @@ -0,0 +1,170 @@ +# Freigabedokument V3.2 – PDF-Umbenenner + +## Geprüfter Stand + +- Git-Branch: `main` +- Versionsnummer: `3.2.297` +- 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.