Report-showcase/.template/development/docs/adr/0002-data-and-assets.md

ADR-0002: Публичные, пользовательские и приватные ресурсы

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

Способ доставки через ZIP заменён папкой .private в ADR-0010. Граница публичных и приватных данных остаётся действующей.

Контекст

Внутренний шаблон Scientia содержит фирменные реквизиты, логотипы, имена, подписи, печати и материалы конкретного документа. Логотипы, адреса, имена и реквизиты разрешено распространять внутри компании. Реальные подписи и печати нельзя хранить в Git вместе с шаблоном.

Typst не читает ZIP напрямую и не умеет проверить наличие изображения без попытки его загрузить. Поэтому приватный архив должен быть внешним каналом доставки, а отсутствие ресурса должно моделироваться значением none.

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

1. Оставить всё в одном tracked-каталоге — максимально просто, но подписи и печати неизбежно распространяются с каждым форком.
2. Хранить приватные изображения в Git LFS — уменьшает основной репозиторий, но не устраняет доступ и историю распространения.
3. Хранить подписи и печати в отдельном ZIP — требует извлечения, зато отделяет приватный канал от шаблона.
4. Не поддерживать реальные изображения вообще — безопасно, но не покрывает подготовку финальных документов.

Решение

Выбрали три класса ресурсов:

• публичные фирменные данные и логотипы хранятся в .template/companies/;
• материалы конкретного документа хранятся в assets/;
• реальные подписи и печати поставляются отдельным private-assets.zip; проверенная задача извлекает их в .private/ и включает через sys.inputs только на время приватной сборки main.typ.

.private/ и private-assets*.zip исключаются через .gitignore. В репозитории остаются только нейтральные placeholders: векторный круг для печати и крест для подписи. При значении ресурса none renderer использует placeholder; указанный путь обязан существовать.

Последствия

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

Становится сложнее: для финального подписанного PDF нужно получить ZIP, извлечь его и явно указать пути.

Закрывает дверь на: хранение настоящих подписей и печатей в обычном Git, Git LFS или visual snapshots.