Switch queue to local label templates

README.md

@@ -1,109 +1,143 @@
 # LabelPrintAgent
 
-Windows-Tray-Anwendung für den späteren Etikettendruck aus JSON-Layouts.
+Windows-Tray-Anwendung zum Rendern und Drucken von Etiketten über installierte Windows-Drucker, z. B. einen Dymo LabelWriter.
 
-## Etappe 1
+## Aktueller Stand
 
-Die erste Etappe enthält das lauffähige Grundgerüst:
+Der Agent arbeitet jetzt mit lokalen `LabelTemplates` in `C:\ProgramData\LabelPrintAgent\settings.json`.
 
-- .NET-9-Windows-Forms-Projekt
-- Tray-Icon mit Kontextmenü
-- Einstellungsdialog mit Tabs:
-  - Allgemein
-  - Datenbank
-  - Drucker
-  - Layout
-  - Fehlerhafte Druckaufträge
-- lokale Konfiguration unter `C:\ProgramData\LabelPrintAgent\settings.json`
-- automatische Anlage von `C:\ProgramData\LabelPrintAgent`
-- Layout-Ordner unter `C:\ProgramData\LabelPrintAgent\layouts`
-- Log-Ordner unter `C:\ProgramData\LabelPrintAgent\logs`
-- verschlüsselte Passwortspeicherung per Windows DPAPI
-- Auflistung installierter Windows-Drucker
-- Beispiel-Layout `dymo_57x32_standard`
-- Layout-JSON laden und speichern
+Ein Queue-Job enthält nur noch:
 
-## Etappe 2
+- `barcode_template_id`
+- `payload_json`
 
-Die zweite Etappe ergänzt das Layoutmodell und die JSON-Validierung:
+Die alte Zuordnung über `layout_key` gibt es nicht mehr. Stattdessen gilt:
 
-- typisierte Layoutklassen für Text, Linie, Rechteck und QR-Code
-- JSON-Deserialisierung anhand der Element-Eigenschaft `type`
-- Validierung des Layoutkopfs und aller Elemente
-- Sammlung aller Validierungsfehler statt Abbruch beim ersten Fehler
-- Anzeige der Validierungsfehler im Layout-Tab
-- Speichern nur bei gültigem Layout
-- formatierte Speicherung des Layout-JSON
+```text
+label_print_queue.barcode_template_id
+-> lokales LabelTemplate im LabelPrintAgent
+-> darin enthaltenes Layout rendern
+```
 
-## Etappe 3
+Die Tabelle `barcode_templates` wird nicht verändert. Sie bleibt nur die fachliche Referenz für die `barcode_template_id`.
 
-Die dritte Etappe ergänzt die Rendering-Engine und die Vorschau im Layout-Tab:
+## LabelTemplates
 
-- Bitmap-Rendering mit 300 dpi
-- Text, Linien, Rechtecke und QR-Codes
-- Platzhalterersetzung wie `{titel}`, `{datum:dd.MM.yyyy}` und `{menge:0.00}`
-- automatische Beispiel-Daten für Vorschauen
-- AutoShrink für Textfelder
-- Warnungen, wenn Platzhalter fehlen oder Text nicht vollständig passt
+Ein lokales LabelTemplate enthält:
 
-Eine Vorschau erzeugst du im Tab `Layout` mit dem Button `Vorschau`. Zuerst wird das JSON validiert, dann wird das Etikett mit folgenden Beispiel-Daten gerendert:
+- `barcodeTemplateId`
+- `name`
+- `getNumberUrl`
+- `numberPrintedUrl`
+- `reservedNumberPayloadKey`
+- `qrTemplate`
+- `layout`
+
+Das Layout liegt vollständig eingebettet im Template. Es gibt keine separate Layout-Datei und keinen `layoutKey` mehr.
+
+## Nummernserver
+
+`getNumberUrl` wird per HTTP GET aufgerufen und gibt Plain Text zurück, z. B.:
+
+```text
+123
+```
+
+Der Nummernserver liefert keine führenden Nullen. Die Datenbank speichert `reserved_number` als `BIGINT`, also z. B. `123`.
+
+Führende Nullen entstehen nur über Formatierung im Template:
+
+```text
+{reservedNumber:0000000} -> 0000123
+{nummer:0000000} -> 0000123
+```
+
+Nach erfolgreichem Windows-Druck wird `numberPrintedUrl` aufgerufen. Erst wenn diese Bestätigung erfolgreich war, darf der Job als `printed` markiert werden.
+
+Wenn der Druck erfolgreich war, aber `numberPrintedUrl` fehlschlägt, bleibt `reserved_number` erhalten und der Job geht auf `error`. Beim erneuten Drucken wird dieselbe Nummer wiederverwendet; es wird keine neue Nummer reserviert.
+
+## Payload-Erweiterung
+
+Vor dem Rendern wird `payload_json` erweitert:
+
+- `reservedNumber`
+- der konfigurierte `reservedNumberPayloadKey`, z. B. `nummer`
+- `qr`, wenn `qrTemplate` gesetzt ist
+- `jobId`
+- `barcodeTemplateId`
+
+Beispiel:
 
 ```json
 {
-  "titel": "Beleg privat",
-  "beschreibung": "Dokument 2026-000123",
-  "nummer": "2026-000123",
-  "datum": "2026-05-07",
-  "menge": 42.5,
+  "reservedNumber": 123,
+  "nummer": 123,
   "qr": "bjoernprivat 0000123"
 }
 ```
 
