Сначала разделите два случая: QR отсутствует на странице PDF либо виден, но не читается. При исчезновении проверьте загрузку ресурса и печатный макет. При неудачном чтении исследуйте масштаб, поля и само закодированное значение. Генерация нового QR не исправит CSS, который скрывает старое изображение при печати.
Браузерный preview не равен печатному режиму
Puppeteer Page.pdf по умолчанию использует CSS media type print; документация проверена 25 октября 2026 года. Поэтому видимый на экране элемент может пропасть из-за правил @media print, размеров контейнера, обрезки или положения за границей страницы. Сверьте режим, в котором действительно формируется файл.
| Симптом | Что сравнить |
|---|---|
| Пустое место вместо QR | Доступность и декодирование изображения |
| QR есть в screen, нет в print | Печатные стили и видимость |
| Часть QR срезана | Размеры и overflow контейнера |
| В PDF виден, сканер молчит | Поля, масштаб и контраст |
| Сканируется чужая ссылка | Данные генерации и ключ кеша |
Ресурс должен быть доступен процессу рендера. Локальный путь на компьютере автора, защищённый URL без нужного контекста или временная ссылка с истёкшим сроком могут работать в одном preview и отказать на сервере. Используйте утверждённый способ доставки ресурса, а не расширяйте доступ всему каталогу изображений.
Готовность QR проверяется до сохранения PDF
Условная цепочка проверки:
payload -> ожидаемое тестовое значение
asset -> QR создан и относится к этому выпуску
HTML print -> ресурс загружен, декодирован и видим
layout -> код целиком внутри страницы
PDF -> изображение присутствует
decode -> прочитано именно ожидаемое значениеСлучайная задержка в несколько секунд не является надёжным признаком готовности. Нужен явный контроль завершения ресурса в используемом рендерере. Если QR рисуется асинхронно в canvas или вставляется после запроса, учитывайте завершение этого шага; событие загрузки исходного HTML может произойти раньше.
Для параллельных выпусков не используйте один общий qr.png, который следующая задача перезапишет до чтения предыдущей. Свяжите артефакт с выпуском и его данными. В общий журнал не помещайте секреты и рабочие идентификаторы из payload; диагностику выполните на искусственной ссылке или тестовой строке.
Видимый код всё равно нужно прочитать
DENSO WAVE указывает для обычного QR Code свободную зону шириной четыре модуля с каждой стороны. Источник проверен 25 октября 2026 года. Модуль — клетка кода, поэтому фиксированное поле в миллиметрах без учёта размера модуля не выражает это правило. Рамка таблицы или подпись не должна занимать свободную зону.
- Проверить исходный QR отдельным декодированием.
- Открыть итоговый PDF и найти весь символ.
- Прочитать код с финальной страницы, сравнить значение.
- Проверить печать в предусмотренном масштабе.
- Повторить два параллельных выпуска с разными тестовыми данными.
Не оценивайте успех только по чёрно-белому квадрату на экране. При сильном уменьшении или неудачной обработке изображения клетки теряют различимость. Конкретный размер подбирайте по реальному процессу просмотра и печати; универсальное обещание чтения любым телефоном было бы необоснованным.
Для диагностики сохраните искусственный payload, ресурс QR, HTML печатного режима и финальный PDF с версией рендера. Результат исправления проверяем: символ есть на нужной странице, целиком помещается в макет и возвращает ожидаемое значение после той же обработки, через которую проходит выдаваемый документ.