Pakowanie Kablowo: system magazynowy zbudowany z Claude Code

---

Co sprzedaje Kablowo i dlaczego pakowanie kabli jest inne

Kablowo to firma e-commerce sprzedająca przez Allegro, Amazon PL i Erli. Główne kategorie produktów:

Dlaczego to nie jest standardowy fulfillment

Firma butów pakuje: weź z półki, włóż do kartonu, naklej etykietę. 60 sekund.

Firma kablowa pakuje:

1. Sprawdź zamówienie — czy to kabel, peszle, mix?
2. Odmierz metraż na maszynie (15m kabla YDYp 3x2.5)
3. Nawiń na szpulę lub włóż do pudełka
4. Jeśli zamówienie mieszane — zbierz kable + peszle + akcesoria z różnych stref magazynu
5. Wydrukuj etykietę MIX z kodem grupowym
6. Sprawdź czy zostały resztki kabla — jeśli tak, zaewidencjonuj

To jest 6 kroków zamiast 3. I każdy wymaga innego narzędzia. Dlatego gotowe WMS-y tego nie obsługują.

Wolumen: setki zamówień dziennie przez dwa oddzielne konta BaseLinker (konto A i B — historyczne powody, dwa osobne sklepy Allegro). Pracownik musi widzieć zamówienia z obu kont jako jeden strumień.

---

Dlaczego gotowe rozwiązania nie wystarczyły

Problem 1: Dwa konta BaseLinker

BaseLinker nie obsługuje natywnego mergowania zamówień z wielu kont. Pracownik musiał przełączać się między dwoma panelami, co generowało błędy i gubienie zamówień.

Nasze rozwiązanie: Równoległy fetch z obu kont przez asyncio.gather, merge po date_confirmed, zapis do lokalnej bazy z kolumną account (“A”/“B”). Pracownik widzi jeden ekran — system w tle wie, do którego konta odpalić trigger.

Problem 2: Brak widoków pakowania

BaseLinker pokazuje wszystkie zamówienia płasko. Ale w magazynie kablowym masz fizycznie oddzielne strefy: kable (skrętki) leżą gdzie indziej niż peszle, a oleje jeszcze gdzie indziej. Pracownik potrzebuje widoku filtrowanego po strefie produktu.

Nasze rozwiązanie: Cztery widoki pakowania:

• Skrętki — zamówienia zawierające tylko kable
• Peszle — zamówienia zawierające tylko peszle/osłony
• Mix — zamówienia mieszane (kable + peszle + inne)
• Inne — wszystko co nie pasuje do powyższych

Każdy produkt w katalogu BaseLinker ma custom field strefa (np. SKRETKI, PESZLE, OLIWY). System automatycznie kategoryzuje zamówienia na podstawie stref produktów w nich zawartych.

Problem 3: Integracja z maszyną do kabli

Maszyna do nawijania kabli to ESP8266 (mikrokontroler) sterujący silnikiem. Żaden gotowy WMS nie integruje się z custom hardware. Musieliśmy to zbudować od zera.

Problem 4: Etykiety MIX

Zamówienia mieszane wymagają specjalnej etykiety grupowej (kod MIX) wydrukowanej na drukarce Zebra. Pracownik z jednej strefy pakuje kable, z drugiej peszle — etykieta MIX łączy te paczki w jedno zamówienie.

---

Architektura systemu

Stack technologiczny

Scalanie dwóch kont BaseLinker

Kluczowy element architektury: dwa niezależne konta BaseLinker scalane transparentnie.

┌─────────────────┐    asyncio.gather()    ┌─────────────────┐
│  BaseLinker A    │ ──────────────────────>│                 │
│  (konto główne)  │                        │   FastAPI        │
│                  │                        │   merge by       │  ──> Jedna lista
│  BaseLinker B    │ ──────────────────────>│   date_confirmed │      zamówień
│  (konto dodatkowe)│                        │                 │
└─────────────────┘                        └─────────────────┘

Każde zamówienie w bazie ma kolumnę account (“A” lub “B”). Gdy pracownik odpala trigger (np. drukuj spis, drukuj etykietę), system automatycznie wybiera odpowiedniego klienta BaseLinker na podstawie order.account.

Background jobs

Synchronizacja działa w tle bez udziału pracownika:

