marcus/pdf-umbenenner
1
0
Fork 0
Code Issues 14 Releases 2 Activity

Neues Modul pdf-umbenenner-packaging und zugehörige Dokumentation

Browse Source 
- Parent-POM bindet das neue Modul ein und pflegt die jpackage-Plugin-Version
- pdf-umbenenner-packaging enthält jpackage-Inputs: Launcher-Batches, Icon,
  Beispiel-Properties und Icon-README
- CLAUDE.md und docs/betrieb.md ergänzen die MSI-/Packaging-Hinweise
- Arbeitspaket-Dokumente M14 und M15 neu aufgenommen
This commit is contained in:
Marcus van Elst
2026-04-21 16:11:10 +02:00
parent ada7e203e3
commit aaedc2d713
11 changed files with 961 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workpackages/M14_-_Arbeitspakete.md
+361
View File
@@ -0,0 +1,361 @@
# M14 - Arbeitspakete
## Geltungsbereich
Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein
**M14 – Windows-EXE-Packaging (V2.5)**.
Der dokumentierte und freigegebene Stand **V2.0** (Commit `1bb7a427357c73039c09a8e1bfe351dee54df765`)
wird als vollständig umgesetzt und freigegeben vorausgesetzt.
Die Arbeitspakete sind bewusst so geschnitten, dass:
- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
Die Reihenfolge der Arbeitspakete ist verbindlich.
---
## Zielbild von M14
Nach Abschluss von M14 existiert neben dem bestehenden Shade-JAR ein zweites
Distributionsartefakt: eine **native Windows-EXE**, die alle notwendigen Laufzeitkomponenten
enthält und auf einem frischen Windows 10 (x64) oder Windows Server 2022 (x64) ohne
vorinstalliertes Java oder sonstige Laufzeitumgebungen ausführbar ist.
Die EXE wird ausschließlich **lokal auf der Windows-Entwicklungsmaschine** gebaut,
gesteuert über das Maven-Profil `-P release`. Jenkins bleibt für den normalen
JAR-Build zuständig und ist von M14 nicht betroffen.
---
## Abgrenzungen
### Explizit nicht Bestandteil von M14
- Windows-Installer (MSI, NSIS, Inno Setup o. Ä.) → V3.0
- Code-Signing der EXE → kein kostenfreier Weg für Deutschland verfügbar
- Cross-Compilation für andere Betriebssysteme
- Änderungen an fachlicher Benennungslogik, Statussemantik, Retry-Regeln oder Persistenz
- Änderungen an der GUI oder am headless Batch-Betrieb
- Neue Tests für die EXE (manueller Smoke-Test durch den Entwickler)
- Jenkins-Integration des EXE-Builds
### Unveränderte Leitplanken
- Java 21
- Maven Multi-Module
- Hexagonale Architektur bleibt unberührt
- Das Shade-JAR bleibt das primäre Distributionsartefakt (Änderung in `betrieb.md` erforderlich)
- Der normale Build (`mvn verify`) bleibt unverändert und erfordert kein WiX Toolset
---
## Verbindliche M14-Regeln für alle Arbeitspakete
### 1. Neues Maven-Modul
Das EXE-Packaging wird in einem eigenen Modul `pdf-umbenenner-packaging` gekapselt.
Dieses Modul hat genau eine Abhängigkeit: `pdf-umbenenner-bootstrap`.
### 2. Maven-Profil `release`
Das Profil `release` aktiviert ausschließlich den EXE-Build via `jpackage`.
Der normale Build (`mvn clean verify`) bleibt vom Profil vollständig unberührt.
WiX Toolset wird nur im Profil `release` benötigt.
### 3. Keine Modifikation bestehender Module
Bestehende Module (`domain`, `application`, `adapter-in-cli`, `adapter-in-gui`,
`adapter-out`, `bootstrap`) werden in M14 **nicht** verändert – weder POM noch
Produktions- noch Testcode.
### 4. Batch-Dateien
Die zwei Batch-Dateien landen als Ressourcen im Modul `pdf-umbenenner-packaging`
und werden durch das `jpackage`-Plugin in das EXE-Ausgabeverzeichnis kopiert.
| Dateiname | Funktion |
|---|---|
| `PDF-KI-Renamer.bat` | Headless-Modus (`--headless`) |
| `PDF-KI-Renamer-GUI.bat` | GUI-Modus (kein Argument) |
### 5. Dokumentation
`betrieb.md` wird am Ende von M14 aktualisiert: Der Abschnitt „Keine EXE, kein Installer"
wird durch eine korrekte Beschreibung des V2.5-Distributionsartefakts ersetzt.
---
## AP-001 Neues Maven-Modul `pdf-umbenenner-packaging` anlegen
### Voraussetzung
Kein. Dieses Arbeitspaket ist der M14-Startpunkt.
### Ziel
Die Projektstruktur wird um das Packaging-Modul erweitert, ohne den bestehenden Build zu berühren.
### Muss umgesetzt werden
- Modul `pdf-umbenenner-packaging` anlegen mit minimaler POM-Struktur.
- Modul in Parent-POM (`<modules>`) und Reactor aufnehmen.
- Abhängigkeit auf `pdf-umbenenner-bootstrap` (scope `runtime`) deklarieren.
- Das Modul erzeugt im Normalbuild (`mvn clean verify`) **kein** zusätzliches Artefakt.
- Keine Produktionsklassen, keine Tests – das Modul enthält ausschließlich
Maven-Konfiguration und Ressourcen.
- `package-info.java` entfällt (kein Java-Code im Modul).
### Explizit nicht Teil
- Plugin-Konfiguration für jpackage
- Maven-Profil `release`
- Batch-Dateien
- Icon
### Fertig wenn
- das neue Modul im Reactor vorhanden ist,
- `mvn clean verify` (ohne Profil) weiterhin fehlerfrei durchläuft,
- keine bestehenden Module verändert wurden.
---
## AP-002 Ressourcen bereitstellen (Icon und Batch-Dateien)
### Voraussetzung
AP-001 ist abgeschlossen.
### Ziel
Icon und Batch-Dateien liegen als versionierte Ressourcen im Modul bereit.
### Muss umgesetzt werden
**Icon:**
- Platzhalter-Icon `src/main/packaging/icon.ico` anlegen.
- Das Icon ist ein valides `.ico`-Format (1×1 Pixel genügt als Platzhalter).
- Kommentar in der Datei oder einer begleitenden `README-icon.md`:
„Platzhalter – vor dem Release durch echtes Icon ersetzen."
**Batch-Dateien** unter `src/main/packaging/`:
`PDF-KI-Renamer.bat`:
```bat
@echo off
"%~dp0PDF-KI-Renamer\PDF-KI-Renamer.exe" --headless %*
```
`PDF-KI-Renamer-GUI.bat`:
```bat
@echo off
"%~dp0PDF-KI-Renamer\PDF-KI-Renamer.exe" %*
```
- `%~dp0` stellt sicher, dass die EXE relativ zur Batch-Datei gefunden wird,
unabhängig vom aktuellen Arbeitsverzeichnis.
- `%*` leitet alle weiteren Argumente (z. B. `--config`) durch.
- Pfade mit Leerzeichen (z. B. `C:\Program Files\...`) sind durch die Anführungszeichen korrekt gequotet.
### Explizit nicht Teil
- Plugin-Konfiguration
- Kopieren der Batch-Dateien in das Ausgabeverzeichnis (folgt in AP-003)
### Fertig wenn
- Icon und beide Batch-Dateien unter `src/main/packaging/` vorhanden sind,
- `mvn clean verify` weiterhin fehlerfrei durchläuft.
---
## AP-003 Maven-Profil `release` mit jpackage konfigurieren
### Voraussetzung
AP-002 ist abgeschlossen.
### Ziel
`mvn clean package -P release` erzeugt auf der Windows-Entwicklungsmaschine
(mit WiX Toolset im PATH) eine lauffähige Windows-EXE unter
`pdf-umbenenner-packaging/target/dist/`.
### Technischer Hintergrund
Das Projekt verwendet ein **nicht-modulares Fat-JAR** (Shade-Plugin, kein JPMS).
JavaFX-DLLs sind bereits im Shade-JAR enthalten (Windows-Classifier).
Die Main-Class erweitert bewusst nicht `javafx.application.Application`
(JavaFX-Launcher-Check-Workaround, dokumentiert in `betrieb.md`).
jpackage benötigt:
1. Das Shade-JAR als Eingabe (`--input` + `--main-jar`)
2. Eine minimale JRE (erzeugt via `jlink` oder automatisch durch jpackage)
3. WiX Toolset im PATH (für `--type exe`)
Da das Projekt nicht modular ist, muss jpackage mit `--add-modules ALL-MODULE-PATH`
oder einer expliziten Modulliste arbeiten. Die explizite Modulliste ist
wartungsfreundlicher und wird bevorzugt.
### Muss umgesetzt werden
**Maven-Profil `release`** in der POM von `pdf-umbenenner-packaging`:
```xml
<profile>
<id>release</id>
<build>
<plugins>
<!-- Shade-JAR aus Bootstrap-Modul ins Packaging-Verzeichnis kopieren -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>copy-shade-jar</id>
<phase>package</phase>
<goals><goal>copy-dependencies</goal></goals>
<configuration>
<includeArtifactIds>pdf-umbenenner-bootstrap</includeArtifactIds>
<outputDirectory>${project.build.directory}/jpackage-input</outputDirectory>
<stripVersion>false</stripVersion>
</configuration>
</execution>
</executions>
</plugin>
<!-- jpackage -->
<plugin>
<groupId>org.panteleyev</groupId>
<artifactId>jpackage-maven-plugin</artifactId>
<version>1.6.0</version>
<executions>
<execution>
<id>create-exe</id>
<phase>package</phase>
<goals><goal>jpackage</goal></goals>
<configuration>
<type>EXE</type>
<name>PDF-KI-Renamer</name>
<appVersion>${project.version}</appVersion>
<vendor>gecheckt.de</vendor>
<input>${project.build.directory}/jpackage-input</input>
<mainJar>pdf-umbenenner-bootstrap-${project.version}.jar</mainJar>
<mainClass>de.gecheckt.pdf.umbenenner.bootstrap.PdfUmbenennerApplication</mainClass>
<destination>${project.build.directory}/dist</destination>
<icon>${project.basedir}/src/main/packaging/icon.ico</icon>
<addModules>
java.base,java.desktop,java.logging,java.naming,java.net.http,
java.sql,java.xml,jdk.unsupported
</addModules>
<javaOptions>
<javaOption>-Xms64m</javaOption>
<javaOption>-Xmx512m</javaOption>
</javaOptions>
<winConsole>false</winConsole>
<winShortcut>false</winShortcut>
<winMenu>false</winMenu>
</configuration>
</execution>
</executions>
</plugin>
<!-- Batch-Dateien ins dist-Verzeichnis kopieren -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-batch-files</id>
<phase>package</phase>
<goals><goal>copy-resources</goal></goals>
<configuration>
<outputDirectory>${project.build.directory}/dist</outputDirectory>
<resources>
<resource>
<directory>src/main/packaging</directory>
<includes>
<include>*.bat</include>
</includes>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
```
**Wichtige Hinweise für Claude Code:**
- Die Modulliste (`addModules`) ist ein Ausgangspunkt. Der tatsächliche Bedarf
kann per `jdeps --print-module-deps` auf dem Shade-JAR ermittelt werden.
Claude Code soll `jdeps` ausführen und die Modulliste anpassen.
- `winConsole=false` sorgt dafür, dass kein CMD-Fenster beim GUI-Start erscheint.
Für den headless-Start via Batch ist das akzeptabel (Ausgabe geht in Log-Dateien).
- Die Plugin-Version `1.6.0` von `org.panteleyev:jpackage-maven-plugin` ist
zu verifizieren – aktuelle Version per Maven Central prüfen.
- Das `jpackage`-Plugin muss in `pluginManagement` im Parent-POM oder direkt
in der Packaging-POM versioniert sein.
### Explizit nicht Teil
- Anpassung von `betrieb.md` (folgt in AP-004)
- Manuelle Ausführung oder Smoke-Test
### Fertig wenn
- `mvn clean verify` (ohne Profil) weiterhin fehlerfrei durchläuft,
- die POM-Konfiguration syntaktisch korrekt und vollständig ist,
- `jdeps` auf dem Shade-JAR ausgeführt wurde und die Modulliste korrekt befüllt ist.
---
## AP-004 Dokumentation aktualisieren
### Voraussetzung
AP-003 ist abgeschlossen.
### Ziel
Die Projektdokumentation spiegelt den V2.5-Stand korrekt wider.
### Muss umgesetzt werden
**`betrieb.md` – Abschnitt „Keine EXE, kein Installer" ersetzen durch:**
```markdown
### Windows-EXE (V2.5)
Ab V2.5 steht neben dem Shade-JAR ein zweites Distributionsartefakt bereit:
eine **native Windows-EXE** für Windows 10/11 (x64) und Windows Server 2022 (x64).
Die EXE enthält eine eingebettete JRE 21 und benötigt keine separate Java-Installation
auf dem Zielsystem.
**Voraussetzungen für den EXE-Build (nur auf der Entwicklungsmaschine):**
- Windows x64
- JDK 21 im PATH
- [WiX Toolset 3.x](https://wixtoolset.org/) im PATH
**EXE bauen:**
```powershell
.\mvnw.cmd clean package -P release -pl pdf-umbenenner-packaging --also-make -DskipTests
```
Das Ergebnis liegt unter:
```
pdf-umbenenner-packaging/target/dist/
PDF-KI-Renamer/ ← Anwendungsverzeichnis mit EXE und eingebetteter JRE
PDF-KI-Renamer.bat ← Headless-Start
PDF-KI-Renamer-GUI.bat ← GUI-Start
```
**Hinweis:** Die EXE ist nicht signiert. Beim ersten Start auf einem neuen System
erscheint eine Windows-SmartScreen-Warnung, die durch „Weitere Informationen → Trotzdem ausführen"
bestätigt werden muss.
```
**`betrieb.md` – Abschnitt „Voraussetzungen" aktualisieren:**
- Java 21 ist für Endnutzer der EXE **nicht** mehr erforderlich (eingebettet).
- Hinweis ergänzen: „Bei Verwendung des Shade-JAR direkt: Java 21 JRE erforderlich."
**`CLAUDE.md` aktualisieren** (falls vorhanden):
- Hinweis auf Profil `release` und WiX-Abhängigkeit ergänzen.
- Build-Kommando für EXE dokumentieren.
### Fertig wenn
- `betrieb.md` den neuen Abschnitt enthält,
- die Voraussetzungen korrekt aktualisiert sind,
- `mvn clean verify` weiterhin fehlerfrei durchläuft.
docs/workpackages/M15_-_Arbeitspakete.md
+216
View File
@@ -0,0 +1,216 @@
# M15 - Arbeitspakete
## Geltungsbereich
Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein
**M15 – MSI-Installer (V3.0)**.
Der Stand **V2.5** (M14 abgeschlossen) wird als vollständig umgesetzt vorausgesetzt:
- Modul `pdf-umbenenner-packaging` existiert
- Maven-Profil `release` ist konfiguriert
- `icon.ico`, `PDF-KI-Renamer.bat`, `PDF-KI-Renamer-GUI.bat` liegen unter
`pdf-umbenenner-packaging/src/main/packaging/`
Die Arbeitspakete sind so geschnitten, dass Opus 4.7 sie in einem Durchgang
vollständig umsetzen kann. Nach jedem Arbeitspaket muss `mvn clean verify`
(ohne Profil) fehlerfrei durchlaufen.
---
## Zielbild von M15
Nach Abschluss von M15 erzeugt `mvn clean package -P release` einen vollständigen
**MSI-Installer** (`PDF-KI-Renamer-2.5.0.msi`) der:
- die Anwendung nach `C:\Program Files\PDF KI Renamer\` installiert,
- eine Beispiel-Konfiguration nach
`C:\ProgramData\PDF KI Renamer\config\application.example.properties` ablegt,
- beide Batch-Dateien ins Installationsverzeichnis legt,
- einen Startmenü-Eintrag für den GUI-Start erstellt,
- einen Desktop-Shortcut erstellt,
- über „Programme und Features" sauber deinstallierbar ist.
---
## Abgrenzungen
### Explizit nicht Bestandteil von M15
- Automatische Konfigurationsauflösung aus `ProgramData` (bleibt `--config`-Sache)
- Code-Signing des MSI
- Upgrade-Logik (MajorUpgrade, automatisches Deinstallieren alter Versionen)
- Änderungen an fachlicher Logik, GUI, headless-Betrieb oder Persistenz
- Neue Tests
### Unveränderte Leitplanken
- `--type MSI` ersetzt `--type EXE` im Profil `release`
- Der Normalbuild (`mvn clean verify`) bleibt unverändert
- Bestehende Module außer `pdf-umbenenner-packaging` werden nicht angefasst
---
## Verbindliche M15-Regeln
### 1. Installationsverzeichnis
`C:\Program Files\PDF KI Renamer\`
### 2. Konfigurationsverzeichnis
`C:\ProgramData\PDF KI Renamer\config\`
Die Beispiel-Config wird aus `docs/examples/application.properties` des Projekts
in dieses Verzeichnis kopiert und als `application.example.properties` abgelegt.
### 3. Batch-Dateien
Beide Batch-Dateien landen im Installationsverzeichnis.
Die Pfade in den Batch-Dateien müssen auf das Installationsverzeichnis angepasst werden
(nicht mehr relativ per `%~dp0`, sondern absolut via Installationspfad-Variable oder
weiterhin relativ – beides ist akzeptabel solange es funktioniert).
### 4. Startmenü & Desktop
- Startmenü-Gruppe: `PDF KI Renamer`
- Startmenü-Eintrag: `PDF KI Renamer` → startet GUI
- Desktop-Shortcut: `PDF KI Renamer` → startet GUI
### 5. Deinstallation
Saubere Deinstallation über „Programme und Features". Vom Installer angelegte
Dateien werden entfernt. Nutzerdaten in `ProgramData` (Konfiguration, Logs, DB)
werden **nicht** gelöscht.
---
## AP-001 MSI-Typ und Installer-Ressourcen vorbereiten
### Voraussetzung
M14 ist abgeschlossen. `mvn clean verify` ist grün.
### Ziel
Das Profil `release` erzeugt einen MSI statt einer EXE,
und alle notwendigen Installer-Ressourcen liegen bereit.
### Muss umgesetzt werden
1. In `pdf-umbenenner-packaging/pom.xml` im Profil `release`:
- `<type>EXE</type>` → `<type>MSI</type>`
- Folgende Windows-spezifische jpackage-Optionen ergänzen:
```xml
<winShortcut>true</winShortcut>
<winMenu>true</winMenu>
<winMenuGroup>PDF KI Renamer</winMenuGroup>
<winDirChooser>true</winDirChooser>
<winShortcutPrompt>false</winShortcutPrompt>
<installDir>PDF KI Renamer</installDir>
```
2. Beispiel-Konfiguration als Installer-Ressource bereitstellen:
- `docs/examples/application.properties` nach
`pdf-umbenenner-packaging/src/main/packaging/application.example.properties`
kopieren (als versionierte Kopie im Modul – nicht das Original verschieben).
3. `mvn clean verify` muss weiterhin grün bleiben.
### Fertig wenn
- `<type>MSI</type>` in der POM gesetzt
- Windows-Optionen konfiguriert
- `application.example.properties` unter `src/main/packaging/` vorhanden
- `mvn clean verify` grün
---
## AP-002 ProgramData-Verzeichnis und Beispiel-Config im Installer verankern
### Voraussetzung
AP-001 ist abgeschlossen.
### Ziel
Der MSI-Installer legt beim Installieren die Beispiel-Config unter
`C:\ProgramData\PDF KI Renamer\config\application.example.properties` ab.
### Technischer Hintergrund
jpackage unterstützt `--app-content` zum Hinzufügen zusätzlicher Dateien
in das Anwendungs-Image. Diese landen jedoch im Installationsverzeichnis,
nicht in `ProgramData`.
Für `ProgramData` gibt es zwei Wege:
- **Weg A**: jpackage `--resource-dir` mit WiX-Override (komplex, fehleranfällig)
- **Weg B**: Die Beispiel-Config über `--app-content` ins Installationsverzeichnis
legen und in der Dokumentation beschreiben, dass der Nutzer sie nach
`ProgramData` kopieren soll (einfach, robust)
**Verbindlich für M15: Weg B.**
### Muss umgesetzt werden
1. `application.example.properties` via `--app-content` in das
Anwendungsverzeichnis einbinden:
```xml
<appContent>
<appContent>src/main/packaging/application.example.properties</appContent>
</appContent>
```
2. `mvn clean verify` muss weiterhin grün bleiben.
### Fertig wenn
- `application.example.properties` ist in der jpackage-Konfiguration als
`appContent` eingebunden
- `mvn clean verify` grün
---
## AP-003 Desktop-Shortcut konfigurieren
### Voraussetzung
AP-002 ist abgeschlossen.
### Ziel
Der Installer erstellt zusätzlich einen Desktop-Shortcut.
### Technischer Hintergrund
jpackage unterstützt Desktop-Shortcuts über `--win-shortcut`.
`<winShortcut>true</winShortcut>` ist bereits in AP-001 gesetzt –
das erzeugt jedoch primär einen Startmenü-Eintrag.
Für einen **Desktop**-Shortcut ist ein zusätzlicher WiX-Override nötig.
Prüfe zunächst ob `<winShortcut>true</winShortcut>` in Kombination mit
`<winShortcutPrompt>false</winShortcutPrompt>` bereits einen Desktop-Shortcut erzeugt.
Falls nicht, dokumentiere dies als bekannte Einschränkung in `betrieb.md`
und überspringe den WiX-Override (zu komplex für M15).
### Fertig wenn
- Entweder Desktop-Shortcut funktioniert, oder
- die Einschränkung ist in `betrieb.md` dokumentiert
- `mvn clean verify` grün
---
## AP-004 Dokumentation aktualisieren
### Voraussetzung
AP-001 bis AP-003 sind abgeschlossen.
### Ziel
Die Projektdokumentation spiegelt den V3.0-Stand korrekt wider.
### Muss umgesetzt werden
1. `docs/betrieb.md` – Abschnitt „Windows-EXE (V2.5)" erweitern zu
„Windows-Installer (V3.0)":
- MSI-Build-Kommando dokumentieren
- Installationsverzeichnis dokumentieren
- Hinweis: Beispiel-Config liegt nach Installation im Installationsverzeichnis,
muss manuell nach `C:\ProgramData\PDF KI Renamer\config\` kopiert und
angepasst werden
- Hinweis auf SmartScreen-Warnung (kein Code-Signing)
- Headless-Betrieb: Beispiel-Aufruf mit `--config`
2. `CLAUDE.md` aktualisieren:
- Build-Kommando für MSI ergänzen
### Fertig wenn
- `betrieb.md` vollständig aktualisiert
- `CLAUDE.md` aktualisiert
- `mvn clean verify` grün
- M15 vollständig abgeschlossen