DEV Community: DOKIVO (Докиво)

Водяной знак вышел за границы PDF: почему проверка текста этого не заметила

Dmitry K — Fri, 30 Oct 2026 11:56:58 +0000

Команда DOKIVO (Докиво)

В цепочке «изображение → PDF → пометка “Копия”» оба шага завершились успешно, результат скачался, а извлечение текста вернуло нужное слово. Но на маленькой странице часть надписи оказалась за краем. Рассказываем, как разделили проверку содержимого и проверку его видимости.

Это разбор исправления в DOKIVO от 30 октября 2026 года. Примеры взяты из нашей контролируемой проверки, а не из документов клиентов.

Как получился ложный успех

У проблемного PDF страница была размером 120 × 80 пунктов. Это размеры страницы документа, не ширина окна браузера и не разрешение исходной фотографии.

Для центральной надписи использовался фиксированный размер шрифта 28 пунктов. Размещение, которое выглядит нормально на большом листе, оказалось неподходящим для маленькой страницы. В PDF при этом сохранялся весь текст «Копия» — наличие символов в документе не означало, что они целиком попадали в видимую область.

Проверка «нашли нужную строку в извлечённом тексте» ответила на свой вопрос правильно. Ошибка была в выводе: из наличия строки мы ожидали её полной видимости.

Исправление: учитывать страницу и ширину строки

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

Числа символов для такой задачи недостаточно: «ШШШ» и «111» могут занимать разную ширину. В pdf-lib ширину строки можно получить методом widthOfTextAtSize.

Для понимания геометрии полезна простая модель. Пусть неповёрнутый прямоугольник текста имеет ширину w, высоту h, а угол поворота равен a. Его габариты после поворота:

rotated_width  = abs(w * cos(a)) + abs(h * sin(a))
rotated_height = abs(w * sin(a)) + abs(h * cos(a))

По этим габаритам можно ограничить масштаб и затем разместить надпись с запасом от краёв. Однако высота прямоугольника — лишь приближение: базовая линия, выносные элементы и метрики конкретных глифов требуют проверки конечного PDF. Формулы выше объясняют принцип, но не заменяют проверку реального шрифта.

Что проверять в готовом файле

Мы разделили проверки на три уровня.

Содержимое. В документе есть ожидаемое слово. Это ловит потерянную или неверную пометку, но само по себе не ловит обрезание.

Геометрия. Получаем прямоугольники символов из готового PDF и сравниваем с границами страницы. Если хотя бы один символ выходит за край, проверка завершается ошибкой. Для извлечения границ подходит, например, PdfTextPage.get_charbox в pypdfium2. При этом координаты символов и границы страницы нужно привести к одной системе координат.

для каждого символа пометки:
    проверить left >= 0 и bottom >= 0
    проверить right <= page_width и top <= page_height

Это упрощённый пример для страницы без дополнительного поворота и смещённой области обрезки. Для произвольного PDF следует отдельно учитывать поворот и действующую видимую область. Переносить такой псевдокод в обработчик любых документов без этих оговорок нельзя.

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

Что получилось в нашем случае

После исправления повторили полный путь в браузере: загрузка изображения, создание PDF, добавление «Копия», скачивание результата. Сделали два запуска — при ширине интерфейса 1440 и 390 пикселей. Это проверка двух размеров интерфейса, не испытание физического телефона.

В обоих скачанных PDF:

страница сохранила размер 120 × 80 пунктов;
все пять символов «Копия» оказались внутри страницы;
проверка структуры qpdf прошла;
при просмотре рендера исходное изображение и полная пометка были видны.

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

Проверка, которую стоит оставить в обработчике

Успешный статус задачи, корректная структура PDF и найденная строка отвечают на разные вопросы. Для функции, которая наносит видимую пометку, нужны ещё границы символов и просмотр итоговой страницы.

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

Этот случай возник при разработке готовых сценариев DOKIVO. Сценарий объединяет последовательные операции над файлом; качество результата каждой операции всё равно нужно проверять отдельно.

Текст подготовлен с помощью ИИ по исходникам и сохранённым результатам проверки команды DOKIVO. Описанный результат относится к указанным контрольным файлам.

