gPdf
Сценарії використання · Логістика й доставка

PDF транспортних етикеток у масштабі перевізника

Рендерте термоетикетки 4×6 із векторними штрихкодами GS1-128, кодами коробів ITF-14 і палетними ID SSCC-18. Рендеринг на edge тримає p99 нижче 15 мс навіть під час піків Black Friday.

Задача

Рендерити готові для перевізника термоетикетки 4×6 — зокрема векторні штрихкоди GS1-128, ITF-14 і SSCC-18 — напряму з JSON замовлення, без запуску headless-браузера для кожного запиту. Вивід має надійно скануватися при 203 dpi на принтерах Zebra, SATO і Honeywell та залишатися нижче 15 мс p99 під час пікових навантажень роздрібної торгівлі.

Чому gPdf підходить для цього сценарію

  • Векторні Code 128, QR, DataMatrix, PDF417 і GS1-128 / ITF-14 / SSCC-18 — із субпіксельною точністю при 203 dpi, 300 dpi і 600 dpi.
  • Точність координат 0,1 мм — відповідає допускам перевізників щодо загальної довжини людинозчитуваних рядків.
  • Розміри сторінок `label_4_6_in`, `label_4_8_in` і `label_a6` уже налаштовані для основних форматів термопринтерів.
  • Детермінізм — той самий JSON замовлення рендериться в байтово ідентичний PDF, тому передрук на складі не створює “іншу” етикетку.
  • Рендеринг на edge — p50 3 мс, p99 8 мс, навіть коли 50 000 етикеток друкуються в одну хвилину перед забором перевізником.
  • Stateless: етикетка існує в пам’яті Cloudflare Worker isolate приблизно 4 мс, а потім звільняється. Немає сховища документів і додаткової поверхні витоку даних перевізника.

Приклад запиту

POST /api/v1/pdf/render — мінімальна термоетикетка 4×6 зі штрихкодом 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" }
      }
    ]
  }]
}

Відповідність і conformance

  • GS1 General Specifications — ширина модуля (X-dimension), quiet zone і загальна довжина відповідають допускам GS1 Section 5.4 при 203 dpi.
  • Вимоги перевізників — UPS, FedEx, DHL і USPS приймають відрендерений вивід як сканований; додаткова обробка для кожного перевізника не потрібна.
  • PDF/A-2b доступний для архівування через `settings.profile = "pdfa-2b"`, якщо потрібно зберігати PDF етикетки з податкових або аудиторських причин.

Навантаження транспортних етикеток в одному абзаці

Кожне замовлення створює один PDF, кожен PDF один раз друкується на термопринтері, а режим відмови при повільній генерації — це не “сторінка повільно завантажується”, а “складський забір стоїть у черзі за вашим API рендерингу етикеток”. Доставка — це процес, де затримка p99 є головною продуктовою метрикою, де детермінований вивід важливий через регулярні передруки, і де якість штрихкоду — виміряна допусками GS1 X-dimension, а не пікселями — визначає, чи сканери прочитають етикетку з першого проходу.

PDF-стекам на основі headless-браузера важко одночасно закрити всі три вимоги: витрати холодного старту накопичуються під час піків, растрові штрихкоди деградують на малих термоетикетках, а растеризація шрифтів змінюється між версіями Chromium, тому “байтово ідентичний передрук” стає неможливим.

Чому gPdf підходить

Термоетикетка 4×6 невелика (576 × 864 пікселі при 203 dpi), має мало елементів (текстові блоки + 1-2 штрихкоди + необов’язковий логотип перевізника) і великий обсяг (середній 3PL рендерить 50 000-500 000 на день). Це саме те навантаження, для якого створено gPdf. Рендерер:

  1. Компілює макет один раз — координати сторінки, каскади шрифтів і геометрія штрихкодів визначаються під час запиту, а не через браузерний рушій макета.
  2. Векторизує кожен штрихкод — модулі малюються безпосередньо в PDF stream, тому GS1-128 шириною 30 мм читається чисто при 203 dpi або 600 dpi без растеризації з урахуванням DPI на вашому боці.
  3. Вбудовує NotoSans CJK + Latin — той самий payload коректно рендерить китайську назву перевізника без підготовки шрифтів у контейнері рендерингу.

p99 залишається рівним — 8 мс на нашому еталонному навантаженні (1 000 викликів прикладу вище в EU-WEST), незалежно від того, чи один isolate відрендерив одну етикетку, чи 10 000 етикеток.

Математика обсягу й вартості

Типовий середній 3PL працює приблизно з 50 000 етикеток/день, тобто близько 1,5 млн/міс. На Basic plan (5 USD/міс. за 100 000 сторінок, 0,00005 USD за сторінку перевищення) це:

1,5 млн сторінок × 0,00005 USD      = 75,00 USD перевищення
+ база плану Basic                  =  5,00 USD
──────────────────────────────────────────
разом                                = 80,00 USD/міс.

Те саме навантаження на Puppeteer-on-Lambda за типових налаштувань паралельності Lambda потрапляє в діапазон 200-400 USD/міс., ще до врахування витрат холодного старту під час піку.

Black Friday: робочий приклад

Піковий сплеск — це навантаження, де рендеринг на edge найчіткіше показує свою цінність. Роздрібний клієнт, який у першу годину Black Friday виходить на 200% звичайного обсягу етикеток — наприклад, 100 000 етикеток за 60 хвилин, у середньому 1 700 етикеток/хв і пікові сплески до 5 000/хв, — завершує роботу в межах одного пулу регіону Cloudflare Workers без витрат холодного старту. Те саме навантаження на прогрітому пулі Puppeteer, розрахованому на середній трафік, дає холодні старти 1,5-2,5 с на контейнерах, які запускаються для сплеску, і складський пункт забору відчуває кожен із них.

Куди дивитися далі

Читати далі