🏷️ ZPL Label Designer Pro (Desktop & Web Server)

Zaawansowany system do projektowania, podglądu na żywo i masowego drukowania etykiet w standardzie Zebra ZPL-II. Aplikacja dostępna jest w dwóch wersjach:

1. 🖥️ Wersja Desktop (PySide6 / Qt6) – natywna aplikacja okienkowa dla systemów Windows i Linux.
2. 🌐 Wersja Web (WEBFORK/) – serwer aplikacji webowej (FastAPI + HTML5/JS) ze wsparciem dla autostartu na Alpine Linux (OpenRC), Linux / Raspberry Pi oraz Dockerze.

---

📑 Spis Treści

• Główne Możliwości Systemu
• Struktura Projektu
• Wersja Desktop (PySide6)
  • Instalacja i Uruchomienie
• Wersja Web Server (WEBFORK)
  • Uruchomienie Lokalne (Windows / Linux)
  • Autostart na Alpine Linux (OpenRC)
  • Uruchomienie w Kontenerze Docker
• Kluczowe Moduły i Funkcje
  • Projektant Wizualny WYSIWYG & Wyrównanie Tekstu
  • Silnik Drukarek (RAW TCP/IP & USB RAW)
  • Import Danych (Excel / CSV) i Druk Masowy
  • Menedżer Rozmiarów Etykiet
• Testy Jednostkowe i Integracyjne

---

🌟 Główne Możliwości Systemu

• 🎨 Edytor Wizualny WYSIWYG & Kod ZPL:

  • Płótno z uchwytami do przesuwania, skalowania, rotacji i przyciągania do siatki (Snap-to-Grid).
  • Pełna obsługa wyrównania tekstu wewnątrz pola (^FB): na środku pola (Center - C), do lewej krawędzi (Left - L), do prawej krawędzi (Right - R) oraz wyjustowanie (Justify - J).
  • Kody 1D: Code 128, EAN-13, Code 39, EAN-8.
  • Kody 2D: QR Code, DataMatrix, PDF417.
  • Ramki, linie poziome/pionowe (^GB) oraz wbudowany konwerter grafik do komend ZPL ^GF.
  • Wymuszenie kodowania UTF-8 (^CI28) z pełną obsługą polskich znaków (ą, ć, ę, ł, ń, ó, ś, ź, ż).
  • Historia operacji: Cofnij / Ponów (Ctrl+Z, Ctrl+Y), kopiowanie i wklejanie elementów.

• ⚡ Lokalny Silnik Rasteryzacji (Local Rasterizer):

  • 100% offline generowanie podglądu etykiet w Pythonie / Pillow (0 ms opóźnienia, brak limitów i zależności od zewnętrznych API).

• 📊 Druk Masowy i Import Danych:

  • Wczytywanie plików Excel (.xlsx, .xls), CSV oraz TSV metodą Drag & Drop.
  • Inteligentne automatyczne mapowanie kolumn do zmiennych szablonu {ZMIENNA}.
  • Wybór trybu drukowania:
    • ⚡ Szybki Druk (1 rekord) – błyskawiczny wydruk pojedynczego wybranego wiersza,
    • 🖨️ DRUKUJ (Wszystkie zaznaczone) – wysyła ciągły, nieprzerwany strumień ZPL dla wszystkich zaznaczonych pozycji.
  • Wbudowany Generator Serii Numerów (Auto-SN) z dopełnianiem zerami, prefiksami i sufiksami.
  • Eksport wsadu do wielostronicowego pliku PDF lub scalonego pliku ZPL.

• 🖨️ Komunikacja z Drukarkami Zebra:

  • Sieć LAN: Bezpośredni port RAW TCP/IP (Port 9100).
  • Port USB RAW: Bezpośredni zapis do /dev/usb/lpX (Linux) lub Windows Spooler RAW.
  • Diagnostyka sprzętowa (~HS): brak papieru, brak taśmy, otwarta głowica.
  • Skaner autodiscovery drukarek Zebra w lokalnej podsieci LAN i wykrywanie portów USB.

