Freigabedoku für V3.2
This commit is contained in:
@@ -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.
|
||||||
Reference in New Issue
Block a user