gPdf
Przypadki użycia · Logistyka i wysyłka

PDF etykiet wysyłkowych w skali przewoźnikowej

Renderuj termiczne etykiety wysyłkowe 4×6 z wektorowymi kodami GS1-128, kartonowymi kodami ITF-14 i identyfikatorami palet SSCC-18. Renderowanie na edge utrzymuje p99 poniżej 15 ms, także podczas szczytów Black Friday.

Zadanie do wykonania

Renderuj gotowe dla przewoźnika termiczne etykiety wysyłkowe 4×6 — w tym wektorowe kody GS1-128, ITF-14 i SSCC-18 — bezpośrednio z JSON zamówienia, bez uruchamiania headless browsera dla każdego żądania. Wynik musi skanować się niezawodnie przy 203 dpi na drukarkach Zebra/SATO/Honeywell i pozostać poniżej 15 ms p99 w szczytach sprzedażowych.

Dlaczego gPdf pasuje tutaj

  • Wektorowe Code 128, QR, DataMatrix, PDF417 oraz GS1-128 / ITF-14 / SSCC-18 — z dokładnością podpikselową przy 203 dpi, 300 dpi i 600 dpi.
  • Precyzja współrzędnych 0,1 mm — spełnia tolerancję całkowitej długości przewoźnika dla linii czytelnych dla człowieka.
  • Rozmiar strony `label_4_6_in` oraz `label_4_8_in` i `label_a6` są wstępnie skonfigurowane dla dominujących formatów drukarek termicznych.
  • Determinizm — ten sam JSON zamówienia renderuje się do bajtowo identycznego PDF, więc ponowny wydruk w magazynie nie tworzy "innej" etykiety.
  • Renderowanie na edge — p50 3 ms, p99 8 ms, nawet gdy 50 000 etykiet drukuje się w tej samej minucie przed odbiorem przez przewoźnika.
  • Bezstanowość: etykieta istnieje w pamięci przez około 4 ms w izolacie Cloudflare Worker, po czym jest zwalniana. Bez magazynu dokumentów i bez dodatkowej powierzchni wycieku danych przewoźnika.

Przykładowe żądanie

POST /api/v1/pdf/render — minimalna termiczna etykieta 4×6 z kodem śledzenia przewoźnika Code 128.

{
  "pages": [{
    "size": "label_4_6_in",
    "elements": [
      {
        "type": "text",
        "x": 4, "y": 6,
        "content": "SHIP TO",
        "style": { "font_size": 8, "font_family": "NotoSans-Regular" }
      },
      {
        "type": "text",
        "x": 4, "y": 12,
        "content": "Acme Distribution Centre\n1200 Logistics Pkwy\nMemphis TN 38116",
        "style": { "font_size": 11, "font_family": "NotoSans-Regular" }
      },
      {
        "type": "barcode",
        "format": "code128",
        "content": "1Z999AA10123456784",
        "x": 4, "y": 60,
        "width": 92, "height": 22,
        "barcode_text": { "enabled": true, "position": "bottom" }
      }
    ]
  }]
}

Zgodność i wymagania techniczne

  • GS1 General Specifications — szerokość modułu (X-dimension), quiet zone i długość całkowita odpowiadają tolerancjom GS1 Section 5.4 przy 203 dpi.
  • Wymagania przewoźników — UPS, FedEx, DHL i USPS akceptują wyrenderowany wynik jako skanowalny; nie jest wymagane dodatkowe przetwarzanie dla konkretnego przewoźnika.
  • PDF/A-2b dostępne do archiwizacji przez `settings.profile = "pdfa-2b"`, jeśli musisz zachować PDF etykiety ze względów podatkowych albo audytowych.

Obciążenie etykiet wysyłkowych w jednym akapicie

Każde zamówienie tworzy jeden PDF, każdy PDF jest drukowany raz na drukarce termicznej, a tryb awarii przy zbyt wolnym systemie nie brzmi “strona ładuje się powoli” — tylko “odbiór w magazynie czeka za API renderującym etykiety”. Wysyłka to obszar, w którym opóźnienie p99 jest kluczową metryką produktu, deterministyczny wynik ma znaczenie, bo ponowne wydruki są rutyną, a jakość kodów kreskowych — mierzona tolerancjami GS1 X-dimension, a nie pikselami — decyduje, czy skanery odczytają etykietę za pierwszym razem.

Stosy PDF oparte na headless browserach mają problem z tymi trzema wymaganiami naraz: koszt cold start narasta w szczycie, rastrowe kody kreskowe tracą jakość na małych etykietach termicznych, a rasteryzacja fontów zmienia się między wersjami Chromium, więc “bajtowo identyczny ponowny wydruk” staje się niemożliwy.

Dlaczego gPdf pasuje

Termiczna etykieta 4×6 jest mała (576 × 864 piksele przy 203 dpi), ma niewiele elementów (bloki tekstu + 1-2 kody kreskowe + opcjonalne logo przewoźnika) i duży wolumen (średniej wielkości 3PL renderuje 50 000-500 000 dziennie). To właśnie obciążenie, dla którego zbudowano gPdf. Silnik renderowania:

  1. Kompiluje układ raz — współrzędne strony, kaskady fontów i geometria kodów kreskowych są rozwiązywane w czasie żądania, nie przez silnik układu przeglądarki.
  2. Wektoryzuje każdy kod kreskowy — moduły są rysowane bezpośrednio w strumieniu PDF, więc GS1-128 o szerokości 30 mm czyta się czysto przy 203 dpi albo 600 dpi bez logiki rasteryzacji zależnej od DPI po Twojej stronie.
  3. Osadza NotoSans CJK + Latin — te same dane wejściowe poprawnie renderują chińską nazwę przewoźnika bez dostarczania fontów do kontenera renderującego.

p99 pozostaje płaskie na poziomie 8 ms w naszym obciążeniu referencyjnym (1000 wywołań powyższej próbki w EU-WEST), niezależnie od tego, czy pojedynczy izolat wyrenderował jedną etykietę, czy 10 000 etykiet.

Matematyka wolumenu i kosztu

Typowy średniej wielkości 3PL działa w okolicach 50 000 etykiet dziennie, czyli około 1,5 mln miesięcznie. W planie Basic (5 USD/mies. za 100 000 stron, 0,00005 USD za stronę nadwyżki) oznacza to:

1,5 mln stron × 0,00005 USD = 75,00 USD nadwyżki
+ podstawa planu Basic      =  5,00 USD
─────────────────────────────────────
razem                        = 80,00 USD / mies.

To samo obciążenie na Puppeteer-on-Lambda mieści się zwykle w przedziale 200-400 USD/mies. przy typowych ustawieniach współbieżności Lambda, zanim doliczysz koszt cold start w szczycie.

Black Friday: przykład roboczy

Szczytowe spiętrzenie to obciążenie, w którym renderowanie na edge najszybciej pokazuje swoją wartość. Klient retailowy osiągający 200% normalnego wolumenu etykiet w pierwszej godzinie Black Friday — powiedzmy 100 000 etykiet w 60 minut, średnio 1700 etykiet/minutę i piki 5000/minutę — kończy pracę w ramach jednej puli regionu Cloudflare Workers bez kosztu cold start. To samo obciążenie na ciepłej puli Puppeteer dobranej do średniego ruchu powoduje cold start 1,5-2,5 s na kontenerach uruchamianych dla burstów, a stanowisko odbioru w magazynie odczuwa każdy taki przypadek.

Gdzie spojrzeć dalej

Czytaj dalej