---

📁 Struktura Projektu

LabelDesigner/
├── core/                        # Wspólny silnik ZPL, druku, danych, szablonów i samoaktualizacji (updater.py)
│   ├── local_rasterizer.py      # Lokalny rasteryzator ZPL -> PNG/PDF (Pillow)
│   ├── printer.py               # Sterownik drukarek Zebra (TCP 9100, USB RAW, Win32 Spooler)
│   ├── zpl_engine.py            # Walidacja, zmienne {..} i kodowanie UTF-8 (^CI28)
│   ├── zpl_generator.py         # Generator ZPL z obiektów CanvasElement (w tym ^FB)
│   ├── zpl_parser_v2.py         # Dwukierunkowy parser ZPL -> CanvasElement
│   ├── data_loader.py           # Parser Excel/CSV z dopasowywaniem kolumn
│   ├── template_manager.py      # Menedżer szablonów .zpltemplate
│   ├── config_manager.py        # Menedżer konfiguracji i formatów etykiet
│   └── serial_generator.py      # Generator serii numerów
├── ui/                          # Interfejs aplikacji desktopowej (PySide6 / Qt6)
│   ├── main_window.py           # Główne okno aplikacji desktopowej
│   ├── designer_tab.py          # Edytor kodu ZPL z podglądem na żywo
│   ├── print_tab.py             # Zakładka importu danych i druku masowego
│   ├── settings_tab.py          # Ustawienia drukarki, DPI i rozmiarów etykiet
│   ├── label_size_dialog.py     # Okno zarządzania własnymi formatami etykiet
│   └── wysiwyg/                 # Wizualny edytor etykiet (Canvas, uchwyty, inspektor)
├── templates/                   # Szablony startowe (np. 70x40mm, 100x50mm, 100x150mm, 50x30mm)
├── tests/                       # Testy jednostkowe i integracyjne pytest
├── main.py                      # Punkt startowy aplikacji Desktop
│
└── WEBFORK/                     # 🌐 Wersja Web (Client-Server dla serwera / Raspberry Pi)
    ├── backend/
    │   ├── main.py              # Serwer REST API (FastAPI) i Print Spooler
    │   ├── models.py            # Modele Pydantic API
    │   └── security.py          # Token API, ochrona SSRF, limity żądań
    │                            # (silnik ZPL bierze ze wspólnego core/ powyżej)
    ├── frontend/
    │   ├── index.html           # Interfejs webowy (SPA, układ jak w desktopie)
    │   └── static/
    │       ├── css/app.css      # Ciemny motyw graficzny (Dark Theme)
    │       └── js/              # Moduły JS (canvas.js, zpl_editor.js, batch_print.js, settings.js)
    ├── deploy/alpine/
    │   ├── labeldesigner.initd  # Skrypt usługi OpenRC (/etc/init.d/labeldesigner)
    │   └── install_autostart_alpine.sh # 1-kliknięciowy instalator autostartu na Alpine Linux
    ├── Dockerfile               # Obraz Docker
    ├── docker-compose.yml       # Konfiguracja Docker Compose z dostępem do USB
    ├── run_web.bat              # Uruchomienie 1-kliknięciem na Windows
    └── run_web.sh               # Uruchomienie na Linux / Raspberry Pi

---

🖥️ Wersja Desktop (PySide6)

Aplikacja desktopowa z bogatym interfejsem graficznym Qt6, dedykowana do pracy na stacji roboczej projektanta.

Instalacja i Uruchomienie (Desktop):

1. Wymagania: Python 3.10 lub nowszy.
2. Instalacja zależności:

   pip install -r requirements.txt
   

3. Uruchomienie:

   python main.py
   

   Na Windows można również kliknąć dwukrotnie plik run.bat.

📂 Gdzie aplikacja przechowuje dane

Katalog instalacji jest traktowany jako tylko do odczytu (binarka może stać w /opt, /usr/local albo w Program Files), więc konfiguracja, szablony użytkownika, cache podglądu i log awarii trafiają do katalogu użytkownika:

