Initial commit

docs/private-assets.md

@@ -0,0 +1,108 @@
+# Приватные подписи и печати
+
+Настоящие подписи и печати хранятся только в локальной папке `.private`. Весь каталог исключён из Git, поэтому его можно целиком копировать между рабочими проектами с заменой.
+
+## Самый короткий сценарий
+
+1. Скопируйте готовую папку `.private` рядом с `main.typ`.
+2. В `main.typ` измените только один параметр:
+
+```typst
+#let use-private-assets = true
+```
+
+3. Пользуйтесь обычным предпросмотром Tinymist или нажмите `Ctrl+Shift+B`.
+
+Чтобы снова получить безопасную сборку без приватных изображений, верните `false`. При `false` Typst вообще не пытается открыть `.private/settings.typ`, поэтому чистый форк работает даже без каталога `.private`.
+
+## Структура папки
+
+```text
+.private/
+├── settings.typ
+├── scientia/
+│   ├── sign.png
+│   └── stamp.png
+├── technology/
+│   ├── sign.png
+│   └── stamp.png
+├── too/
+│   ├── sign.png
+│   └── stamp.png
+└── executors/
+    ├── Musikhin.png
+    ├── Guzeev.png
+    ├── Fedorov.png
+    └── ...
+```
+
+Необязательно хранить изображения всех компаний и сотрудников. Настройки должны включать только уже существующие PNG.
+
+## Настройки изображений
+
+Файл `.private/settings.typ` выглядит так:
+
+```typst
+#let settings = (
+  companies: (
+    scientia: (signature: true, stamp: true),
+    technology: (signature: false, stamp: false),
+    too: (signature: false, stamp: false),
+  ),
+  signatures: (
+    musikhin: (enabled: true, offset: 1.25cm),
+    guzeev: (enabled: true, offset: 1.4cm),
+    fedorov: (enabled: false, offset: 0.7cm),
+  ),
+)
+```
+
+- `signature` — использовать подпись организации `sign.png`;
+- `stamp` — использовать печать `stamp.png`;
+- `enabled` — использовать PNG сотрудника;
+- `offset` — индивидуальное смещение подписи по вертикали.
+
+Полная безопасная заготовка: [examples/private/settings.typ](examples/private/settings.typ).
+
+## Если подпись сотрудника ещё не получена
+
+Укажите `enabled: false` или совсем не добавляйте сотрудника в `settings.signatures`. В списке исполнителей сохранятся должность, ФИО, линия и свободное место для ручной подписи. Сборка не будет обращаться к отсутствующему PNG и не завершится ошибкой.
+
+Typst не умеет заранее проверить наличие файла без попытки его открыть. Поэтому `enabled: false` — явный и надёжный способ обозначить, что подписи пока нет.
+
+## Состав исполнителей и роли
+
+Состав конкретного отчёта задаётся в `main.typ`:
+
+```typst
+#let executors = (
+  report-executor("musikhin", role: "Ответственный исполнитель", private-settings: private-settings),
+  report-executor("guzeev", role: "Ведущий геомеханик", private-settings: private-settings),
+  report-executor("fedorov", private-settings: private-settings),
+)
+```
+
+Чтобы изменить роль сотрудника только в текущем документе, замените текст `role`. Если `role` не указан, используется обычная должность из справочника шаблона. Чтобы убрать сотрудника из отчёта, удалите или закомментируйте одну строку.
+
+## Справочник сотрудников
+
+| Идентификатор | ФИО | Обычная должность | PNG |
+|---------------|-----|-------------------|-----|
+| `musikhin` | Мусихин А.С. | Ответственный исполнитель | `Musikhin.png` |
+| `guzeev` | Гузеев И.А. | Главный геомеханик | `Guzeev.png` |
+| `fedorov` | Федоров Д.А. | Инженер-геомеханик | `Fedorov.png` |
+| `ilyasov` | Ильясов Б.Т. | Технический директор, к.т.н. | `Ilyasov.png` |
+| `khimichev` | Химичев С.С. | Инженер-геомеханик | `Khimichev.png` |
+| `brusnicin` | Брусницын И.В. | Инженер-геомеханик | `Brusnicin.png` |
+| `ozornin` | Озорнин Д.А. | Геолог | `Ozornin.png` |
+| `buhartdinov` | Бухартдинов А.С. | Главный маркшейдер | `Buhartdinov.png` |
+| `tkachenko` | Ткаченко А.С. | Инженер-геомеханик | `Tkachenko.png` |
+| `moshin` | Мошин В.Е. | Гидрогеолог | `Moshin.png` |
+| `mitrokhin` | Митрохин В.А. | Главный гидрогеолог | `Mitrikhin.png` |
+| `luzina` | Лузина М.В. | Геолог | `Luzina.png` |
+
+Справочник находится внутри `.template` и синхронизируется через Git. Он не содержит самих подписей или приватных настроек смещения.
+
+## Что попадает в Git
+
+`.gitignore` исключает каталог `.private/` целиком, включая `settings.typ`. Перед Push всё равно посмотрите список Source Control: настоящих PNG там быть не должно.