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

- 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
2026-04-21 16:11:10 +02:00
parent ada7e203e3
commit aaedc2d713
11 changed files with 961 additions and 6 deletions
@@ -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