System	Konfiguracja i szablony	Cache podglądu
Windows	%APPDATA%\ZPL Label Designer Pro\	%LOCALAPPDATA%\ZPL Label Designer Pro\cache\
Linux	$XDG_DATA_HOME/zpl-label-designer/ (domyślnie ~/.local/share/zpl-label-designer/)	$XDG_CACHE_HOME/zpl-label-designer/ (domyślnie ~/.cache/zpl-label-designer/)
macOS	~/Library/Application Support/ZPL Label Designer Pro/	~/Library/Caches/ZPL Label Designer Pro/

Przy pierwszym uruchomieniu katalog szablonów jest zasiewany kopią szablonów startowych, a istniejący config.json leżący obok aplikacji zostaje jednorazowo przeniesiony (aktualizacja ze starszej wersji nie gubi ustawień).

Zmienna środowiskowa LABELDESIGNER_DATA_DIR nadpisuje tę lokalizację — przydatna przy instalacjach przenośnych (pendrive) i na serwerach:

LABELDESIGNER_DATA_DIR=/srv/labeldesigner-data python main.py

🔨 Kompilacja Aplikacji Desktop (Windows & Linux):

Kompilacja dla Windows (.exe):

Uruchom plik build_windows.bat lub wpisz:

pyinstaller --clean -y label_designer_windows.spec

Gotowy plik wykonywalny znajdziesz w: dist/ZPL_Label_Designer_Pro/ZPL_Label_Designer_Pro.exe.

Pierwsze uruchomienie:

Nowa instalacja (brak pliku config.json) otwiera Kreator konfiguracji (ui/setup_wizard.py): połączenie z drukarką (sieć z wyszukiwaniem w LAN albo USB, test połączenia), rozmiar etykiety i DPI, a na końcu wydruk etykiety testowej (core/setup_label.py). Ponownie: Pomoc › Kreator konfiguracji…. Aktualizacja z wcześniejszej wersji go nie pokazuje.

Wydanie i aktualizacje (Windows):

Wydanie (numer wersji, testy, kompilacja, paczka .zip z notą i sumą SHA-256) przygotowuje skill wydanie-windows, skonfigurowany w wydanie.json. Wersja Windows aktualizuje się sama: przy starcie (po kilku sekundach, w tle) pyta serwer o najnowsze wydanie, a gdy jest nowsze, pokazuje w pasku stanu napis „Dostępna wersja X”. Kliknięcie otwiera okno z opisem zmian i przyciskami „Pobierz i zainstaluj”, „Później”, „Pomiń tę wersję”. Ręcznie: Pomoc › Sprawdź aktualizacje…; wyłączenie sprawdzania przy starcie: Ustawienia › Aktualizacje.

Wymagania wobec wydania w Gitei (czyta je core/updater.py):

• tag to sam numer (1.2.0), wyższy od działającej wersji; wydania z dopiskiem (1.2.0-rc1) dostają tylko użytkownicy, którzy sami używają kandydata;
• wydanie opublikowane (nie szkic) z załącznikiem ZPL_Label_Designer_Pro-<wersja>-windows.zip;
• w opisie linia SHA-256: <64 znaki hex> z sumą tego zipa — bez niej program odmawia instalacji (skill dopisuje ją do noty release/OPIS-<wersja>.md).

Instalacja zamyka program zwykłą drogą (z pytaniem o niezapisane zmiany), a skrypt .cmd podmienia exe i katalog _internal, po czym uruchamia nową wersję; przy błędzie przywraca poprzednią. Ustawienia i szablony użytkownika leżą w %APPDATA%\ZPL Label Designer Pro i nie są ruszane. Program zainstalowany w katalogu bez prawa zapisu (np. Program Files) odsyła do ręcznej instalacji ze strony wydania.

Instalator (Windows):