Лимит изображения в пикселях и лимит в байтах — две разные проверки

Dmitry K — Thu, 29 Oct 2026 14:50:57 +0000

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

В DOKIVO (Докиво) «Изменить размер» вписывает JPG, PNG или WebP в заданные границы с сохранением пропорций. Разберём, как принять такой результат для сайта, каталога или формы загрузки.

Зафиксируйте оба ограничения

Запишите допустимые ширину, высоту, формат и размер файла. Уточните, требуется ли точный размер или достаточно не превышать границу. «Не шире 1200 пикселей» и «ровно 1200 × 1200» — разные требования.

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

Рассчитайте ожидаемые пропорции

Для исходника 2400 × 1600 и предела 1200 × 1200 коэффициент уменьшения равен 0,5. Ожидаемый результат вписывания — 1200 × 800, а не квадрат 1200 × 1200. Это расчёт пропорций, не результат проведённой конвертации.

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

Настройте преобразование

В DOKIVO ширина обязательна, высота задаёт дополнительную границу. Добавьте изображение, укажите ширину, при необходимости высоту и откройте сравнение до и после. Смотрите на надписи, тонкие линии и мелкие детали объекта.

Уменьшение числа пикселей не задаёт точный размер файла в байтах. На объём влияют формат, содержимое и параметры кодирования. Не обещайте получателю «меньше 500 КБ» только по расчёту ширины: нужно проверить фактический файл.

Приёмка состоит из двух этапов

Сначала откройте скачанное изображение и проверьте его ширину, высоту, пропорции и читаемость. Затем проверьте размер файла и попробуйте обычную загрузку в целевую форму. Успешное преобразование ещё не означает, что форма примет все остальные свойства.

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

Материал команды DOKIVO, подготовленный с помощью ИИ. Описание инструмента сверено 29 октября 2026 года. Геометрический пример расчётный; заявлений о новом испытании скорости или качества нет.

Сравнение двух XLSX: сначала ключ строки, потом список изменений

Dmitry K — Thu, 29 Oct 2026 14:49:23 +0000

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

Мы — команда DOKIVO (Докиво). В «Сравнить таблицы Excel» используем явно заданные пары столбцов и от одного до трёх ключей. Статья объясняет границы такой сверки; это не новый тест скорости или точности.

Выберите идентичность записи

Для товарной выгрузки ключом может быть артикул. Если одна и та же позиция встречается на нескольких складах, одного артикула недостаточно: понадобится сочетание «артикул + склад». Ключ должен соответствовать смыслу строки.

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

Явно сопоставьте столбцы

В DOKIVO выбираются исходный и новый XLSX, по одному листу, строки заголовков и пары столбцов. Проверьте направление: «исходный → новый» определяет смысл добавленных и удалённых записей.

Если в новом файле столбец переименовали, сопоставьте его по содержанию. Совпадение позиции столбца не гарантирует одинаковую семантику. Прежде чем принимать отчёт, проверьте одну известную неизменную запись и одно ожидаемое изменение.

Не скрывайте неоднозначные ключи

Пустые и повторяющиеся ключи DOKIVO показывает как неоднозначность. Автоматического слияния дубликатов нет. Решение «взять первую строку» может потерять реальные данные, поэтому причину повторов нужно разобрать в исходной таблице.

Типы, ведущие нули, пробелы и регистр не нормализуются автоматически. Значения 0012 и 12 нельзя объявить равными без знания предметной области. Если нормализация нужна, зафиксируйте её как отдельное преобразование и сохраните исходные файлы.

Прочитайте полный отчёт

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

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

Хорошая приёмка включает четыре вещи: верно выбраны версии, ключ соответствует записи, неоднозначности разобраны, найденные изменения проверены на исходных адресах. Одного большого числа в сводке недостаточно для решения, какая выгрузка правильная.

Материал команды DOKIVO, подготовленный с помощью ИИ. Контракт публичного инструмента сверён 29 октября 2026 года. Значения и сценарий иллюстративные; независимый бенчмарк не проводился.

Повтор запроса к файловому API: почему один XLSX ещё не означает одну операцию

