Document Platform v2: конструктор PDF-шаблонов с Cruise Pack плагинами

Крупный речной оператор + open-source @webshturm — туризм и документооборот. Document Platform v2: 9 LIVE PDF-шаблонов, 33 теста, генерация PDF ~3 сек end-to-end. 2026-04-28 — 2026-04-30. Менеджеры редактируют шаблоны без программистов, Cruise Pack опубликован на npm.

Менеджер открывает админку, перетаскивает блоки на PDF-шаблон, нажимает «Сохранить» — через 3 секунды обновлённый ваучер уходит клиенту. Document Platform v2 — конструктор шаблонов с визуальным редактором (PDFme Designer + GrapesJS) и плагинами для отраслевых блоков. Cruise Pack (@webshturm/pdfme-plugins-cruise-pack v0.1.0) — открытый набор плагинов: GroupedTable для таблицы кают, маршрут на карте, расписание стоянок.

Контекст

До Document Platform v2 каждый PDF-шаблон верстался вручную разработчиком: правка штампа, обновление цены на сезон или добавление нового поля занимали от одного до трёх часов рабочего времени IT-специалиста. Менеджеры не могли трогать шаблоны самостоятельно — любое изменение шло через code review и деплой. Это создавало постоянное бутылочное горлышко между маркетингом и разработкой: «поправить ваучер под акцию» означало ждать очереди задач несколько дней.

После запуска основной voucher-pipeline на Hatchet и Gotenberg (подробнее в блоге pdf-voucher-pipeline-hatchet-gotenberg) стало очевидно: генерация PDF автоматизирована, но редактирование шаблонов по-прежнему ручное. Уйти от этого бутылочного горлышка можно только одним способом — дать менеджерам визуальный редактор прямо в админке. Brainstorm прошёл 28–29 апреля 2026, реализация — 30 апреля. За три дня: от идеи до 9 живых шаблонов в продакшене и открытого npm-пакета.

Какие вызовы решены

Как редактировать шаблоны без программистов? PDFme Designer интегрирован как Svelte 5 компонент прямо в существующую админку. Drag-and-drop блоки, live preview в браузере, кнопка «Сохранить» — всё. Редактор передаёт сериализованный template-JSON на сервер, где он версионируется в БД. Разработчик нужен только при создании нового типа шаблона с нуля.

Как версионировать шаблоны с эффект-датами? Таблица voucher_templates работает по effective-date pattern: insert-only, поле valid_from. Резолвер на момент рендера выбирает max(valid_from) ≤ effective_date (дата события, не дата генерации). Старые версии шаблонов не теряются — ваучер, выписанный в апреле, при повторной генерации в июне будет использовать апрельский шаблон, а не новый. Это критично для документов с юридической силой.

Как рендерить с кириллицей и сложными таблицами кают? Gotenberg HTML→PDF с подключёнными шрифтами Geist Variable обеспечивает корректную кириллицу и предсказуемое межстрочное расстояние. Для сложных структур — GroupedTable plugin из Cruise Pack: вместо «table + colspan merge» на уровне HTML плагин принимает flat data с group-by ключом и сам строит таблицу с merge-ячейками верхнего уровня. Это решает проблему рендера Gotenberg с несовместимыми CSS-правилами для colspan.

Как переиспользовать плагины между двумя продуктами? Cruise Pack вынесен в отдельный open-source npm-пакет @webshturm/pdfme-plugins-cruise-pack. Оба продукта — Круизный флот и Прогулочный флот — подключают одну и ту же зависимость. Изменение плагина выходит одним релизом и применяется везде после npm update. Первый стабильный релиз 0.1.0 опубликован.

Как обеспечить pixel-perfect рендер без ручного тестирования? 33 unit-теста для каждого плагина в Cruise Pack включают snapshot-сравнение с baseline-PDF. Любое изменение рендера — визуальное или структурное — приводит к падению теста в CI до того, как изменение попадёт в продакшен. Регрессии отлавливаются автоматически.

Как опубликовать под scope @webshturm в npm? OTP-токен + npm publish --access public под организацией webshturm. Пакет уже доступен как @webshturm/pdfme-plugins-cruise-pack на npmjs.com. Versioning через semver: 0.1.0-alpha.0 в ходе разработки, stable 0.1.0 после прохождения всех 33 тестов.

Подход

1. PDFme Designer в админке через Svelte 5 wrapper-компонент: принимает initial template JSON и onSave callback. Designer монтируется в div, callback сериализует результат и POST’ит на /api/admin/voucher-templates. Вся логика хранения — на сервере, компонент не знает о БД.

