marcus
aaedc2d713
- 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
362 lines
12 KiB
Markdown
362 lines
12 KiB
Markdown
# 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.
|