Dmitry K — Wed, 28 Oct 2026 15:05:08 +0000

Автор: Команда DOKIVO (Докиво)

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

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

1. Ключ относится к намерению, а не к HTTP-попытке

Намерение — это конкретный набор файлов, параметры и версия сценария. Ключ для него нужно сохранить до первого запроса. Если создавать новый UUID при каждом сетевом повторе, сервер увидит разные операции.

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

Действие клиента	Ожидаемый результат
Первый запрос с новым ключом	Новый запуск
Точный повтор с прежним ключом	Тот же идентификатор запуска
Изменённый файл с прежним ключом	Конфликт `409`, а не молчаливая новая обработка
Новое осознанное задание	Новое намерение и новый ключ

Это важно и для n8n. Повтор узла внутри одного выполнения и запуск всего workflow заново — разные ситуации. Во втором случае источник должен передать сохранённое намерение вместе со своим стабильным идентификатором события. Иначе даже правильно устроенный шаблон создаст новое задание.

2. Потерянный ответ — отдельное состояние

После тайм-аута нельзя автоматически считать, что запрос не принят. В нашем контракте предусмотрено чтение запуска по прежнему ключу: GET /api/v1/runs/by-key с заголовком Idempotency-Key.

Схема восстановления клиента выглядит так:

сохранить намерение
отправить запрос один раз
если получен runId:
    читать состояние этого запуска
если исход отправки неизвестен:
    искать запуск по сохранённому ключу
    если найден — продолжить чтение
    если не найден за ограниченное число проверок:
        сохранить состояние «исход неизвестен»
        не создавать новый ключ автоматически

Это схема поведения, а не готовый SDK. В частности, 404 при первом поиске не всегда позволяет заключить, что первоначальная отправка точно не состоялась. В проверенном шаблоне число проверок ограничено; неопределённость сохраняется явно, вместо бесконечного цикла или повторной обработки вслепую.

3. Готовый файл может требовать проверки

В приёмочном примере обрабатывались три учебных PDF-спецификации. Результат содержал четыре извлечённые строки: два файла включены, один исключён из-за несовпадения схемы. XLSX был доступен, но запуск имел состояние needs_attention.

Для интеграции это отдельная ветка: сохранить отчёт и направить его на проверку. Условие «файл скачался» не должно автоматически превращать частично обработанную партию в полностью принятую.

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

4. Подпись уведомления не устраняет дубли

Уведомление может прийти повторно, например если получатель успел принять его, но отправитель не увидел успешный HTTP-ответ.

В проверенном контракте подпись вычисляется как HMAC-SHA256(secret, timestamp + "." + rawBody). Получатель проверяет исходные байты тела, время и идентификатор события. Повторная сериализация уже разобранного JSON для вычисления подписи может изменить байты: пробелы и переносы тоже имеют значение.

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

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

5. Срок хранения ключа и файла — разные сроки

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

Поэтому восстановление спустя несколько часов может корректно найти прежний запуск, но уже не получить его файл. Автоматически запускать обработку заново в этой ситуации — новое бизнес-решение, которое нельзя незаметно спрятать в сетевой retry.

Что показала приёмка

В сохранённых проверках от 28 октября 2026 года:

точный повтор API-запроса возвращал прежний runId, изменённые байты с тем же ключом давали 409;
два выполнения импортированного шаблона в n8n 2.45.4 с сохранённым намерением возвращали тот же запуск и одинаковые байты XLSX;
исходящий HTTPS webhook пережил два ответа 503, затем получил 200;
результат с частичным включением файлов оставался needs_attention, а содержимое XLSX проверялось независимо от интерфейса.

Приёмник n8n проверялся в изолированном окружении по loopback, а исходящая HTTPS-доставка — отдельно. Публичную установку n8n клиента и запись в его CRM эти проверки не охватывали. Проверки разных участков нельзя складывать в утверждение о гарантии «ровно один раз» для всей внешней системы.

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

Материал подготовлен с помощью ИИ по документации и сохранённым результатам проверок проекта. Новые испытания специально для статьи не запускались. Коммерческих предложений и партнёрских ссылок в статье нет.