37 lines
3.3 KiB
Markdown
37 lines
3.3 KiB
Markdown
# 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.
|
||
|
||
**Закрывает дверь на**: молчаливое игнорирование неверно указанного пути к производственному ресурсу.
|