• Co 5 minut: odświeżanie zamówień z obu kont BL
• Co 60 minut: synchronizacja katalogu produktów
• Raz dziennie: audyt stref (sprawdzenie czy każdy produkt ma przypisaną strefę)

---

Widoki pakowania — jak pracownik korzysta z systemu

Pracownik magazynu otwiera aplikację na tablecie lub telefonie i widzi cztery zakładki:

Flow pakowania krok po kroku

---

Maszyna do nawijania kabli — ESP8266

To jest serce operacji kablowej. ESP8266 to mikrokontroler Wi-Fi za kilkadziesiąt złotych, który steruje silnikiem DC nawijającym kabel.

Co robi maszyna

1. Odmierza długość kabla — z dokładnością do 0.1m (encoder na kole)
2. Nawija na szpulę (tryb szpula) lub wkłada do pudełka (tryb pudełko)
3. Automatycznie odejmuje odpad — każde cięcie generuje ~0.5m odpadu (nóż + zapas). System to odlicza
4. Hamuje precyzyjnie — rampa prędkości w dół, żeby kabel nie wyskoczył ze szpuli

Endpointy maszyny

Parametry konfiguracji

Maszyna ma kilkanaście parametrów konfiguracyjnych, które admin ustawia przez panel:

• PWM speed — prędkość obrotowa silnika (0-255)
• Ramp up — czas rozruchu (ms) — żeby kabel się nie zerwał przy starcie
• Ramp down — czas hamowania (ms) — precyzyjne zatrzymanie
• Brake mode — typ hamulca: elektroniczny (PWM reverse) lub mechaniczny
• Watchdog — auto-stop po X sekundach bez impulsów encodera (zacięcie kabla)
• Waste offset — stały odpad na cięcie (domyślnie 0.5m)

Persistent connection pooling

ESP8266 to mikrokontroler z ograniczonymi zasobami (80 KB RAM). Każde nowe połączenie TCP to obciążenie. Dlatego nasz backend utrzymuje persistent httpx client z connection poolingiem:

_client = httpx.AsyncClient(
    base_url="http://192.168.1.113",
    timeout=2.0,  # status polling — krótki timeout
    limits=httpx.Limits(max_connections=2, max_keepalive_connections=1),
)

Frontend odpytuje status maszyny co 1 sekundę (hook useESP). Dzięki persistent connection nie ma narzutu TCP handshake przy każdym request.

Dodatkowy debounce: 3 kolejne faile zanim system zadeklaruje maszynę jako offline (unika fałszywych alarmów przy chwilowym zacięciu Wi-Fi).

Wykres wydajności

Wydajność maszyny ESP8266 vs ręczne cięcie kabla

Czas w sekundach na 100 metrów kabla

Ręcznie (100m)

~1,5 min

90 sek

Maszyna ESP (100m)

~20 sek

20 sek

Oszczędność czasu

78%

4.5x szybciej

Kluczowy insight: Maszyna ESP eliminuje etap “odmierzania długości” całkowicie — encoder mierzy metry w trakcie nawijania. Ręcznie trzeba odmierzyć, zaznaczyć, dociągnąć. Z maszyną: wpisujesz 15m, klikasz Start, kabel nawija się sam.

---

Drukarka Zebra i skanery kodów kreskowych

Etykiety ZPL

System generuje etykiety w formacie ZPL (Zebra Programming Language) — format natywny dla drukarek termicznych Zebra. Etykieta 100x150mm (4x6”) zawiera:

Print Agent na Windows

Drukarka Zebra jest podłączona do PC z Windows. Na PC działa Print Agent — mały serwis HTTP, który:

• Przyjmuje komendę ZPL z backendu FastAPI
• Przekazuje ją do drukarki Zebra przez Windows Print API
• Raportuje status (online/offline, kolejka wydruku)
• Auto-restart w razie awarii

Endpointy drukowania:

• GET /api/print/mix-label/{order_id} — renderuje etykietę HTML (otwiera print dialog w przeglądarce)
• POST /api/print/mix-label/{order_id}/headless — drukuje bezpośrednio na Zebrze (headless, bez przeglądarki)
• GET /api/print/agent-status — health check agenta
• GET /api/print/agent-printers — lista dostępnych drukarek

Skanery kodów kreskowych i telefon Zebra

Pracownicy magazynu używają skanerów Zebra (handheld) i telefonów z czytnikiem kodów do pickowania zamówień. System multi-device sync (/api/collected) pozwala na:

