marcus/pdf-umbenenner
1
0
Fork 0
Code Activity

M8 Abschlussdokumentation und Betriebsdoku final geschärft

Browse Source
This commit is contained in:
Marcus van Elst
2026-04-08 17:09:53 +02:00
parent d61316c699
commit 03689802dd
26 changed files with 75 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/befundliste.md
View File

@@ -1,6 +1,7 @@
# Befundliste – Integrierte Gesamtprüfung des Endstands
# Befundliste – Integrierte Gesamtprüfung und Freigabe des Endstands
**Erstellt:** 2026-04-08
**Aktualisiert:** 2026-04-08 (Naming-Convention-Bereinigung B1 abgeschlossen, finale Freigabe)
**Grundlage:** Vollständiger Maven-Reactor-Build, Unit-Tests, E2E-Tests, Integrationstests (Smoke),
PIT-Mutationsanalyse, Code-Review gegen verbindliche Spezifikationen (technik-und-architektur.md,
fachliche-anforderungen.md, CLAUDE.md)
@@ -20,7 +21,7 @@ fachliche-anforderungen.md, CLAUDE.md)
| Hexagonale Architektur – Port-Verträge (kein Path/NIO/JDBC) | ja | GRÜN |
| Hexagonale Architektur – keine Adapter-zu-Adapter-Abhängigkeiten | ja | GRÜN |
| Statusmodell (8 Werte, Semantik laut CLAUDE.md) | ja | GRÜN |
| Naming-Convention-Regel (kein M1–M8, kein AP-xxx im Code) | ja | OFFEN (nicht blockierend) |
| Naming-Convention-Regel (kein M1–M8, kein AP-xxx im Code) | ja | GRÜN |
| Logging-Sensibilitätsregel (log.ai.sensitive) | ja | GRÜN |
| Exit-Code-Semantik (0 / 1) | ja | GRÜN |
| Konfigurationsbeispiele (Pflicht- und Optionalparameter) | ja | GRÜN |
@@ -111,55 +112,22 @@ Alle geforderten Kernszenarien aus der E2E-Testbasis sind abgedeckt und grün:
---
## Offene Punkte
## Abgeschlossene Punkte
### Nicht blockierend
#### B1 – Naming-Convention-Verletzungen in Code, Tests und Konfiguration (CLAUDE.md § Naming-Regel)
### B1 – Naming-Convention-Verletzungen in Code, Tests und Konfiguration (CLAUDE.md § Naming-Regel)
**Themenbereich:** Dokumentation / Codequalität
**Norm:** CLAUDE.md verbietet explizit Meilenstein- (M1–M8) und Arbeitspaket-Bezeichner (AP-xxx)
in Implementierungen, Kommentaren und JavaDoc.
**Befund:** 43 Treffer in `.java`-Dateien (21 in Produktionscode, 22 in Testcode) sowie
1 Treffer in `config/application.properties`.
Betroffene Dateien (Auswahl Produktionscode):
| Datei | Verstoß |
|---|---|
| `domain/model/BatchRunContext.java` | `@since M2-AP-003` |
| `domain/model/DocumentFingerprint.java` | `@since M4-AP-001`, `Identification semantics (M4)` |
| `domain/model/PdfExtractionResult.java` | `@since M3-AP-001` |
| `domain/model/SourceDocumentCandidate.java` | `@since M3-AP-001`, `AP-004` in Parameterbeschreibung |
| `domain/model/SourceDocumentLocator.java` | `@since M3-AP-001` |
| `adapter/out/lock/FilesystemRunLockPortAdapter.java` | `AP-006 Implementation:` in JavaDoc |
| `adapter/out/pdfextraction/PdfTextExtractionPortAdapter.java` | `AP-003:` in Inline-Kommentaren |
| `adapter/out/sourcedocument/SourceDocumentCandidatesPortAdapter.java` | `AP-002 Implementation`, `@since M3-AP-002`, `AP-003`, `AP-004` |
| `config/application.properties` | Kommentarheader `# PDF Umbenenner Configuration for AP-006 Testing` |
Betroffene Dateien (Auswahl Testcode):
| Datei | Verstoß |
|---|---|
| `adapter/out/bootstrap/validation/StartConfigurationValidatorTest.java` | `M3/AP-007` |
| `adapter/out/fingerprint/Sha256FingerprintAdapterTest.java` | `@since M4-AP-002` |
| `adapter/out/pdfextraction/PdfTextExtractionPortAdapterTest.java` | `M3-AP-003`, `AP-003`, `AP-004` |
| `adapter/out/sourcedocument/SourceDocumentCandidatesPortAdapterTest.java` | `M3-AP-002`, `AP-004` |
| `adapter/out/sqlite/SqliteUnitOfWorkAdapterTest.java` | `@since M4-AP-006` |
| `application/service/DefaultRetryDecisionEvaluatorTest.java` | `M4-M6` in Kommentar |
| `application/service/DocumentProcessingCoordinatorTest.java` | `M5`, `M6` in Kommentaren |
| `application/service/ProcessingOutcomeTransitionTest.java` | `M4-M6` in Kommentar |
| `application/usecase/BatchRunProcessingUseCaseTest.java` | `M7` in Kommentar |
| `bootstrap/ExecutableJarSmokeTestIT.java` | `AP-008`, `M1` in JavaDoc |
**Bewertung:** Rein kosmetisch/dokumentarisch. Kein Einfluss auf Funktionalität, Build
oder Testergebnis. Betrifft ausschließlich Kommentare und JavaDoc-Annotationen.
**Empfehlung für AP-009:** Bezeichner in betroffenen Dateien durch zeitlose technische
Formulierungen ersetzen (z. B. `@since M4-AP-001` → entfernen oder in neutrales
`@since 1.0` umwandeln; Inline-Kommentare sachlich formulieren).
**Status:** **BEHOBEN** – alle 43 Treffer in `.java`-Dateien sowie der Kommentarheader in
`config/application.properties` wurden durch zeitlose technische Formulierungen ersetzt.
---
## Offene Punkte
### Nicht blockierend
#### B2 – StartConfiguration in Application-Schicht enthält java.nio.file.Path (Architektur-Grenzfall)
**Themenbereich:** Architektur
@@ -175,9 +143,8 @@ Die Port-Verträge selbst sind sauber (keine Path-Typen in Port-Interfaces).
**Bewertung:** Grenzfall. `Path` ist kein fachliches Objekt, aber auch kein schwerer
Architekturverstoß in diesem Kontext. Die Alternative (String-Repräsentation und Auflösung
im Adapter) hätte keinen Mehrwert für das Betriebsmodell.
**Empfehlung für AP-009:** Auf Wunsch im Rahmen von AP-009 prüfen, ob das Verschieben von
`StartConfiguration` in das Bootstrap-Modul sinnvoller wäre. Keine Pflicht, da kein
funktionaler Defekt vorliegt.
**Entscheidung:** Kein Handlungsbedarf. Das Verschieben von `StartConfiguration` in das
Bootstrap-Modul wäre eine Option, ist aber keine Pflicht, da kein funktionaler Defekt vorliegt.
---
@@ -188,22 +155,23 @@ funktionaler Defekt vorliegt.
Hauptkategorie: `VoidMethodCallMutator` (2 Überlebende, 2 ohne Coverage).
**Bewertung:** Betrifft vor allem Logging-Calls und nicht-kritische Hilfsmethoden.
Keine funktional tragenden Entscheidungspfade betroffen.
**Empfehlung:** Kein AP-009-Handlungsbedarf; wurde bereits in AP-007 auf akzeptablem
Niveau konsolidiert.
**Entscheidung:** Kein Handlungsbedarf. Betrifft vor allem Logging-Calls und nicht-kritische
Hilfsmethoden. Wurde auf akzeptablem Niveau konsolidiert.
---
## Zusammenfassung
## Zusammenfassung und Freigabe
| Klassifikation | Anzahl | Beschreibung |
|---|---|---|
| Release-Blocker | **0** | – |
| Nicht blockierend | **3** | B1 Naming, B2 Path-Grenzfall, B3 PIT-Bootstrap |
| Abgeschlossen (war nicht blockierend) | **1** | B1 Naming-Convention-Bereinigung |
| Nicht blockierend, kein Handlungsbedarf | **2** | B2 Path-Grenzfall, B3 PIT-Bootstrap |
**Der Endstand ist produktionsbereit.** Alle fachlichen, technischen und architekturellen
Kernanforderungen sind umgesetzt und durch automatisierte Tests abgesichert. Der Maven-Build
ist fehlerfrei. Die identifizierten offenen Punkte sind ausschließlich nicht blockierend.
**Freigabeentscheidung: Der Endstand ist produktionsbereit und freigegeben.**
Falls AP-009 durchgeführt wird, sollte der Fokus auf **B1** (Naming-Convention-Bereinigung)
liegen, da dieser Punkt die einzige verbindliche CLAUDE.md-Regel betrifft, die noch nicht
vollständig eingehalten wird.
Alle fachlichen, technischen und architekturellen Kernanforderungen aus den verbindlichen
Spezifikationen (technik-und-architektur.md, fachliche-anforderungen.md, CLAUDE.md) sind
vollständig umgesetzt und durch automatisierte Tests abgesichert. Der Maven-Build ist fehlerfrei.
Die CLAUDE.md-Naming-Convention-Regel (kein M1–M8, kein AP-xxx im Produktions- oder Testcode)
ist vollständig eingehalten. Keine bekannten spezifikationsrelevanten Blocker sind offen.