Wybrane wydania (co kilka wersji) mają też ZPL_Label_Designer_Pro-X.Y.Z-setup.exe (Inno Setup, skrypt installer.iss); do nowej instalacji wystarczy instalator z najnowszego wydania, które go ma, bo program po instalacji sam się zaktualizuje. Instaluje program dla bieżącego użytkownika w %LOCALAPPDATA%\Programs\ZPL Label Designer Pro, bez uprawnień administratora, dzięki czemu samoaktualizacja działa. Dodaje skrót w menu Start, opcjonalnie na pulpicie, skojarzenie plików .zpltemplate (dwuklik otwiera szablon) i deinstalator, który pyta, czy usunąć też ustawienia i szablony użytkownika. Instalator powstaje tylko na prośbę, przełącznikiem --instalator przy wydaniu (skill wydanie-windows, pole instalator w wydanie.json; wymaga Inno Setup 6: winget install JRSoftware.InnoSetup).

Aktualizacja bez internetu i zgłaszanie problemów:

• Pomoc › Zainstaluj aktualizację z pliku… instaluje paczkę ZPL_Label_Designer_Pro-X.Y.Z-windows.zip pobraną na innym komputerze. Plik .sha256 z wydania musi leżeć obok paczki; program sprawdza sumę, wersję zapisaną w exe i zawartość paczki.
• Pomoc › Zgłoś problem… buduje paczkę z opisem, informacjami o systemie i logami (logs\labeldesigner.log). Wysyłka: zgłoszenie na serwer Forgejo (prywatne repozytorium, token w Ustawienia › Zgłaszanie problemów), e-mail z załącznikiem (Simple MAPI, a gdy program pocztowy go nie obsługuje, mailto:) albo zapis do pliku. Nazwy kont Windows i adresy IP sieci lokalnej są ukrywane, a config.json nigdy nie trafia do paczki.

Kompilacja dla Linux:

• Na maszynie Linux / Raspberry Pi:

  chmod +x build_linux.sh
  ./build_linux.sh
  

  Gotowy plik wykonywalny znajdziesz w: dist/ZPL_Label_Designer_Pro_Linux/ZPL_Label_Designer_Pro.

• Kompilacja przez Docker (na dowolnym systemie):

  docker build -f Dockerfile.build_linux -t zpl_builder_linux .
  docker run --rm -v "%cd%/dist:/app/dist" zpl_builder_linux
  

---

🌐 Wersja Web Server (WEBFORK/)

Wersja serwerowa przeznaczona do uruchomienia na maszynie (serwer, komputer magazynowy, Raspberry Pi) podłączonej do drukarki, umożliwiająca projektowanie i drukowanie etykiet z dowolnego urządzenia w sieci lokalnej przez przeglądarkę internetową.

1. Uruchomienie Lokalne (Web):

• Windows: Uruchom WEBFORK/run_web.bat lub wpisz:

  cd WEBFORK
  python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
  

• Linux / Raspberry Pi:

  cd WEBFORK
  chmod +x run_web.sh
  ./run_web.sh
  

• Otwórz w przeglądarce: http://localhost:8000 (lub http://<IP_SERWERA>:8000).

---

2. Autostart na Alpine Linux (OpenRC)

Na serwerze z systemem Alpine Linux dostępny jest w pełni zautomatyzowany skrypt instalacyjny:

cd WEBFORK
chmod +x deploy/alpine/install_autostart_alpine.sh
sudo ./deploy/alpine/install_autostart_alpine.sh

Co wykonuje skrypt:

1. Doinstalowuje pakiety apk (python3, py3-pip, py3-pillow, py3-virtualenv, openrc, gcc, musl-dev, linux-headers, font-dejavu).
2. Instaluje aplikację w /opt/labeldesigner i konfiguruje środowisko venv.
3. Rejestruje usługę /etc/init.d/labeldesigner.
4. Dodaje usługę do autostartu (rc-update add labeldesigner default) i natychmiast ją uruchamia.

Zarządzanie usługą w Alpine Linux:

• Status: rc-service labeldesigner status
• Restart: rc-service labeldesigner restart
• Zatrzymanie: rc-service labeldesigner stop
• Logi: tail -f /var/log/labeldesigner.log

---

3. Uruchomienie w Kontenerze Docker

cd WEBFORK
docker-compose up -d --build

