# 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.
