Etiketten & Drucker

Der Etikettendruck wird nicht in der Oberfläche eingerichtet. Er ist eine optionale Betriebsfunktion der Anwendung. Die Konfiguration erfolgt über eine Umgebungsvariable und gilt nach dem nächsten Start des werkspur-Prozesses.

Wann gedruckt wird

WERKSPUR erzeugt einen Druckauftrag für jedes Ereignis LotCreated, das der Etiketten-Consumer aus dem Nachrichtenbus erhält. Dazu gehören neu angelegte Lose sowie neue Kind-Lose, die bei Teilung, Zusammenführung, Transformation oder Teilmengenentnahme entstehen.

Der Druck läuft nach der Losbuchung über den Nachrichtenbus. Die Buchung wartet nicht auf den Drucker. Ein nicht erreichbarer Drucker kann deshalb die Anlage oder Verarbeitung eines Loses nicht zurückrollen.

Das Etikett enthält die Los-ID als QR-Code. Der QR-Inhalt ist genau die technische Los-ID, die auch das Scan-Terminal erwartet. Zusätzlich druckt die Vorlage Auftrag, Menge, Einheit und den aktuellen Schritt in lesbarer Form.

TCP auf Port 9100

Setzen Sie FOUNDRY_LABEL_PRINTER_ADDR auf die vom Anwendungscontainer erreichbare Adresse im Format host:port. Für einen Zebra-kompatiblen Netzwerkdrucker ist Port 9100 üblich:

FOUNDRY_LABEL_PRINTER_ADDR=etikettendrucker.example:9100

Die Anwendung öffnet für jeden Druckauftrag eine rohe TCP-Verbindung und schreibt den ZPL-Text direkt. Sie verwendet weder IPP noch einen Betriebssystem-Spooler. Die Verbindung besitzt keine eigene TLS- oder Drucker-Authentifizierung. Begrenzen Sie Port 9100 deshalb im Netzwerk auf die erforderlichen Quelladressen.

Die Konfiguration wird beim Start gelesen. Starten Sie nach einer Änderung den Anwendungsdienst neu:

docker compose -f deploy/docker-compose.yml up -d werkspur

Im mitgelieferten Stand enthält deploy/.env.example die Variable, deploy/docker-compose.yml reicht sie aber noch nicht an den werkspur-Container weiter. Ergänzen Sie dort im Abschnitt werkspur.environment die Zuordnung:

FOUNDRY_LABEL_PRINTER_ADDR: ${FOUNDRY_LABEL_PRINTER_ADDR:-}

Erst danach übernimmt der Compose-Stack den Wert aus deploy/.env. Bei einem direkt gestarteten Prozess genügt die Variable in dessen Umgebung.

ZPL-Vorlage

Die fest eingebaute Vorlage verwendet ZPL für ein Etikett von ungefähr 76 × 51 mm bei 203 dpi. Der QR-Code verwendet Fehlerkorrekturstufe Q. Die menschenlesbare Los-ID wird in zwei Hälften dargestellt, wenn sie dem 26-stelligen ULID-Format entspricht.

Auftrag, Einheit und Los-ID werden vor dem Einsetzen bereinigt. ZPL-Steuerzeichen und Zeilenumbrüche aus diesen Feldern können dadurch keine zusätzlichen Druckerbefehle einschleusen.

Für die Vorlage gibt es derzeit weder einen Editor in der Oberfläche noch eine Konfigurations-API. Abmessungen, Positionen und Felder sind Teil der Anwendung. Abweichende Etikettenformate erfordern eine Änderung und erneute Bereitstellung des Dienstes.

Deaktivierter Druck

Ein leerer Wert für FOUNDRY_LABEL_PRINTER_ADDR deaktiviert den Etiketten-Consumer. Auch ohne NATS-Verbindung startet kein Druck. Alle übrigen Losfunktionen bleiben verfügbar.

Das Deaktivieren sammelt keine später nachzudruckende Warteschlange innerhalb des Etiketten-Consumers. Ereignisse können weiterhin im Nachrichtenbus vorhanden sein, doch der aktuelle Dienst bietet keine Zusage, dass während einer absichtlich deaktivierten Phase später automatisch genau ein Etikett je Los ausgegeben wird. Planen Sie die Aktivierung deshalb vor dem produktiven Anlegen neuer Lose.

Fehler

Der Verbindungsaufbau zum Drucker läuft höchstens fünf Sekunden. Der gesamte Druckversuch erhält ein Zeitfenster von 15 Sekunden. Schlägt Verbindungsaufbau oder Schreiben fehl, protokolliert die Anwendung labels: print failed mit der Los-ID und bestätigt das Nachrichtenbus-Ereignis trotzdem.

Dieses Verhalten blockiert die Ereignisverarbeitung nicht, bedeutet aber auch: Ein fehlgeschlagener Druck wird nicht automatisch wiederholt. Die aktuelle Oberfläche und API bieten keinen erneuten Druck. Organisieren Sie den Ersatzdruck deshalb als betrieblichen Ausnahmeprozess. Verwenden Sie dabei die ursprüngliche Los-ID; erzeugen Sie nicht allein für ein Etikett ein zusätzliches Los.

Ein erfolgreicher Auftrag erscheint im Log als label printed. Das bestätigt, dass die Anwendung den ZPL-Text ohne Schreibfehler an die TCP-Verbindung übergeben hat. Es bestätigt nicht, dass Papier eingelegt war, das Etikett mechanisch ausgegeben wurde oder der QR-Code lesbar ist.

Test und Betrieb

Prüfen Sie die Einrichtung in drei Stufen:

1. Testen Sie vom Servernetz aus, ob die Druckeradresse auf Port 9100 erreichbar ist. Beachten Sie, dass die Verbindung aus dem Docker-Netz ebenfalls erlaubt sein muss.
2. Senden Sie mit einem vom Druckerhersteller freigegebenen Werkzeug ein minimales ZPL-Testetikett. Damit trennen Sie Netzwerk- und Druckerkonfiguration von WERKSPUR.
3. Legen Sie in WERKSPUR ein freigegebenes Testlos an. Vergleichen Sie die gedruckte Los-ID mit der Losseite und scannen Sie den QR-Code am „Scan-Terminal“ zurück.

Beobachten Sie während des Tests die Logs:

docker compose -f deploy/docker-compose.yml logs -f werkspur

Dokumentieren Sie Druckeradresse, Etikettenmaterial, Auflösung und den manuellen Ersatzdruck. Richten Sie eine Log-Überwachung für labels: print failed ein. /readyz prüft Datenbank und Nachrichtenbus, aber nicht die Erreichbarkeit des Etikettendruckers. Ein grüner Readiness-Status ersetzt deshalb keinen regelmäßigen physischen Test.

Wie das Los nach dem Druck gescannt und gebucht wird, zeigt Der Shopfloor-Prozess. Die Bedeutung der Los-ID und ihrer Ereignisse erklärt Rückverfolgbarkeit & Genealogie.