Kontener automatycznie mapuje porty USB hosta (/dev/usb) dla bezpośredniej obsługi drukarek podłączonych kablem USB.

---

🔍 Kluczowe Moduły i Funkcje

1. Projektant Wizualny WYSIWYG

• Wyrównanie tekstu wewnątrz ramki (^FB):
  • ↔️ Na środku (Center - C) – tekst jest precyzyjnie centrowany wewnątrz wyznaczonego pola,
  • ⬅️ Do lewej (Left - L) – wyrównanie do lewej krawędzi,
  • ➡️ Do prawej (Right - R) – wyrównanie do prawej krawędzi,
  • ↕️ Wyjustowany (Justify - J) – wyrównanie obustronne.
• Bloki tekstowe z zawijaniem (^FB): w grupie „Zawijanie tekstu” ustawiasz maksymalną liczbę linii i odstęp między nimi; tekst zawija się po słowach w obrębie szerokości pola, a ramka sama rośnie do wysokości bloku. Canvas i podgląd wydruku łamią linie w tych samych miejscach, a czerwony znacznik w rogu ostrzega, gdy tekst nie mieści się w liczbie linii.
  • Działa także dla zmiennych {NAZWA} w druku masowym: każdy rekord zawija się według własnej długości, a ręczne łamanie linii z komórki Excela/CSV (Alt+Enter) trafia na etykietę jako nowa linia (w polu jednoliniowym jako spacja).
• Blokowanie pozycji obiektów (Lock 🔒) zapobiegające przypadkowemu przesunięciu.
• Asystent kodów GS1 / EAN z automatyczną walidacją i wyliczaniem cyfry kontrolnej Modulo 10.

2. Silnik Drukarek Zebra

• Druk Sieciowy: RAW TCP/IP socket na porcie 9100.
• Druk USB: Bezpośredni zapis RAW do urządzeń /dev/usb/lp0...lp9 (Linux) oraz natywny Windows Spooler RAW.
  • Windows: druk RAW wymaga pakietu pywin32 (moduł win32print) — jest w requirements.txt, więc instaluje się razem z resztą zależności. Bez niego wykrywanie i druk USB są nieaktywne, a aplikacja wprost o tym informuje.
  • Linux: użytkownik musi należeć do grupy lp (sudo usermod -aG lp $USER) lub mieć odpowiednią regułę udev.
• Bezpieczeństwo danych: wartości wstawiane z Excela/CSV oraz teksty z projektanta są automatycznie zabezpieczane komendą ^FH i kodowaniem szesnastkowym, więc dane zawierające ^ lub ~ nie mogą rozbić etykiety ani wysłać komendy do drukarki.
• Druk Masowy (Batch): Scalanie wszystkich etykiet w jeden strumień ZPL (^XA...^XZ\n^XA...^XZ), co eliminuje problemy z rozłączaniem sesji TCP po wydrukowaniu 1 etykiety.

3. Import Danych (Excel / CSV) i Druk Masowy

• Wczytywanie baz produktowych i adresowych (.xlsx, .csv).
• Płynna nawigacja po rekordach z podglądem w locie.
• Opcje:
  • ⚡ Szybki Druk (1 rekord) – drukuje wyłącznie aktualnie przeglądany wiersz.
  • 🖨️ DRUKUJ (Wszystkie zaznaczone) – drukuje komplet zaznaczonych wierszy z tabeli.
• Generator sekwencji numerów seryjnych z definiowanym krokiem, prefiksem, sufiksem i długością zer.

4. Menedżer Rozmiarów Etykiet

• Fabryczne presety: 100x150 mm (Kurierska), 100x50 mm (Magazynowa), 70x40 mm (Produktowa), 50x30 mm (Regałowa).
• Kreator własnych rozmiarów: możliwość wprowadzania dowolnych wymiarów w milimetrach (np. 80x40 mm, 60x30 mm) bezpośrednio z poziomu interfejsu GUI / Web, z automatycznym przeliczaniem na punkty (dots) przy 203 DPI, 300 DPI i 600 DPI.

---