• Skanowanie kodu EAN produktu → automatyczne zaznaczenie jako “zebrane” (picked)
• Wielourządzeniowy sync — 4 koszyki pickingowe, każdy z własnym skanerem
• Identyfikacja urządzenia/użytkownika — wiadomo kto co zebrał
• Auto-cleanup — po spakowaniu zamówienia, stan zebranych itemów się resetuje

---

Integracja z BaseLinker API — jakie zapytania wykonujemy

System komunikuje się z BaseLinker przez custom async client z kolejką priorytetową. Oto dokładna lista metod API, z których korzystamy:

Metody API BaseLinker

System priorytetów i rate limiting

Nasz BaseLinker client to nie jest zwykły wrapper na requests.post(). To asynchroniczny klient z kolejką priorytetową:

Dynamic trigger engine

Trigger ID nie są hardcoded w kodzie. Są w zmiennej środowiskowej jako JSON:

ACCOUNT_A_TRIGGERS={"skretki.spis":44364, "skretki.etykieta":44365, "mix.spis":44366, "mix.etykieta":44367}

GET /api/triggers/available skanuje JSON dict po prefixie widoku. Dodanie nowego triggera = edycja zmiennej + restart. Zero zmian w kodzie.

---

Wykres oszczędności czasu pakowania

Czas pakowania 20 zamówień: ręcznie vs z aplikacją

Porównanie w minutach — realne dane z magazynu Kablowo

Ręcznie

3h 10min

Z aplikacją

1h 56min

Oszczędność

39%

Co dokładnie oszczędzamy

Skrętki (kable): Największa oszczędność — maszyna ESP eliminuje ręczne odmierzanie. Zamiast mierzyć, zaznaczać, ciągnąć kabel — pracownik wpisuje metraż i klika Start.

Mix (zamówienia mieszane): Etykiety MIX z automatycznym kodem grupowym eliminują szukanie siebie nawzajem po magazynie. Pracownik z jednej strefy widzi kod “AB7K”, pracownik z drugiej strefy szuka tego samego kodu — i łączą paczki.

Picking (zbieranie): Skanery kodów kreskowych eliminują ręczne sprawdzanie listy. Skan → pick → następny. Bez czytania nazw i porównywania.

Etykietowanie Zebra: Headless printing eliminuje przełączanie okien, szukanie drukarki, formatowanie. Klik → etykieta na Zebrze. 5 sekund.

Łącznie: ~39% oszczędności czasu na pełnej zmianie pakowania (20 zamówień per batch). Na skali miesiąca to kilkadziesiąt godzin roboczych.

---

Zdjęcia i dokumentacja pakowania

System posiada pełny moduł mediów do dokumentacji operacji magazynowych:

Pliki organizowane są automatycznie: YYYY/MM/DD/{uuid}-{oryginalna_nazwa}. UUID zapewnia unikalność, oryginalna nazwa pozwala na identyfikację. Każdy plik ma tracking: kto uploadował, kiedy, jaki typ MIME.

---

Struktura wewnętrznego API

Cały backend to FastAPI z czystym podziałem na warstwy: Router (HTTP) → Service (logika) → Repository (baza danych).

Drzewo endpointów

Format odpowiedzi

Każdy endpoint zwraca ustandaryzowany JSON:

{
  "status": "SUCCESS",
  "data": { ... },
  "count": 42
}

Lub w przypadku błędu:

{
  "status": "ERROR",
  "detail": "Order not found",
  "error_code": "ERR_NOT_FOUND"
}

Pełna dokumentacja Swagger

Wygenerowaliśmy pełną dokumentację API w formacie OpenAPI 3.0, dostępną jako interaktywny Swagger UI: Dokumentacja API Pakowanie Kablowo.

Swagger zawiera wszystkie endpointy, schematy request/response, kody błędów i przykłady. Dokumentacja jest standalone — nie jest podpięta do produkcyjnego backendu.

---

Podsumowanie

Kluczowe metryki

Powiązane artykuły

Ten system to nie tylko jeden monolit — składa się z kilku wyspecjalizowanych modułów. Każdy z nich ma swój osobny artykuł:

Cały system zbudowaliśmy z Claude Code w kilka tygodni. ROI zwrócił się w pierwszym miesiącu — głównie dzięki oszczędności czasu pakowania i redukcji strat materiałowych na resztkach kablowych.