Неправильный размер этикетки может испортить штрихкод, обрезать адрес и остановить приемку товара. Источник ошибки бывает в шаблоне, DPI принтера, драйвере, настройке бумаги, автоматическом масштабировании PDF или переводе миллиметров в dots. Проверять нужно физический результат линейкой и тестовым штрихкодом, а не только предпросмотр на экране.

Зафиксируйте модель и DPI принтера, фактический размер носителя и способ печати. Напечатайте рамку известного размера без содержимого и измерьте ее. Это отделит масштаб всей страницы от ошибок расположения отдельных элементов.

Что проверить в первую очередь

Начните с одного воспроизводимого сценария. Зафиксируйте точное время, идентификатор объекта, пользователя или операции, версию приложения и последнее известное рабочее состояние. Не меняйте несколько параметров одновременно: один контролируемый шаг должен подтверждать или исключать одну гипотезу. Перед работой с данными и конфигурацией подготовьте резервную копию и проверенный способ отката.

  • Уточните реальный размер этикетки, зазора и ориентацию в миллиметрах.
  • Проверьте 203, 300 или 600 DPI устройства и выбранного драйвера.
  • Отключите Fit to page и другие автоматические режимы масштабирования.
  • Сравните прямую печать ZPL или TSPL и печать через PDF.
  • Выполните калибровку датчика носителя по инструкции производителя.

Почему возникает проблема

Внешний симптом часто появляется дальше по цепочке, чем первичная ошибка. Интерфейс может показывать неверное состояние из-за backend, очереди, кеша, прав доступа, фоновой задачи или внешнего API. Поэтому важно проследить данные от источника до результата и найти первую точку расхождения, а не исправлять только последнее сообщение об ошибке.

  • Шаблон рассчитан для 300 DPI, а отправляется на принтер 203 DPI без пересчета.
  • Браузер или PDF viewer масштабирует страницу под выбранный формат бумаги.
  • Драйвер имеет другой размер stock и добавляет поля.
  • Команды ширины и длины этикетки заданы в dots, но вычислены как миллиметры.
  • Принтер не откалиброван и неверно определяет начало следующей этикетки.

Пошаговая диагностика

Диагностику проводите на тестовой записи или отдельном окружении. В журналах скрывайте токены, пароли, персональные данные и содержимое документов. Для каждого шага сохраняйте измеримый результат: код ответа, версию записи, идентификатор события, состояние процесса, контрольную сумму или время выполнения. Так можно отличить подтвержденную причину от случайного совпадения.

  • Напечатайте прямоугольник 20 на 20 миллиметров и измерьте обе стороны.
  • Получите raw-команды или точный PDF page size перед отправкой.
  • Сверьте формулу dots = mm / 25.4 * DPI для всех размеров.
  • Проверьте настройки драйвера, spooler и самого принтера отдельно.
  • Просканируйте штрихкод верификатором или несколькими целевыми сканерами.

Единицы измерения в шаблоне печати

Макет должен иметь канонический физический размер, а преобразование в dots выполняться один раз под конкретное устройство.

  • Ширина, высота и безопасные поля задаются в миллиметрах.
  • Профиль принтера хранит DPI, язык команд и ограничения печатной области.
  • Генератор переводит координаты в integer dots по одному правилу округления.
  • PDF создается с точным page box без скрытых полей.
  • Штрихкод получает минимальный модуль и quiet zone, соответствующие печати и сканеру.

Как исправить проблему

Исправление делите на небольшие обратимые изменения. Сначала устраните подтвержденную причину, затем повторите исходный сценарий и проверьте соседние функции. Массовое обновление данных запускайте на ограниченной выборке с отчетом и только после сверки расширяйте на весь объем. Не отключайте авторизацию, проверку сертификатов, валидацию или аудит ради быстрого исчезновения симптома.

  • Исправьте профиль устройства и уберите жестко заданный DPI из шаблонов.
  • Задайте точный размер бумаги в драйвере и отключите масштабирование.
  • Для raw-печати пересчитайте все размеры и команды длины под DPI принтера.
  • Откалибруйте датчик и сохраните настройки носителя.
  • Добавьте печать контрольной шкалы и ID версии шаблона для диагностики.

