diff --git a/docs/freigabe-v3_0.md b/docs/freigabe-v3_0.md new file mode 100644 index 0000000..cd660ec --- /dev/null +++ b/docs/freigabe-v3_0.md @@ -0,0 +1,148 @@ +# Freigabedokument V3.0 – PDF-Umbenenner + +## Geprüfter Stand + +- Git-Branch: `main` +- Versionsnummer: `3.0.x` + *(Konkrete Build-Nummer wird beim Release-Build von Jenkins als Suffix gesetzt – + Marcus trägt sie hier nach dem finalen Release-Build ein.)* +- Freigabedatum: 2026-05-03 +- **Status:** vorläufige Implementierungs-Freigabe; + finale Release-Freigabe nach abgeschlossener MSI-Testmatrix und manuellem GUI-Produkttest + +--- + +## 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.