29
docs/betrieb.md
View File

@@ -35,8 +35,13 @@ Empfohlene Startsequenz für den Windows Task Scheduler:
1. Aktion: Programm/Skript starten
2. Programm: `java`
3. Argumente: `-jar pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar`
4. Starten in: Verzeichnis mit `config/application.properties` und `config/prompts/`
3. Argumente: `-jar C:\Pfad\zur\Installation\pdf-umbenenner-bootstrap\target\pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar`
4. Starten in: `C:\Pfad\zur\Installation` (muss das Verzeichnis mit `config\application.properties` und `config\prompts\` enthalten)
> **Hinweis:** Das „Starten in"-Verzeichnis ist das Arbeitsverzeichnis der Anwendung.
> Die Konfigurationsdatei `config/application.properties` sowie das Prompt-Verzeichnis
> `config/prompts/` müssen relativ zu diesem Verzeichnis erreichbar sein. Der JAR-Pfad
> in den Argumenten muss absolut oder relativ zum Starten-in-Verzeichnis korrekt angegeben sein.
---
@@ -126,13 +131,21 @@ Das Suffix zählt nicht zu den 20 Zeichen des Basistitels.
### Dokumentstatus
| Status | Bedeutung |
|---------------------------|-----------|
| `SUCCESS` | Erfolgreich verarbeitet und kopiert |
| `FAILED_RETRYABLE` | Fehlgeschlagen, erneuter Versuch in späterem Lauf möglich |
| `FAILED_FINAL` | Terminal fehlgeschlagen, wird nicht erneut verarbeitet |
Die folgende Tabelle beschreibt das vollständige Statusmodell, das in der SQLite-Datenbank
gespeichert wird.
| Status | Bedeutung |
|-----------------------------|-----------|
| `READY_FOR_AI` | Verarbeitbar, KI-Pfad noch nicht durchlaufen |
| `PROPOSAL_READY` | KI-Benennungsvorschlag liegt vor, Zielkopie noch nicht geschrieben |
| `SUCCESS` | Erfolgreich verarbeitet und kopiert (terminaler Endzustand) |
| `FAILED_RETRYABLE` | Fehlgeschlagen, erneuter Versuch in späterem Lauf möglich |
| `FAILED_FINAL` | Terminal fehlgeschlagen, wird nicht erneut verarbeitet |
| `SKIPPED_ALREADY_PROCESSED` | Übersprungen – Dokument bereits erfolgreich verarbeitet |
| `SKIPPED_FINAL_FAILURE` | Übersprungen – Dokument terminal fehlgeschlagen |
| `SKIPPED_FINAL_FAILURE` | Übersprungen – Dokument terminal fehlgeschlagen |
`PROCESSING` ist ein transienter Zwischenstatus während eines laufenden Verarbeitungsversuchs
und wird nicht als dauerhafter Endstatus gespeichert.
### Retry-Regeln