🧪 Testy Jednostkowe i Integracyjne

Projekt posiada kompletny zestaw 204 testy automatyczne (154 desktop + 50 web) pokrywających silnik ZPL, parser, generator, odporność na wstrzyknięcie komend ZPL, diagnostykę drukarek (~HS), backend Windows Spooler, komunikację sieciową i USB, wykrywanie fontów systemowych, ścieżki danych użytkownika, import danych i endpointy REST API:

# Uruchomienie wszystkich testów
pytest -v

# Uruchomienie testów samej wersji Web
pytest -v WEBFORK/tests/

---

⚙️ Ciągła Integracja (CI)

Workflow .github/workflows/ci.yml uruchamia przy każdym pushu i PR:

Zadanie	Co sprawdza
Desktop — ubuntu / windows	import punktu wejścia + pełny zestaw testów na obu docelowych systemach
Web backend (bez Qt)	testy serwera w środowisku bez PySide6 — dowód, że działa na serwerze headless
Build — ubuntu / windows	rzeczywista kompilacja PyInstallerem i weryfikacja, że plik wykonywalny powstał
Obraz Docker	budowa obrazu i smoke test kontenera (/, /api/config, /api/templates)

Testy metryk pikselowych (szerokości etykiet kontrolek) są oznaczone markerem ui_metrics i uruchamiane tylko na Windows — zależą od metryk fontów danej platformy, więc na Linuksie dawałyby fałszywe alarmy. Reszta testów UI jest strukturalna i działa wszędzie.

Uwaga dla Gitea: repozytorium jest hostowane na Gitea, która rozumie ten sam format workflow (Gitea Actions). Wymaga to jednak zarejestrowanych runnerów z etykietami ubuntu-latest i windows-latest. Domyślne obrazy act_runner są tylko linuksowe, więc zadania Windows zostaną pominięte, dopóki nie podepniesz runnera Windows. Zadanie Docker potrzebuje runnera z dostępem do demona Dockera.

Uruchomienie tych samych kontroli lokalnie

Nie wymaga żadnego runnera:

python run_checks.py            # testy dla bieżącej platformy
python run_checks.py --build    # dodatkowo kompilacja binarki
python run_checks.py --web      # dodatkowo testy serwera web (osobne środowisko bez Qt)

---

📄 Licencja

Copyright © 2026 Kamil Adamus (kamil@adamus.cloud).

Oprogramowanie jest udostępniane na warunkach wolnej licencji GNU General Public License v3 (GPL-3.0-or-later). Pełny tekst licencji znajduje się w pliku LICENSE (LICENSE.txt).

💼 Płatne Wsparcie Techniczne i Wdrożenia Komercyjne

Aplikacja w wersji publicznej udostępniana jest na zasadach licencji GPLv3 bez gwarancji. W ramach jednoosobowej działalności gospodarczej Autor świadczy odpłatne usługi profesjonalne:

• Wsparcie techniczne (SLA / helpdesk) – asysta powdrożeniowa, rozwiązywanie problemów, gwarancja czasu reakcji.
• Wdrożenia komercyjne – instalacja i konfiguracja w infrastrukturze klienta, na serwerach, Raspberry Pi oraz terminalach przemysłowych.
• Integracje z systemami ERP / WMS – dedykowane konektory baz danych, automatyzacja wydruków ze skanerów kodów kreskowych.
• Licencjonowanie komercyjne (Dual-Licensing) – dla firm, które nie mogą lub nie chcą stosować wymogów licencji GPLv3 (np. chcą zamknąć własne integracje lub wdrożyć system jako zamknięte rozwiązanie).

Kontakt w sprawie oferty komercyjnej: kamil@adamus.cloud

Zasoby zewnętrzne

• Ikony interfejsu: Uicons by Flaticon (Regular Rounded), licencja Flaticon — darmowa pod warunkiem podania autora. Podpis jest w oknie „O programie”; pełny tekst licencji: ui/assets/icons/LICENSE-flaticon.txt. Ikony generuje tools/build_ui_icons.py (tam też dodaje się nowe).