Building/.template/development/docs/adr/0004-error-handling.md

ADR-0004: Ранняя валидация и явные fallback-политики

Дата: 2026-08-26 Статус: Принято

Контекст

Ошибки Typst часто проявляются во время layout далеко от места, где пользователь передал неверное значение. Для бизнес-документа особенно опасны тихие fallback: неверная компания, отсутствующая сторона, незаметно пропавшая подпись или citation, не попавшая в список источников.

При этом распространяемый шаблон должен компилироваться без реальных подписей и печатей. Они поставляются отдельным ZIP; PowerShell task проверяет и извлекает архив, после чего запускает main.typ с явным sys.inputs. Typst 0.15 не предоставляет проверки существования файла без попытки загрузки.

Рассматриваемые варианты

1. Полагаться только на diagnostics Typst — мало кода, но сообщения не отражают доменный путь поля.
2. Всегда аварийно завершаться при любом отсутствующем ресурсе — строго, но шаблон нельзя удобно распространять без подписей.
3. Валидировать domain до layout и явно моделировать необязательные ресурсы — больше контрактов, зато ошибки предсказуемы.

Решение

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

Для подписи, печати и необязательных изображений поддерживаются политики:

• hide — не показывать ресурс и не резервировать место;
• placeholder — показать безопасную графическую заглушку: круг для печати или крест для подписи;
• reserve-space — оставить место для ручной подписи или печати.

Политика применяется только если поле равно none. Если поле содержит путь, но файл отсутствует, сборка завершается ошибкой.

Последствия

Становится проще: распространение шаблона, поиск причины ошибки и тестирование негативных сценариев.

Становится сложнее: каждый профиль обязан определить required/optional поля и defaults.

Закрывает дверь на: молчаливое игнорирование неверно указанного пути к производственному ресурсу.