2. Handlebars для динамических полей — двойные фигурные скобки ({{tour.name}}, {{customer.fio}}) в теле шаблона. Перед передачей в Gotenberg сервер компилирует template с реальными данными заказа через Handlebars.compile(). Менеджер видит в редакторе плейсхолдеры, в PDF — реальные значения. Поддерживаются helpers: форматирование даты, склонение числительных, условный рендер блоков (например, блок «Питание» показывается только если тариф включает питание). Это убирает необходимость создавать отдельный шаблон для каждого тарифного пакета.

3. Cruise Pack как отдельный npm-пакет — версионируемые плагины с собственной историей изменений. Путь: 0.1.0-alpha.0 в фазе разработки, стабилизация после 33 тестов, публикация 0.1.0 stable. Следующие плагины (маршрут на карте, расписание стоянок) выйдут в 0.2.0.

4. GroupedTable plugin — кастомная разработка @webshturm: принимает flat array данных и group-by ключ, рендерит таблицу с визуально merged строками верхнего уровня. Устраняет несовместимость Gotenberg с CSS border-collapse + rowspan в сложных таблицах кают.

5. Hatchet workflow voucher-render — вход: (template_id, effective_date, order_data). Шаги: резолвер max(valid_from), Handlebars compile, Gotenberg HTML→PDF, upload в Supabase Storage, возврат public URL. Полное время: ~3 секунды end-to-end.

6. 33 unit-теста в Cruise Pack — каждый плагин тестируется отдельно с fixture данными и snapshot baseline-PDF. Snapshot генерируется при первом запуске, фиксируется в git, при следующих запусках сравнивается побайтово. Отклонение → fail с diff.

7. Tag v0.1.0 + Apache 2.0 — открытая лицензия позволяет другим туроператорам использовать плагины бесплатно. Commercial support — отдельная услуга от @webshturm. Open-source как стратегия входящего маркетинга.

Результат

• 9 LIVE PDF-шаблонов в продакшене: 1 ваучер Круизного флота + 1 ваучер Прогулочного флота + 7 версий экскурсионного шаблона pf_excursion
• 33 unit-теста в Cruise Pack с автоматическими snapshot-проверками рендера — каждый плагин покрыт полностью
• ~3 секунды end-to-end от запроса до public URL PDF в Supabase Storage
• Open-source npm: @webshturm/pdfme-plugins-cruise-pack v0.1.0 — опубликован, доступен публично на npmjs.com
• Менеджеры обновляют шаблоны без code review и без участия разработчика — весь цикл в браузере
• Версионирование по effective-date: ни один исторический PDF не потеряет связь со своим шаблоном, даже если шаблон обновится завтра

Эффект для бизнеса

• Время правки шаблона: с 1–3 часов разработчика до 5–10 минут менеджера — прямая экономия на стоимости часа разработки
• IT не блокер для маркетинга — обновление сезонных штампов, цен и дат идёт без релиза кода, PR review и ожидания очереди задач
• Open-source spillover — npm-пакет потенциально привлекает других туроператоров с похожей нагрузкой документооборота: GroupedTable + маршруты на карте нужны всем, кто продаёт круизы. Это органический inbound-поток без рекламного бюджета

Что использовали

PDFme 5.x как движок шаблонов с поддержкой кастомных плагинов, Handlebars 4.x для компиляции динамических полей на сервере перед рендером, GrapesJS как дополнительный WYSIWYG для маркетинговых блоков, Hatchet TS SDK v1 для orchestration rendering workflow с retry и observability, Gotenberg 8 для HTML→PDF с корректной кириллицей через embedded шрифты, шрифты Geist Variable для предсказуемой типографики, кастомный Svelte 5 wrapper над PDFme Designer для интеграции в существующую SvelteKit 2 админку без конфликтов с runes-компонентами. Supabase Storage — хранение сгенерированных PDF с публичными URL. Пакет @webshturm/pdfme-plugins-cruise-pack 0.1.0 — собственная разработка @webshturm, опубликован публично на npm под лицензией Apache 2.0.

Что мы можем сделать у вас

Если у вас регулярно меняются документы — счета, договоры, ваучеры, гарантийные письма, акты — и каждую правку делает разработчик через код и деплой, мы строим конструктор шаблонов на базе PDFme + Handlebars за 2–4 недели. Редактор интегрируется в вашу существующую админку. Менеджеры получают drag-and-drop интерфейс, IT-команда перестаёт быть бутылочным горлышком. Собственный open-source плагин-пакет под вашу отрасль с полным тест-покрытием и документацией — отдельный проект на 1–2 месяца, публикуется под вашим npm-scope. Написать нам