Безопасный порядок внедрения

  • Сохраните затрагиваемые данные, конфигурацию и текущие журналы, затем проверьте возможность реального восстановления.
  • Повторите проблему на тестовом объекте без реальных списаний, рассылок и необратимых изменений клиентских данных.
  • Зафиксируйте изменение в системе контроля версий или журнале работ вместе с причиной, ожидаемым эффектом и планом отката.
  • Проведите тест на нормальном сценарии, ошибочном вводе, повторном запросе, параллельной операции и временной недоступности зависимости.
  • После выпуска наблюдайте полный пользовательский путь, логи и метрики, а не только один успешный запрос.

Как проверить результат

Разовый успешный тест недостаточен. Повторите операцию, проверьте крайние значения, одновременные действия и восстановление после перезапуска или временного сбоя. Для важного сценария сохраните автоматический тест либо короткий регрессионный чек-лист. Итог должен подтверждаться не только интерфейсом, но и состоянием базы, очереди, внешнего сервиса и журналом действий.

  • Контрольная рамка совпадает с физическим размером в пределах допуска оборудования.
  • Текст и штрихкод не выходят за безопасную область.
  • Первая и двадцатая этикетка имеют одинаковое положение без накопления сдвига.
  • Штрихкод читается целевым сканером под рабочим углом.
  • Шаблон корректно выбирает профиль для каждого разрешения принтера.

Типичные ошибки при исправлении

  • Компенсировать масштаб случайным CSS transform.
  • Проверять только preview PDF на мониторе.
  • Выбирать ближайший стандартный формат бумаги вместо точного пользовательского.
  • Уменьшать штрихкод до визуального попадания без проверки модуля и quiet zone.
  • Смешивать миллиметры, points, pixels и dots в нескольких слоях генерации.

Как предотвратить повторение

Профилактика строится вокруг явных контрактов, повторяемых релизов и наблюдаемости. Система должна не только работать сейчас, но и позволять быстро увидеть нарушение правила при следующем обновлении, росте нагрузки или сбое внешнего сервиса. Проверки особенно полезно автоматизировать там, где ошибка уже привела к потере времени, данных, денег или заявок.

  • Храните профили принтеров и тестовые отпечатки для каждого DPI.
  • Добавьте автоматическую проверку page size и границ элементов.
  • Печатайте версию шаблона мелким служебным полем.
  • Документируйте настройки драйвера и калибровки рабочего места.
  • Проверяйте шаблон после обновления браузера, PDF-библиотеки или драйвера.

Что контролировать после выпуска

  • Количество успешных и ошибочных операций в разрезе версии, канала и типа сценария.
  • Возраст необработанных записей, длину очередей, число повторных попыток и долю окончательных отказов.
  • Расхождение между пользовательским статусом и фактическим состоянием в базе или внешней системе.
  • Появление новых кодов ошибок после релиза и изменение времени выполнения ключевой операции.
  • Сигналы от поддержки и бизнес-метрики, которые могут показать скрытый частичный сбой.

Что подготовить для технического разбора

  • Описание ожидаемого и фактического поведения с точной последовательностью действий.
  • Время проблемы, идентификатор тестового объекта и версии затронутых компонентов.
  • Фрагменты журналов до и после ошибки без секретов и персональных данных.
  • Перечень последних изменений и уже выполненных проверок.
  • Безопасный доступ к тестовой среде либо способ воспроизвести сбой без влияния на клиентов.

Частые вопросы

Почему 100 пикселей не равны одному размеру на всех принтерах?

Физический размер зависит от DPI; термопринтер работает в точках головки, а не экранных CSS-пикселях.

Что лучше: PDF или ZPL?

Для поддерживаемого термопринтера raw-язык обычно дает более предсказуемый результат, но выбор зависит от инфраструктуры.

Можно ли исправить только драйвером?

Иногда да, если шаблон физически корректен. Сначала контрольная рамка покажет, где появляется масштаб.

Когда нужна помощь специалиста

Если этикетки обрезаются или печатаются не в масштабе, я могу проверить шаблон, PDF или raw-команды, профиль DPI и драйвер, затем подготовить точную печать и контрольный тест. Для оценки нужны модель принтера, размер носителя и пример файла.