Initial commit

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

@@ -0,0 +1,36 @@
+# 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.
+
+**Закрывает дверь на**: молчаливое игнорирование неверно указанного пути к производственному ресурсу.