Der Agent speichert keine Layouts, keine Nummernserver-Regeln und keine MySQL-Queue-Logik mehr. Das Backend entscheidet, welche Etiketten gedruckt werden, rendert bzw. liefert das fertige Etikett als Bild, und der Agent druckt dieses Bild über einen installierten Windows-Drucker.

Ablauf

LabelPrintAgent
-> fragt alle X Sekunden PaperlessManager-Backend
-> erhält druckfertige Etikettenjobs, bis kein Job mehr vorhanden ist
-> lädt/liest das Etikettbild
-> druckt über Windows-Drucker
-> meldet Erfolg oder Fehler ans Backend zurück

Der Agent unterstützt Server-Sent Events für Push-Benachrichtigungen und nutzt Polling als Fallback. Jeder Poll-Lauf ruft so lange /jobs/next auf, bis das Backend 204 No Content zurückgibt.

Backend-Vertrag

Die ausführliche API-Beschreibung liegt in BACKEND_API.md.

Der Agent fragt standardmäßig:

GET /api/label-print-agent/jobs/next?agentId={agentId}
Authorization: Bearer {apiToken}

Wenn nichts zu drucken ist:

204 No Content

Wenn ein Etikett vorhanden ist:

{
  "jobId": "12345",
  "labelImageBase64": "...",
  "labelImageContentType": "image/png",
  "labelWidthMm": 57,
  "labelHeightMm": 32
}

Alternativ darf das Backend statt labelImageBase64 eine URL liefern:

{
  "jobId": "12345",
  "labelImageUrl": "/api/label-print-agent/jobs/12345/image",
  "labelImageContentType": "image/png",
  "labelWidthMm": 57,
  "labelHeightMm": 32
}

Der Agent meldet Erfolg:

POST /api/label-print-agent/jobs/{jobId}/printed
Authorization: Bearer {apiToken}
Content-Type: application/json

{
  "agentId": "PC-BUERO",
  "printerName": "DYMO LabelWriter 450"
}

Der Agent meldet Fehler:

POST /api/label-print-agent/jobs/{jobId}/error
Authorization: Bearer {apiToken}
Content-Type: application/json

{
  "agentId": "PC-BUERO",
  "printerName": "DYMO LabelWriter 450",
  "errorMessage": "Drucker ist nicht verfügbar."
}

Lokale Einstellungen

Die Einstellungen liegen unter:

C:\ProgramData\LabelPrintAgent\settings.json

Beispiel:

{
  "backend": {
    "baseUrl": "https://paperlessmanager.local",
    "agentId": "PC-BUERO",
    "encryptedApiToken": "",
    "nextJobPath": "/api/label-print-agent/jobs/next",
    "imagePath": "/api/label-print-agent/jobs/{jobId}/image",
    "reportSuccessPath": "/api/label-print-agent/jobs/{jobId}/printed",
    "reportErrorPath": "/api/label-print-agent/jobs/{jobId}/error",
    "useServerSentEvents": true,
    "eventsPath": "/api/label-print-agent/events"
  },
  "printer": {
    "printerName": "DYMO LabelWriter 450",
    "labelWidthMm": 57,
    "labelHeightMm": 32,
    "dpi": 300
  },
  "worker": {
    "enabled": true,
    "pollIntervalSeconds": 30
  }
}

Der API-Token wird lokal mit Windows DPAPI verschlüsselt gespeichert.

Dymo-Druck

Der Dymo LabelWriter muss in Windows als normaler Drucker eingerichtet sein. Das Backend liefert ein fertiges Bild für das Etikett, typischerweise PNG in 57 x 32 mm.

Wichtig:

Der Agent verwendet PrintDocument.
Es wird kein ZPL, EPL oder TSPL verwendet.
Das Bild wird auf die komplette Papierfläche gedruckt.
Der Dymo-Treiber sollte auf das passende Etikettenformat eingestellt sein.

Bedienung

Anwendung starten.
Tray-Symbol öffnen.
Im Tab Backend BaseUrl, AgentId und optional API-Token eintragen.
Im Tab Drucker den Dymo LabelWriter auswählen.
Im Tab Allgemein Polling aktivieren und Intervall setzen.
Mit Jetzt prüfen kann sofort ein Poll-Lauf ausgelöst werden; dabei werden alle aktuell verfügbaren Jobs verarbeitet.

Tray-Status

Das Tray-Icon zeigt den aktuellen Zustand:

Grün: Worker ist aktiviert, Backend-Konfiguration ist vollständig, Drucker ist verfügbar und der letzte Backend-Kontakt war erfolgreich.
Rot: Konfiguration fehlt, Drucker ist nicht verfügbar, Worker ist deaktiviert oder der Backend-Kontakt ist fehlgeschlagen.

Logs und 401-Fehler

Logs liegen standardmäßig unter:

C:\ProgramData\LabelPrintAgent\logs\label-print-agent-YYYYMMDD.log

Bei HTTP-Fehlern wie 401 Unauthorized protokolliert der Agent:

HTTP-Methode und URL
Statuscode und Reason Phrase
ob ein Authorization-Header gesetzt wurde
Authorization-Scheme, z. B. Bearer
Token-Länge, aber niemals den Token selbst
kurzer SHA-256-Fingerprint des Tokens zum Abgleich mit dem Backend
WWW-Authenticate-Header des Backends
gekürzten Response-Body des Backends

Beim Speichern wird der API-Token normalisiert. Falls versehentlich Bearer ... oder Authorization: Bearer ... eingefügt wurde, speichert der Agent nur den eigentlichen Tokenwert.

Nicht mehr im Agent

keine Layout-JSON-Verwaltung
keine lokalen LabelTemplates
keine MySQL-Verbindung
keine Nummernserver-URLs
keine Nummernreservierung im Agent

Diese Verantwortung liegt vollständig im PaperlessManager-Backend.