Titellänge nun parametrisierbar
This commit is contained in:
@@ -0,0 +1,120 @@
|
||||
# V2.6 – Titellänge parametrisierbar machen
|
||||
|
||||
**Status:** Entwurf
|
||||
**Erstellt:** 2026-04-22
|
||||
**Autor:** Marcus (mit Claude als Mentor)
|
||||
|
||||
---
|
||||
|
||||
## Ziel
|
||||
|
||||
Der maximale Basistitel für KI-generierte PDF-Namen wird nicht mehr hardcodiert,
|
||||
sondern ist über die Konfigurationsdatei steuerbar. Alle bisherigen Magic Numbers
|
||||
(20 und 60 Zeichen) werden durch den konfigurierten Wert ersetzt.
|
||||
|
||||
---
|
||||
|
||||
## Hintergrund
|
||||
|
||||
### Bisheriger Zustand
|
||||
- Titellänge war mit 20 Zeichen im Prompt und 60 Zeichen in der Validierung hardcodiert
|
||||
- Kein zentraler Konfigurationsparameter, Werte über ~20 Dateien verstreut
|
||||
- 60-Zeichen-Limit wurde im Rahmen des Produkttests als pragmatischer Zwischenwert eingeführt
|
||||
|
||||
### Motivation
|
||||
- Verschiedene Einsatzszenarien erfordern unterschiedliche Titellängen
|
||||
- Dateinamenlimits je nach Zielsystem unterschiedlich (siehe Recherche unten)
|
||||
|
||||
### Recherchierte Dateinamenlimits (nur Dateiname, ohne Pfad)
|
||||
|
||||
| System | Limit |
|
||||
|---|---|
|
||||
| Windows 10 / Windows Server 2022 (NTFS) | 255 Zeichen |
|
||||
| Synology NAS – Btrfs (unverschlüsselt) | 255 Zeichen |
|
||||
| Synology NAS – Btrfs (verschlüsselt) | ~143 Zeichen |
|
||||
|
||||
**Hinweis:** Der generierte Dateiname hat das Format `YYYY-MM-DD - <Titel>.pdf`,
|
||||
was bereits 18 Zeichen Overhead bedeutet (Datum + Trennzeichen + Dateiendung).
|
||||
Das sicherste Maximum für verschlüsselte Synology-Volumes ist daher **120 Zeichen**
|
||||
für den Basistitel (143 − 18 = 125, mit Puffer auf 120 gerundet).
|
||||
|
||||
---
|
||||
|
||||
## Fachliche Anforderungen
|
||||
|
||||
### Neuer Konfigurationsparameter
|
||||
|
||||
- **Name:** `ai.title.max.length` (finale Benennung obliegt der Implementierung)
|
||||
- **Typ:** positive Ganzzahl
|
||||
- **Defaultwert:** `60` (bisheriger Wert bleibt erhalten, kein Breaking Change)
|
||||
- **Speicherort:** `.properties`-Konfigurationsdatei
|
||||
|
||||
---
|
||||
|
||||
### Validierungsregeln
|
||||
|
||||
| Wert | Typ | Verhalten |
|
||||
|---|---|---|
|
||||
| Kein Wert / leer | Fehler | Pflichtfeld, Start wird abgebrochen |
|
||||
| Keine Ganzzahl (z. B. „abc", „1.5") | Fehler | Ungültiger Typ, Start wird abgebrochen |
|
||||
| < 1 | Fehler | Wert muss positiv sein, Start wird abgebrochen |
|
||||
| 1–9 | Fehler | Minimum ist 10 Zeichen, Start wird abgebrochen |
|
||||
| 10–19 | Warnung | „Titellänge unter 20 Zeichen ist für die meisten Dokumente nicht empfohlen" |
|
||||
| 20–99 | OK | Normaler Betrieb, keine Meldung |
|
||||
| 100–120 | Warnung | „Hohe Titellänge – Dateiname wird sehr lang, Kompatibilität mit verschlüsselten Volumes prüfen" |
|
||||
| > 120 | Fehler | Überschreitet sicheres Limit für verschlüsselte Synology-Volumes, Start wird abgebrochen |
|
||||
|
||||
---
|
||||
|
||||
### GUI – Konfigurationseditor
|
||||
|
||||
- Neues Texteingabefeld im Bereich **„Verarbeitungslimits"**
|
||||
- Beschriftung: **„Max. Titellänge (Zeichen)"**
|
||||
- Validierung erfolgt beim Speichern – ungültige Werte werden **nicht** gespeichert
|
||||
- Warnungen und Fehlermeldungen erscheinen im **Meldungsbereich** (unten in der GUI)
|
||||
- Warnungen blockieren das Speichern **nicht**, Fehler hingegen schon
|
||||
|
||||
---
|
||||
|
||||
### Verarbeitung / Backend
|
||||
|
||||
- Alle hardcodierten `20`- und `60`-Zeichen-Limits werden durch den konfigurierten Wert ersetzt
|
||||
- **Keine Magic Numbers** mehr im Produktionscode
|
||||
- Der Wert wird beim Start geladen, validiert und an alle betroffenen Komponenten weitergereicht
|
||||
- Betroffen sind mindestens:
|
||||
- `AiResponseValidator`
|
||||
- `TargetFilenameBuildingService`
|
||||
- Prompt-Template (Hinweistext an die KI)
|
||||
- JavaDoc aller betroffenen Klassen
|
||||
|
||||
---
|
||||
|
||||
### Prompt-Template
|
||||
|
||||
- Der Hinweis auf die Zeichenbegrenzung im Prompt-Template (`config/prompts/template.txt`)
|
||||
wird ebenfalls dynamisch mit dem konfigurierten Wert befüllt
|
||||
- **Hinweis:** Das Prompt-Template liegt außerhalb des JARs und wird zur Laufzeit gelesen.
|
||||
Die Implementierung muss sicherstellen, dass der konfigurierte Wert zur Laufzeit
|
||||
in den Prompt eingesetzt wird (z. B. per Platzhalter-Ersetzung).
|
||||
|
||||
---
|
||||
|
||||
## Nicht in V2.6 enthalten
|
||||
|
||||
- Automatisches Kürzen von zu langen KI-Titeln
|
||||
- Pfadlängen-Validierung (Gesamtpfad inkl. Ordner)
|
||||
- Unterschiedliche Limits je nach Zielsystem (nur ein globaler Wert)
|
||||
|
||||
---
|
||||
|
||||
## Abnahmekriterien
|
||||
|
||||
- [ ] Neuer Parameter ist in der `.properties`-Datei konfigurierbar
|
||||
- [ ] Defaultwert 60 ist abwärtskompatibel (bestehende Configs ohne den Parameter funktionieren)
|
||||
- [ ] Alle Validierungsregeln greifen korrekt (Fehler blockieren Start/Speichern, Warnungen nicht)
|
||||
- [ ] GUI zeigt das neue Feld im richtigen Bereich
|
||||
- [ ] Meldungsbereich zeigt passende Warn- und Fehlertexte
|
||||
- [ ] Keine hardcodierten 20- oder 60-Zeichen-Limits mehr im Produktionscode
|
||||
- [ ] Prompt-Template enthält den konfigurierten Wert zur Laufzeit
|
||||
- [ ] Alle bestehenden Tests werden angepasst
|
||||
- [ ] `mvn clean verify` ist grün
|
||||
@@ -66,7 +66,7 @@ Fallback auf aktuelles Datum ist erlaubt, wenn kein belastbares Datum eindeutig
|
||||
|
||||
### 4.3 Titel
|
||||
|
||||
- maximal **20 Zeichen (Basistitel)**
|
||||
- maximal **konfigurierbare Anzahl Zeichen (Basistitel, Default 60, gültiger Bereich 10..120)**
|
||||
- verständlich und eindeutig
|
||||
- keine Sonderzeichen außer Leerzeichen
|
||||
|
||||
@@ -87,7 +87,7 @@ Bei Namenskonflikten:
|
||||
|
||||
Regel:
|
||||
|
||||
- 20 Zeichen gelten nur für den Basistitel
|
||||
- die konfigurierte maximale Titellänge gilt nur für den Basistitel
|
||||
- Suffix wird zusätzlich ergänzt
|
||||
|
||||
---
|
||||
@@ -192,7 +192,7 @@ Ein Ergebnis ist korrekt, wenn:
|
||||
|
||||
- Format stimmt
|
||||
- Datum korrekt ist
|
||||
- Titel max. 20 Zeichen hat
|
||||
- Titel die konfigurierte maximale Länge einhält
|
||||
- Dubletten korrekt behandelt wurden
|
||||
- Begründung vorhanden ist
|
||||
- Ergebnis reproduzierbar ist
|
||||
|
||||
@@ -55,8 +55,8 @@ YYYY-MM-DD - Titel(2).pdf
|
||||
```
|
||||
|
||||
Dabei gilt:
|
||||
- die **20 Zeichen** beziehen sich nur auf den **Basistitel**
|
||||
- das Dubletten-Suffix zählt **nicht** zu diesen 20 Zeichen
|
||||
- die **konfigurierte maximale Titellänge** bezieht sich nur auf den **Basistitel**
|
||||
- das Dubletten-Suffix zählt **nicht** zur konfigurierten Titellänge
|
||||
- die Quelldatei wird **nie** überschrieben oder verändert
|
||||
|
||||
---
|
||||
@@ -290,7 +290,7 @@ Der Titel muss technisch diese Regeln erfüllen:
|
||||
- Deutsch
|
||||
- verständlich
|
||||
- eindeutig genug für den Dokumentkontext
|
||||
- maximal **20 Zeichen** als Basistitel
|
||||
- maximal die **konfigurierte Titellänge** als Basistitel (Default 60, gültiger Bereich 10..120)
|
||||
- keine unzulässigen Windows-Dateinamenzeichen
|
||||
- keine generischen Platzhalter wie z. B. `Dokument`, `Datei`, `Scan`, `PDF`
|
||||
- Eigennamen bleiben unverändert
|
||||
@@ -532,6 +532,7 @@ Verbindlich zweckmäßige Parameter:
|
||||
- `max.retries.transient`
|
||||
- `max.pages`
|
||||
- `max.text.characters`
|
||||
- `max.title.length`
|
||||
- `prompt.template.file`
|
||||
|
||||
Pro unterstützter Provider-Familie existiert ein eigener Parameter-Namensraum mit zweckmäßig mindestens:
|
||||
|
||||
Reference in New Issue
Block a user