Логика
Шаблон документа — это HTML-заготовка (договор, акт, счёт и т.п.) с плейсхолдерами вида «имя клиента», «сумма аренды» и т.д., которые при формировании конкретного документа автоматически заполняются данными заявки, клиента или инвентаря (см. «Плейсхолдеры шаблонов»). Шаблон принадлежит конкретной компании и управляется через отдельный раздел настроек — список, создание, редактирование и удаление.Таблица шаблонов физически общая для всех компаний, но каждая запись жёстко привязана к своей компании, а все запросы к списку и к одному шаблону дополнительно фильтруются по компании текущего пользователя. Одна компания не увидит и не сможет получить доступ к шаблонам другой компании через этот раздел.
Фильтр содержимого (какой инвентарь/услуги попадают в документ) и точки проката, к которым привязан шаблон, принимаются и сохраняются как есть, без проверки структуры и без проверки существования указанных ID — ответственность за корректность значений лежит на клиенте API.
Формат печатной страницы
Шаблон хранит собственные настройки печатной страницы, которые применяются при конвертации сформированного документа в PDF: формат (стандартный набор — A4, A3, A5, Letter и т.д. — или произвольный размер), реальную ширину и высоту в миллиметрах (по умолчанию 210×297 мм, формат A4), масштаб печати в процентах (по умолчанию 100%) и отступы страницы (по умолчанию 7,62 мм слева/справа, 25,4 мм сверху/снизу).Служебные поля
Компания-владелец шаблона проставляется автоматически при создании и не может быть указана клиентом API напрямую. Статус («Активен»/«Отключён») заменяет старый признак удаления, принятый в проекте в целом. Удаление шаблона — мягкое. Удаление через API переводит шаблон в статус «Отключён», а не уничтожает запись. Отключённый шаблон исчезает из списка и из карточки (обращение к нему возвращает «не найдено») и больше не может быть выбран при создании нового документа, но все документы, ранее сформированные по этому шаблону, остаются нетронутыми — раньше удаление шаблона уничтожало их вместе с ним.Из этого следует, что «удалить» шаблон безопасно: история документов компании не пострадает. Восстановить отключённый шаблон через этот раздел нельзя — он больше не доступен ни на чтение, ни на изменение.
Порядок отображения (позиционирование) шаблонов
Список шаблонов всегда сортируется по порядку сортировки по возрастанию (а не по дате создания). Изменение позиции работает по принципу «вставки со сдвигом»: когда у шаблона появляется или меняется порядковый номер, все остальные шаблоны этой же компании, чей номер больше или равен новому, сдвигаются на единицу вперёд.- Создание нового шаблона. Порядковый номер по умолчанию равен 0, поэтому новый шаблон, если не указать порядок явно, автоматически становится первым в списке.
- Осознанная перестановка. Чтобы переместить существующий шаблон на новую позицию, достаточно один раз изменить его порядковый номер — все шаблоны «после» него автоматически подвинутся.
- Любое другое сохранение. Если порядковый номер не изменился, соседей никто не двигает: переименование, правка содержимого, смена формата страницы и удаление (перевод в «Отключён») порядок не перенумеровывают.
Сдвиг всегда ограничен шаблонами своей компании. Ранее сохранение шаблона одной компании сдвигало порядок у шаблонов всех компаний платформы.
Поле порядка можно оставить незаполненным: пустое значение просто пропускает пересчёт соседей и ошибки не вызывает. Массовый сдвиг соседних шаблонов выполняется одной групповой операцией и не запускает то же правило повторно. Побочный эффект: у сдвинутых таким образом шаблонов дата обновления не меняется — обновляется только числовое значение порядка.
API управления шаблонами и права доступа
Раздел предоставляет два адреса: список и создание (без пагинации, всем сотрудникам с правом просмотра; создание требует права на добавление) и просмотр/редактирование/удаление одного шаблона по идентификатору (доступны просмотр, полное и частичное редактирование, удаление — с соответствующими правами).И список, и карточка одного шаблона строго ограничены компанией текущего пользователя: попытка обратиться к идентификатору шаблона другой компании вернёт «не найдено», а не ошибку доступа.
Особенности поведения
- Массовый сдвиг соседних шаблонов не обновляет дату последнего изменения у сдвинутых записей, хотя их числовой порядок меняется.
- Отключённый (удалённый) шаблон недоступен во всём разделе: он не отображается в списке, его карточка возвращает «не найдено», и создать по нему новый документ нельзя. Документы, созданные по нему ранее, продолжают жить.
- Сдвиг порядка соседей выполняется только при реальном изменении порядкового номера и только по шаблонам своей компании.
- Ограничение типа источника данных до значений «клиент»/«заявка на аренду» проверяется только при приёме запроса через API; на уровне базы данных это обычное текстовое поле.
- Поле «Создан пользователем» необязательно и не выставляется сервером автоматически из авторизованного пользователя — если значение передано, оно полностью доверяется тому, что прислал клиент.
- Поле «Точки проката» — просто список чисел без связи с таблицей точек проката и без проверки, что указанные точки существуют и принадлежат данной компании.
- Поле «Шаблон-первоисточник» не входит ни в короткий, ни в расширенный набор полей API — фактически неиспользуемое поле.
- Просмотр списка и карточки шаблона разрешён любому аутентифицированному сотруднику компании без отдельной проверки права «просмотр»; проверка прав применяется только к созданию, редактированию и удалению.