147 lines
7.6 KiB
Markdown
147 lines
7.6 KiB
Markdown
# Freigabedokument V3.0 – PDF-Umbenenner
|
||
|
||
## Geprüfter Stand
|
||
|
||
- Git-Branch: `main`
|
||
- Versionsnummer: `3.0.238`
|
||
- MSI-Datei: `PDF-KI-Renamer-3.0.238.msi`
|
||
- Freigabedatum: 2026-05-05
|
||
- **Status:** freigegeben
|
||
|
||
---
|
||
|
||
## Zielsetzung von V3.0
|
||
|
||
V3.0 ist kein Wechsel der Kernfunktion, sondern ein gezielter Qualitätssprung in drei
|
||
Dimensionen: **Infrastruktur** (konsistente Versionierung, Flyway-DB-Migration,
|
||
Jenkins-Stabilisierung, MSI-Vorbereitung), **Transparenz** (Historien-Tab, differenzierte
|
||
Fehlerstatus-Darstellung, Lauf-Summary-Banner) und **Bedienkomfort** (Tooltips, Statuszeile,
|
||
Prompt-Editor). Die fachliche Kernverarbeitung des PDF-Umbenenners – PDF lesen, KI benennen,
|
||
Zieldatei kopieren – bleibt vollständig unverändert. Es wird kein neues Maven-Modul eingeführt;
|
||
die hexagonale Architektur bleibt unangetastet.
|
||
|
||
---
|
||
|
||
## Umgesetzte Issues
|
||
|
||
| # | Commit | Kategorie | Beschreibung |
|
||
|---|---|---|---|
|
||
| #67 | `c6379c0` | Infrastruktur | Konsistente Versionierung via Maven CI-friendly `${revision}`, MANIFEST.MF mit `Implementation-Version`, Fallback `dev` |
|
||
| #68 | `500a8c5` | Infrastruktur | Jenkins-Build mit `-Drevision`-Übergabe, robuste Shade-JAR-Archivierung mit Bash und `mapfile` |
|
||
| #49 | `732d00c` | Infrastruktur | Flyway-Integration mit V1-Basisskript, 3-Fall-Strategie (leer / Bestand baselined / regulärer Folgestart), `PRAGMA foreign_keys` per `SQLiteConfig`, Lock-Mechanismus, vollständige Schema-Prüfcheckliste, manuelle Schema-Evolution entfernt |
|
||
| #51 | `563d9f5` | Fachlich/UX | Einheitliche Status-Darstellung mit Icon, Farbe, Tooltip; `FAILED_RETRYABLE` vs. `FAILED_FINAL` eindeutig differenziert |
|
||
| #66 | `0fe5359` | UX | Tooltips auf Konfigurationstab, Verarbeitungslauf-Tab und Toolbar; zentrale `GuiTooltipTexts`-Konstantenklasse |
|
||
| #73 | `dc17824` | GUI | Summary-Banner unterhalb Fortschrittsbalken nach Laufabschluss |
|
||
| #50 | `4f5ce4c` | GUI | Statuszeile mit Version, Provider/Modell und Konfigurationsdateipfad |
|
||
| #71 | `5d5dee0` | GUI | Prompt-Editor-Tab mit atomarem Speichern (`ATOMIC_MOVE`), Dirty-State, Default-Reset |
|
||
| #7 | `46fc1d4` | GUI | Historien-Tab mit Liste, Detail, Filter, Status-Reset (feldgenau, Versuche bleiben) und destruktivem Löschen (Attempts vor Record in Transaktion) |
|
||
| #65 | `51d6168` | Infrastruktur | MSI-Vorbereitung: jdeps-Modulliste, BAT-Dateien, `winUpgradeUuid`, Pfad-Hinweise in `betrieb.md` |
|
||
|
||
### Weitere Commits
|
||
|
||
| Commit | Beschreibung |
|
||
|---|---|
|
||
| `6e03093` | Architektur-Übersichten ergänzt (`domain-overview.md`, `gui-overview.md`, `adapter-overview.md`) |
|
||
| `4b89743` | Bedienanleitung auf neuen Stand gebracht |
|
||
|
||
---
|
||
|
||
## Architektur-Bilanz
|
||
|
||
| Neu | Anzahl | Bemerkung |
|
||
|---|---|---|
|
||
| Outbound-Ports | 1 | `HistoryQueryPort` |
|
||
| Application-Use-Cases | 5 | `DefaultPromptEditorUseCase`, `DefaultHistoryOverviewUseCase`, `DefaultHistoryDetailsUseCase`, `DefaultHistoryResetDocumentStatusUseCase`, `DefaultDeleteDocumentHistoryUseCase` |
|
||
| Outbound-Adapter | 2 | `SqliteHistoryQueryAdapter`, `FilesystemPromptPortAdapter.savePrompt` |
|
||
| GUI-Bridge-Interfaces | 5 | `GuiPromptEditorPort`, `GuiHistoryOverviewPort`, `GuiHistoryDetailsPort`, `GuiHistoryResetDocumentStatusPort`, `GuiDeleteDocumentHistoryPort` |
|
||
| GUI-Tabs | 2 | „Verlauf", „Prompt" |
|
||
| GUI-Komponenten | 5 | `GuiStatusBar`, `BatchRunSummaryBanner`, `GuiHistoryTab`, `GuiPromptEditorTab`, `ProcessingStatusPresentation` |
|
||
| Bootstrap | 1 + Erweiterung | `ApplicationVersionProvider` und Erweiterung des `GuiStartupContext` (`applicationVersion`, 5 neue Port-Felder) |
|
||
| Datenbank-Migration | – | Flyway-V1-Basisskript, 3-Fall-Strategie, FK-Pragma per `SQLiteConfig`, Lock-Mechanismus |
|
||
|
||
Nicht geändert: `pdf-umbenenner-domain`, `pdf-umbenenner-adapter-in-cli`, headless-Betrieb.
|
||
Bootstrap ausschließlich um MANIFEST.MF-Einträge und neue Bridge-Verdrahtung erweitert.
|
||
|
||
---
|
||
|
||
## Verbindlich verifizierte Spec-Punkte
|
||
|
||
- `${revision}` wird durch `flatten-maven-plugin` (`resolveCiFriendliesOnly`) aufgelöst;
|
||
installierte POMs enthalten kein unaufgelöstes `${revision}`
|
||
- MANIFEST.MF im Fat-JAR trägt `Implementation-Version`; Laufzeit-Fallback ist `dev`
|
||
- `evolveTableColumns()` vollständig aus dem Code entfernt; Flyway ist die einzige
|
||
Schema-Evolutionsquelle
|
||
- Status-Reset setzt feldgenau `overall_status='READY_FOR_AI'`,
|
||
`content_error_count=0`, `transient_error_count=0`, `last_failure_instant=NULL`;
|
||
Versuche (`processing_attempt`) bleiben vollständig unangetastet
|
||
- Tab-Reihenfolge: `Konfiguration | Verarbeitungslauf | Verlauf | Prompt`
|
||
- `PromptPort.savePrompt` bleibt pfadfrei in der Port-Signatur (Hexagonal-konform;
|
||
Pfadauflösung liegt im Adapter)
|
||
- Farbe ist niemals das einzige Unterscheidungsmerkmal; alle Status tragen Icon und Text
|
||
|
||
---
|
||
|
||
## Headless-Kompatibilität
|
||
|
||
Der bestehende Batch-Betrieb über `--headless` bleibt vollständig erhalten. Die
|
||
`.properties`-Datei bleibt die einzige Konfigurationswahrheit. GUI-Code initialisiert
|
||
den headless Pfad nicht. Keine stillen Änderungen an Retry-Semantik, Status-Persistenz
|
||
oder fachlicher Verarbeitungslogik.
|
||
|
||
---
|
||
|
||
## Datenbank-Migration
|
||
|
||
Bestehende Datenbestände aus dem Vorgängerstand werden beim ersten Start der 3-Fall-Strategie
|
||
unterworfen:
|
||
|
||
- **Neue DB** (keine Tabellen vorhanden): Flyway führt `V1__initial_schema.sql` vollständig aus.
|
||
- **Bestand ohne Flyway-History** (typische Vorgänger-DB): vollständige Schema-Prüfcheckliste
|
||
gegen das V1-Zielschema; bei konformem Schema wird eine datierte Backup-Kopie der
|
||
`.sqlite`-Datei erstellt, danach Baseline auf V1 gesetzt. Bei nicht konformem Schema
|
||
bricht der Start mit klarer Fehlermeldung ab – kein stilles Weiterlaufen.
|
||
- **Bestand mit Flyway-History** (regulärer Folgestart): `migrate()` läuft idempotent.
|
||
|
||
`baselineOnMigrate=true` wird ausschließlich in Fall 2 gesetzt.
|
||
|
||
---
|
||
|
||
## Offene Punkte (vor finalem Release)
|
||
|
||
| Thema | Beschreibung |
|
||
|---|---|
|
||
| MSI-Testmatrix | Manueller MSI-Build und vollständige Abarbeitung der Testmatrix auf Windows-Maschine erforderlich; insbesondere Anwendungsstart **ohne JDK** zur Verifikation der `addModules`-Liste |
|
||
| `winUpgradeUuid` | Der GUID `EA8D0149-1401-4D3D-A98D-A2B98DAE5495` wurde im Rahmen von #65 neu generiert. Vor dem ersten produktiven MSI-Release ist sicherzustellen, dass kein bisheriges produktives MSI mit einem abweichenden GUID ausgeliefert wurde – andernfalls bricht der MSI-Upgrade-Mechanismus. Nach Bestätigung „nie produktiv ausgeliefert" ist der GUID damit gesetzt und darf nie wieder geändert werden. |
|
||
| Manueller GUI-Produkttest | Erfolgreicher Build und grüne Tests ersetzen keinen End-to-End-Lauf gegen einen echten KI-Provider mit echten PDFs. |
|
||
| Finale Freigabe | `freigabe-v3_0.md` wird nach abgeschlossenem manuellen Produkttest und MSI-Verifikation in den Status „freigegeben" überführt. |
|
||
|
||
---
|
||
|
||
## Nicht in V3.0
|
||
|
||
- Automatischer Scheduler / Quellordner-Überwachung
|
||
- Token- und Kosten-Tracking
|
||
- Excel-Export
|
||
- Automatische Update-Prüfung
|
||
- Dark Mode
|
||
- Log-Viewer
|
||
- PDF-Viewer Render-DPI-Konfiguration
|
||
- Zoom per Mausrad
|
||
- Hilfe-Datei F1
|
||
- Änderungen an der fachlichen Kernverarbeitung des PDF-Umbenenners
|
||
- Neue Maven-Module, neue KI-Provider, Architekturbrüche
|
||
|
||
---
|
||
|
||
## Freigabeaussage
|
||
|
||
V3.0 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen
|
||
Architektur sind eingehalten. Die fachliche Kernverarbeitung des PDF-Umbenenners
|
||
bleibt unverändert gegenüber dem Vorgängerstand. Keine Release-Blocker für die
|
||
Implementierungs-Freigabe.
|
||
|
||
Die finale Release-Freigabe steht aus bis zur vollständigen Abarbeitung der
|
||
MSI-Testmatrix (insbesondere Verifikation des Anwendungsstarts ohne JDK),
|
||
Klärung des `winUpgradeUuid`-Erstauslieferungsstatus und abgeschlossenem
|
||
manuellem GUI-Produkttest gegen einen echten KI-Provider.
|