Instalacja i parowanie Bridge krok po kroku

Bridge to lokalna usługa (Node/TypeScript) działająca na komputerze przy kasie lub drukarce. Łączy się z chmurą tylko połączeniem wychodzącym, więc nie trzeba otwierać żadnych portów. Do urządzeń sięga przez TCP, port szeregowy (COM) lub USB-serial.

Wymagania

• Node.js w wersji 22.13 lub nowszej (Bridge używa wbudowanego node:sqlite).
• Komputer włączony na stałe, z dostępem do internetu i połączeniem z urządzeniem.
• Dla portów szeregowych pakiet serialport (natywne binarki): po zbudowaniu wykonaj w katalogu dist polecenie `npm install --omit=dev`. Dla kas TCP i emulatorów nie jest potrzebny.
• Bridge to pojedynczy plik cli.mjs. Instalatora Windows i automatycznych aktualizacji nie ma: usługę uruchamiasz ręcznie, a nową wersję wgrywasz sam.

Instalacja i parowanie

1. W aplikacji otwórz „Kasy i drukarki”, zakładka „Urządzenia”, kliknij „Dodaj urządzenie”, a potem „Sparuj” (kreator pokazuje te same kroki). Kod parowania jest jednorazowy i ważny 30 minut.
2. Zbuduj pakiet poleceniem `pnpm --filter @zaksio/bridge build`. Wynik trafia do apps/bridge/dist (cli.mjs, package.json, deploy/).
3. Skopiuj deploy/bridge.config.example.json jako bridge.config.json i dopasuj urządzenia. Pole `key` to lokalna nazwa urządzenia w Bridge.
4. Sparuj: `node dist/cli.mjs pair --device kasa1 --code ABCD-EFGH --config bridge.config.json`. Polecenie zapisuje token urządzenia i klucz podpisu w lokalnej bazie (dataDir/bridge.sqlite).
5. Uruchom: `node dist/cli.mjs run --config bridge.config.json`, a na stałe jako usługę (kolejna sekcja).
6. Wskaźnik w kreatorze zmieni się sam na „Sparowano”, gdy Bridge zgłosi się z kodem.

Praca jako usługa

• Linux: plik deploy/zaksio-bridge.service (systemd).
• Windows, np. NSSM: `nssm install ZaksioBridge "C:\Program Files\nodejs\node.exe" "C:\ZaksioBridge\cli.mjs run --config C:\ZaksioBridge\bridge.config.json"`, potem `nssm set ZaksioBridge AppDirectory C:\ZaksioBridge` oraz `nssm set ZaksioBridge Start SERVICE_AUTO_START`.
• Plik konfiguracji (JSON) ma pola apiUrl, dataDir, heartbeatSeconds, pollWaitSeconds i listę devices (key, driver, transport, options). Literówki w opcjach sterownika są błędem.
• Domyślnie Bridge drukuje bez polskich znaków (encoding ascii). Inną stronę kodową ustaw po sprawdzeniu ustawień kasy, bo zła drukuje krzaki. Stawka VAT, której kasa nie zna, kończy się błędem bez wydruku.

Sygnał życia, status i alert offline

Bridge regularnie wysyła sygnał życia (heartbeat) ze stanem urządzenia, w tym papieru. W zakładce „Urządzenia” widzisz status: „Online”, „Offline”, „Problem”, „Niesparowane” lub „Wyłączone” i czas ostatniego kontaktu. Pole „Alert po braku sygnału (minuty)” w formularzu urządzenia (domyślnie 5, zakres 1 do 1440) ustala, po ilu minutach ciszy urządzenie dostaje status „Offline” i pojawia się alert „Urządzenie nie odpowiada”. Polecenie `status` pokazuje stan lokalnie.

Token, rotacja i bezpieczeństwo

• Token urządzenia (zbt_...) jest w bazie chmury przechowywany tylko jako skrót. Przycisk „Rotuj token” wymienia go bez żadnej czynności na komputerze: Bridge widzi wygasanie w sygnale życia, pobiera nowy token i zapisuje go. Stary działa jeszcze 15 minut.
• Ponowne parowanie unieważnia stary token, a nowy kod unieważnia poprzedni. Wyłączone urządzenie traci dostęp natychmiast.
• Zadania są podpisane (HMAC-SHA256, klucz z parowania) i sprawdzane przed wykonaniem. Zadanie anulowane lub przekierowane w aplikacji nie zostanie wydrukowane.
• Token i klucz leżą w lokalnej bazie: chroń katalog danych uprawnieniami systemu (Linux: StateDirectoryMode=0700, Windows: ACL tylko dla konta usługi).

Tryb offline

Kolejka lokalna to SQLite w trybie WAL. Zadania pobrane przed utratą łączności drukują się lokalnie, a wyniki czekają i są dosyłane po powrocie internetu. Po restarcie w trakcie wydruku Bridge sprawdza licznik dokumentów kasy zamiast ponawiać na ślepo. Nowe zadania wymagają połączenia: tworzenia zadań przez POS bez internetu jeszcze nie ma.

Gdzie to znaleźć w aplikacji

• Menu „Sprzedaż”, „Kasy i drukarki”, zakładka „Urządzenia”: przyciski „Dodaj urządzenie”, „Sparuj” (po sparowaniu „Sparuj ponownie”), „Edytuj”, „Rotuj token”, „Wyłącz” i „Włącz”.
• Dodawanie, edycja i parowanie wymagają uprawnienia fiscal:write; podgląd fiscal:read. Moduł wymaga cechy profilu `fiscal`.