labelgen

labelgen генерирует PDF-этикетки по XML-шаблонам draw.io и данным товара.

Проект поддерживает два режима работы:

1. CLI-режим: чтение данных из TOML и генерация PDF в локальную директорию.
2. HTTP API: приём JSON от другого микросервиса, генерация PDF, выдача ссылки и отдельного endpoint для скачивания PDF на печать.

Подробный HTTP-контракт описан в docs/api.md. Отдельная справка по KIZ и российскому DataMatrix описана в docs/kiz.md.

Возможности

• Рендеринг PDF по draw.io XML-шаблонам из директории templates.
• Подстановка бизнес-данных товара, атрибутов и даты печати.
• Поддержка EAN-13 и DataMatrix.
• Генерация многостраничного PDF: каждый элемент cis_list создаёт отдельную страницу.
• Синхронный HTTP API для генерации документа.
• Отдельный endpoint для скачивания готового PDF, пригодного для печати.

Структура проекта

• cmd/labelgen — CLI entrypoint и запуск HTTP-сервера.
• internal/api — HTTP API, контракты, сохранение metadata документа, скачивание PDF.
• internal/labeldata — внутренняя модель данных и загрузка из TOML.
• internal/renderer — рендеринг PDF, текста, штрихкодов и изображений.
• internal/mxgraph — парсинг XML draw.io и построение дерева элементов.
• templates — XML-шаблоны этикеток.
• examples/label.toml — пример входных данных для CLI.
• assets — шрифты и изображения, используемые при рендере.
• tools — вспомогательные утилиты для анализа PDF и шаблонов.

Требования

• Go 1.22+
• Шрифты в assets/fonts:
  • NotoSans-Regular.ttf
  • NotoSans-Bold.ttf
• Иконки и стэнсили в assets/stencils, если они используются конкретным шаблоном.

Быстрый старт

Сборка

go build -o labelgen.exe ./cmd/labelgen

Или через Makefile:

make build

Генерация PDF из TOML

go run ./cmd/labelgen --data examples/label.toml

Или через Makefile:

make run

По умолчанию PDF сохраняется в директорию output.

Запуск HTTP API

go run ./cmd/labelgen --serve :8080 --assets assets --templates-dir templates --output output

Или через Makefile:

make serve

После запуска доступны endpoints:

• GET /api/v1/health
• GET /api/v1/templates
• POST /api/v1/render
• GET /api/v1/documents/{id}/content

Форматы входных данных

TOML для CLI

Образец: examples/label.toml

Ключевые секции:

• date
• [meta]
• [assortment]
• [assortment.attr]
• [variant_attr]
• cis

JSON для HTTP API

HTTP API принимает бизнес-DTO, а не внутреннюю карту vars. Базовый пример:

{
  "template": "ШК 40x58 EAN13 Спорт.xml",
  "meta": {
    "description": "batch-42",
    "account": "altinfit"
  },
  "date": "13.03.2026",
  "assortment": {
    "just_name": "Топ спортивный с петлей в рубчик",
    "barcode": "4670383240957",
    "article": "ST0001"
  },
  "assortment_attributes": {
    "Состав": "Полиамид 82%, Эластан 18%",
    "Бренд": "ALTINFIT"
  },
  "variant_attributes": {
    "Цвет": "Черный",
    "Размер": "L(48)"
  },
  "cis_list": [
    {
      "full": "0104670383240957215(fIReCc7K3iz\u001D91AB12\u001D92dGVzdA=="
    }
  ]
}

Подробности по полям, ответам и скачиванию файла находятся в docs/api.md.

Генерация и скачивание PDF через API

1. Создание документа

curl -X POST http://localhost:8080/api/v1/render \
  -H "Content-Type: application/json" \
  -d @request.json

Пример ответа:

{
  "document_id": "c0ffee001122334455667788",
  "file_name": "ШК 40x58 EAN13 Спорт batch-42@altinfit.pdf",
  "download_url": "http://localhost:8080/api/v1/documents/c0ffee001122334455667788/content",
  "pages": 1
}

2. Скачивание PDF для печати

curl -L http://localhost:8080/api/v1/documents/c0ffee001122334455667788/content --output label.pdf

Endpoint отдаёт:

• Content-Type: application/pdf
• Content-Disposition: attachment; filename=...

Это позволяет другому сервису скачать готовый PDF и передать его в печать позже.

Makefile

Поддерживаемые цели описаны в Makefile:

• make build — сборка бинарника
• make run — запуск CLI на примере данных
• make serve — запуск HTTP API
• make test — запуск тестов
• make tidy — очистка go.mod/go.sum
• make clean — очистка сборки и PDF в output

Тесты

go test ./...

Или:

make test

Ограничения

• В HTTP API template должен быть только именем файла из директории templates, без путей.
• assortment.barcode валидируется как строка из 13 цифр.
• Каждый элемент cis_list создаёт отдельную страницу PDF.
• Каждый KIZ в cis_list должен быть crypto-protected GS1 DataMatrix в формате AI01 + GTIN14 + AI21 + Serial + GS + AI91 + Key + GS + AI92 + Crypto.
• Если assortment.barcode передан, он должен совпадать с EAN-13, извлечённым из GTIN внутри KIZ.
• Документы и metadata сейчас сохраняются в локальную output-директорию сервиса.
• download_url строится из Host и X-Forwarded-Proto/X-Forwarded-Host, поэтому за reverse proxy нужно корректно прокидывать эти заголовки.

Migration Guide

Если у вас уже есть клиент старого API, учтите breaking change в ответе POST /api/v1/render:

• было: file_path, pages
• стало: document_id, file_name, download_url, pages

Новый клиент должен использовать download_url или document_id для получения PDF вместо чтения локального file_path сервиса.

Troubleshooting

Не загружаются шрифты

Проверь, что в assets/fonts присутствуют NotoSans-Regular.ttf и NotoSans-Bold.ttf.

Шаблон не найден

Проверь, что template существует в templates и передаётся как имя файла, например ШК 40x58 EAN13 Спорт.xml.

PDF сгенерирован, но не скачивается

Проверь, что:

• output-директория не очищена после рендера
• metadata-файл документа не удалён
• document_id передаётся без изменений

Что дальше

Список следующих улучшений вынесен в TODO.md.