pdf-umbenenner/docs/workpackages/M14_-_Arbeitspakete.md

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:

@echo off
"%~dp0PDF-KI-Renamer\PDF-KI-Renamer.exe" --headless %*

PDF-KI-Renamer-GUI.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:

<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:

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