121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# 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
|