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