-## Etappe 4
+## Oberfläche
 
-Die vierte Etappe ergänzt den Testdruck über installierte Windows-Drucker:
+Im Einstellungsdialog gibt es den Tab `Label-Templates`.
 
-- Druckerliste mit Standarddrucker-Erkennung
-- Prüfung, ob der konfigurierte Drucker noch vorhanden ist
-- Testdruck im Tab `Drucker`
-- Testdruck im Tab `Layout` direkt aus dem aktuell bearbeiteten JSON
-- Ausgabe des gerenderten Bitmaps über `System.Drawing.Printing.PrintDocument`
-- benutzerdefiniertes Papierformat aus dem Layout, beim Beispiel `57 x 32 mm`
-- keine zusätzlichen Druckränder; der Layout-Rand steckt bereits im gerenderten Bitmap
+Dort kannst du:
 
-Für den Dymo LabelWriter muss der Drucker in Windows bereits als normaler Windows-Drucker eingerichtet sein. Stelle im Dymo-Treiber möglichst ebenfalls das Etikettenformat `57 x 32 mm` bzw. das passende Dymo-Label ein. Die App sendet ein fertiges Bild an den Windows-Drucker; es wird kein ZPL, EPL oder TSPL verwendet.
+- Templates anlegen
+- Templates löschen
+- `barcodeTemplateId` bearbeiten
+- Nummernserver-URLs bearbeiten
+- QR-Template bearbeiten
+- eingebettetes Layout-JSON bearbeiten
+- validieren
+- Vorschau erzeugen
+- Testdruck auslösen
 
-Einen Testdruck machst du so:
+Die Vorschau verwendet eine Dummy-Nummer `123` und reserviert keine Nummer beim Nummernserver.
+
+## Dymo-Testdruck
+
+Für den Dymo LabelWriter muss der Drucker in Windows als normaler Drucker eingerichtet sein. Stelle im Dymo-Treiber möglichst das passende Etikettenformat `57 x 32 mm` ein.
+
+Testdruck:
 
 1. Im Tab `Drucker` den Dymo LabelWriter auswählen.
 2. `Speichern` klicken.
-3. `Testdruck` klicken, um das ausgewählte Beispiel-Layout zu drucken.
-4. Alternativ im Tab `Layout` das JSON bearbeiten und dort `Testdruck` klicken.
+3. Im Tab `Label-Templates` ein Template auswählen.
+4. `Vorschau` prüfen.
+5. `Testdruck` klicken.
 
 Typische Fehler:
 
-- Falscher Drucker gewählt: im Tab `Drucker` den Dymo LabelWriter auswählen.
-- Falsches Etikettenformat im Treiber: im Windows-Druckertreiber `57 x 32 mm` bzw. das passende Label einstellen.
-- Ausdruck zu groß oder zu klein: prüfen, ob Treiber-Skalierung deaktiviert ist und das Layout `57 x 32 mm` verwendet.
-- Etikett wird gedreht: im Dymo-Treiber das physische Label `57 x 32 mm` wählen. Die App setzt das Papierformat bereits quer als `57 x 32 mm` und sendet keine zusätzliche Windows-Landscape-Rotation.
+- Falscher Drucker gewählt.
+- Falsches Etikettenformat im Dymo-Treiber.
+- Treiber skaliert auf A4/Letter.
+- Etikett ist gedreht: Dymo-Treiber-Labelgröße und physische Orientierung prüfen.
 
-Noch nicht enthalten sind MySQL-Worker und automatische Datenbankabfrage.
+## Datenbank
 
-## Startanleitung
-
-1. `LabelPrintAgent.sln` in Visual Studio oder Rider öffnen.
-2. Auf einem Windows-Rechner bauen und starten.
-3. Das Tray-Symbol anklicken oder per Kontextmenü `Einstellungen` öffnen.
-4. Im Tab `Drucker` einen installierten Windows-Drucker auswählen und speichern.
-5. Im Tab `Layout` das Beispiel-Layout prüfen, bearbeiten und speichern.
-6. Im Tab `Layout` oder `Drucker` einen Testdruck auslösen.
-
-Beim ersten Start werden die Programmdatenordner und das Beispiel-Layout automatisch angelegt.
-
-## Spätere Etappen
-
-Die SQL-Datei für die spätere Druckwarteschlange liegt bereits unter:
+Die SQL-Datei liegt unter:
 
 ```text
 sql/create_label_print_queue.sql
 ```
+
+Beispiel-Insert:
+
+```sql
+INSERT INTO label_print_queue
+(barcode_template_id, payload_json, status)
+VALUES
+(
+  1,
+  JSON_OBJECT(
+    'titel', 'Beleg privat',
+    'beschreibung', 'Tankbeleg',
+    'datum', '2026-05-07'
+  ),
+  'pending'
+);
+```
+
+## Noch offen
+
+Der automatische MySQL-Worker ist noch nicht aktiv verdrahtet. Die dafür benötigten Modell-, Repository-, Nummernserver- und Druckprozessor-Klassen sind vorbereitet.