> ## Documentation Index > Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Дополнительные поля > Собственные реквизиты компании в карточках системы: разделы и типы значений, глобальные поля платформы, уникальность имени, суточный кэш списка и два независимых поколения настройки — старый общий набор и новый справочник записей. Полный перечень полей — в [глоссарии дополнительных полей](/ru/logic/settings/custom-fields-glossary). Дополнительные поля — это механизм, которым компания расширяет типовые карточки системы своими реквизитами: к клиенту можно добавить «номер водительского удостоверения», к аренде — «сумма чаевых», к единице инвентаря — «номер рамы». Сама система от этого не меняется: она лишь знает, какие поля описаны, как они называются и как их показывать, а введённые значения складывает в служебное хранилище дополнительных данных внутри соответствующей карточки. Раздел устроен непривычно: у него **два поколения интерфейса** — старый набор полей, который целиком лежит внутри одной настройки компании, и новый справочник, где каждое поле является отдельной записью со своим идентификатором. Оба доступны одновременно и живут независимо друг от друга, поэтому понимать разницу критично. ## Модель данных Одна запись справочника описывает одно дополнительное поле одного раздела. | Поле | Тип | Назначение | | -------------------- | ------ | ----------------------------------------------------------------------------------------------------- | | Идентификатор | число | Номер записи; по нему работают операции чтения, изменения и удаления в новом интерфейсе | | Компания | связь | Владелец поля. Пустая привязка означает глобальное поле платформы | | Раздел | список | К карточкам какой сущности относится поле | | Имя поля | текст | Техническое имя, под которым значение сохраняется в карточке и подставляется в документы. Обязательно | | Подпись | текст | Название поля, которое видит пользователь. Обязательно | | Подсказка | текст | Текст-заполнитель внутри пустого поля; может отсутствовать | | Обязательное | флаг | Подсказка интерфейсу, что поле нужно заполнить | | Показывать в таблице | флаг | Поле выводится отдельной колонкой в списке раздела | | Доступно в фильтрах | флаг | По полю можно отбирать записи | | Тип значения | список | Как заполняется поле | | Варианты значений | список | Заранее заданный набор вариантов для выбора; по умолчанию пустой | Имя поля и подпись — разные вещи. Имя участвует в подстановке значений в шаблоны документов и в расчётах, поэтому переименование поля равносильно созданию нового: уже сохранённые в карточках значения останутся под старым именем и просто перестанут отображаться. ### Разделы Поле обязательно относится ровно к одному разделу. В новом справочнике доступны: клиент, услуга, инвентарь, автомобиль, самокат, мотоцикл, комплект, продукт, точка проката, категория, аренда, позиция аренды с инвентарём, позиция аренды с услугой, лид, мастерская, документ и шаблон документа. Разделы мастерской, документа, шаблона документа и три транспортных раздела (автомобиль, самокат, мотоцикл) появились только в новом справочнике — в старом наборе их нет. Обратная асимметрия тоже есть: в старом наборе присутствует раздел «документ клиента», которого в новом перечне разделов не существует. ### Типы значений | Тип | Что вводит пользователь | | --------------------- | --------------------------- | | Строка | Обычный короткий текст | | Форматированный текст | Текст с оформлением | | Целое число | Число без дробной части | | Дробное число | Число с дробной частью | | Да / нет | Флажок | | Дата | Календарная дата | | Дата и время | Момент времени | | Цвет | Значение цвета | | Ссылка на клиента | Выбор существующего клиента | | Ссылка на инвентарь | Выбор единицы инвентаря | | Ссылка на продукт | Выбор продукта | | Ссылка на комплект | Выбор комплекта | | Ссылка на услугу | Выбор услуги | | Ссылка на ремонт | Выбор записи мастерской | | Ссылка на документ | Выбор документа | | Ссылка на шаблон | Выбор шаблона документа | Последние восемь типов — ссылочные: пользователь не вводит значение вручную, а выбирает уже существующую запись, и в карточке сохраняется указатель на неё. Именно этим объясняется особое поведение документов: ссылочное поле аренды на клиента разворачивается в полноценный блок реквизитов выбранного клиента, а не в одно значение. Признаки «Обязательное», «Показывать в таблице» и «Доступно в фильтрах» — это указания для интерфейса. Ни один серверный обработчик их не читает: карточка сохранится и без заполненного обязательного дополнительного поля. ### Глобальные поля платформы и уникальность имени Если у поля не указана компания, оно считается глобальным: платформа заводит его один раз, и оно попадает в списки всех компаний. Правило уникальности действует только на поля компании: внутри тройки «компания + раздел + имя» повторов быть не может. На глобальные поля ограничение не распространяется, и оно не сравнивает поле компании с глобальным — поэтому в одном разделе может оказаться и своё, и платформенное поле с одинаковым именем, и оба вернутся в списке. ## Где хранятся значения Описание поля хранится в общей (платформенной) части базы и относится к компании целиком. Само же значение живёт в карточке той сущности, к которой поле привязано: у клиента, аренды, единицы инвентаря, продукта, точки проката и других — в их собственном хранилище дополнительных данных, под ключом, равным имени поля. Отсюда следуют два практических вывода: * удаление описания поля не стирает уже введённые значения — они остаются в карточках, но перестают быть видимыми; * преобразования данных при смене типа значения не предусмотрено: старые записи продолжают хранить прежний формат, а потребители (документы, расчёты по смене, метрики) будут интерпретировать их по новому типу. ## Кэш списка полей Список дополнительных полей запрашивается практически на каждом экране, поэтому он кэшируется агрессивно. * Для каждой компании существует свой ключ кэша, и в нём лежит уже готовый список: **поля компании плюс все глобальные поля платформы**, объединённые в один плоский перечень. * Срок жизни кэша — **сутки** (86 400 секунд). Это намеренное исключение: по умолчанию записи кэша в системе живут 15 секунд. * Вне контекста компании (когда запрос выполняется на общей части базы) список пуст. * Кэш компании очищается автоматически при сохранении и при удалении дополнительного поля этой компании. Сброс кэша привязан к владельцу записи. Если меняется глобальное поле платформы (без привязки к компании), ни один кэш компаний не очищается — правка расходится по компаниям только по мере естественного истечения суток. Порядок полей в списке ничем не задан: он определяется базой данных и может измениться после правок. Также по ответу нельзя отличить своё поле от глобального — признака принадлежности в выдаче нет, хотя редактировать можно только свои. Работа с кэшем «мягкая»: недоступность кэша не ломает запрос — сбой лишь записывается в журнал, а список читается напрямую из базы. Плата за это — рост нагрузки на базу при проблемах с кэшем. ## Два поколения настройки ### Старый способ: один объект по разделам Исторически все дополнительные поля компании передавались и хранились одним объектом, сгруппированным по разделам: продукт, комплект, инвентарь, услуга, клиент, документ клиента, точка проката, аренда, позиция аренды с инвентарём, позиция аренды с услугой, лид, категория. Внутри каждого раздела — простой список описаний полей без идентификаторов. Ключевые особенности: * сохранение **перезаписывает набор целиком**: разделы, которых нет в запросе, теряют свои поля, поэтому отправлять нужно всегда полную картину. Это верно и для частичного обновления — там недостающие разделы даже не подставляются пустыми, а просто исчезают из хранимого объекта; * у полей нет идентификаторов — «изменить одно поле» технически невозможно, список раздела всегда заменяется новым; * значение попадает в общую настройку компании и подчиняется общей механике настроек: запись в таблицу настроек плюс обновление короткоживущего кэша настроек; * набор типов здесь свой и короче: нет ссылок на ремонт, документ и шаблон, а ссылки на продукт и на комплект обозначаются иначе, чем в новом справочнике; * подпись можно не передавать — тогда она останется пустой, но явно переданная пустая подпись будет отклонена как ошибка. ### Новый способ: отдельные записи Новый интерфейс работает с полями как с обычным справочником: получить весь список, добавить одно поле, изменить одно поле, удалить одно поле. Список отдаётся без постраничной разбивки и берётся из суточного кэша, а операции с конкретной записью идут напрямую в базу и ищут запись **только среди полей текущей компании** — глобальные поля видны, но недоступны для изменения и удаления. Добавление поля через новый справочник сейчас не работает: при сохранении в поле «Компания» подставляется не компания, а перечень членств пользователя, и запрос завершается ошибкой сервера. Практически пригодны только чтение списка, правка и удаление уже существующих записей. Проверки при сохранении записи: раздел и тип обязаны быть из списков допустимых значений, имя и подпись обязательны, подсказка необязательна, а варианты значений должны быть списком. Состав вариантов и их соответствие типу значения не проверяются. Повтор имени в том же разделе понятной ошибки не даёт — это ограничение базы, и наружу оно выходит как сбой сервера. При переходе на новый справочник уже существующие наборы были однократно перенесены в отдельные записи: для каждой компании поля всех разделов превратились в записи, поля без имени пропускались, подпись при отсутствии подставлялась из имени, тип по умолчанию — строка. Постоянной синхронизации между двумя поколениями нет. ### Сравнение | Свойство | Старый набор | Новый справочник | | ------------------------- | ---------------------------------- | ---------------------------------------------------- | | Где хранится | Внутри одной настройки компании | Отдельные записи справочника | | Идентификатор поля | Нет | Есть | | Правка одного поля | Невозможна, заменяется весь раздел | Обычное редактирование записи | | Глобальные поля платформы | Не поддерживаются | Поддерживаются | | Разделы | 12, включая документ клиента | 17, включая мастерскую, документ, шаблон и транспорт | | Типы значений | 12 | 16 | | Кэш | Общий кэш настроек компании | Отдельный список полей на сутки | Два поколения не связаны между собой. Сохранение старым способом не создаёт записей в справочнике, а изменение записи в справочнике не меняет старый набор. Компания может увидеть одно и то же поле дважды или, наоборот, не увидеть в документах поле, которое есть в справочнике. ## Что читает остальная система Несмотря на существование справочника, все внутренние потребители дополнительных полей сегодня читают **старый набор**: * **Документы.** При генерации документа значения дополнительных полей клиента, аренды, инвентаря, продукта и точки проката подставляются в шаблон по имени поля; для инвентаря и продукта подстановка работает в строках табличной части документа. Для полей аренды со ссылочным типом «клиент» вместо одного значения подставляется целый блок реквизитов связанного клиента. К полям инвентаря документ дополнительно добавляет три встроенных значения: идентификационный номер (VIN), цвет и общий пробег. Если значения в карточке нет, в документ попадает заглушка из подчёркиваний. * **Смены.** При закрытии смены числовые дополнительные поля аренды (целые и дробные) суммируются по сменe и выводятся отдельными строками в итоговом сообщении о закрытии. * **Метрики скидок.** Числовые дополнительные поля аренды суммируются и возвращаются в отчёте по скидкам отдельным блоком. Смены и метрики берут только те поля, у которых заданы и имя, и тип, и только числовые типы. Документы такого отбора не делают и берут все описанные поля соответствующих разделов. В отчёте по скидкам числовые дополнительные поля аренды заявлены как дополнительные варианты сортировки, но при применении сортировка по ним отбрасывается — фактически упорядочить отчёт по такому полю нельзя. ## Права доступа Просмотр списка дополнительных полей доступен сотрудникам компании и субарендаторам. Любое изменение — создание, правка, удаление, а также сохранение старого набора — доступно только владельцу компании. Дополнительно действует общий контроль принадлежности к компании: запрос выполняется в контексте той компании, к которой пользователь действительно подключён, а пользователь без компании получает отказ ещё до обращения к данным. Отдельной страницы для дополнительных полей в административной панели платформы нет — глобальные поля заводятся не через интерфейс. ## Типичные сценарии **Добавить поле в карточку клиента.** Пока создание записи в новом справочнике не работает, рабочий путь один: владелец компании сохраняет старый набор целиком, добавив в раздел «клиент» новое описание. Так поле появится и в интерфейсе, и в подстановках документов. **Убрать поле.** Удаление описания скрывает поле из интерфейса и сбрасывает кэш справочника, но значения остаются в карточках. Если позже завести поле с тем же именем и в том же разделе, старые значения снова станут видны. **Платформа заводит поле для всех.** Глобальное поле сразу попадает в выдачу тех компаний, чей кэш ещё не прогрет, а остальные увидят его в течение суток. Компании смогут заполнять такое поле, но не смогут его переименовать или удалить, и в документы его значения не попадут — документы читают только старый набор. ## Подводные камни **Ломает работу или данные** * Создание дополнительного поля через новый справочник завершается ошибкой сервера: при сохранении в привязку к компании подставляется не сама компания, а перечень членств пользователя. * Старое и новое поколения хранят данные раздельно и не синхронизируются: сохранение старым способом не создаёт записей справочника, а операции со справочником не меняют настройку компании. * Все внутренние потребители — генерация документов, итоги смены, метрики скидок — читают только старый набор внутри настройки компании, поэтому поле, существующее только в новом справочнике, в документах и расчётах не появится. * Сохранение старым способом перезаписывает набор целиком: разделы, отсутствующие в запросе, теряют свои поля — при полном обновлении они становятся пустыми, при частичном исчезают из хранимого объекта совсем. * Изменение глобального поля платформы не сбрасывает кэш ни одной компании, поэтому правка расходится по компаниям только по мере истечения суточного срока жизни кэша. * Повтор имени поля в том же разделе не даёт понятной ошибки проверки: ограничение проверяет только база, и наружу это выходит как сбой сервера. **Ограничения, о которых стоит помнить** * Сброс кэша выполняется в том контексте компании, в котором произошло сохранение, а ключи кэша дополнительно разделяются по компаниям — правка из фонового или служебного контекста может очистить не тот ключ, который читают запросы пользователей. * Ограничение уникальности не действует для глобальных полей и не сравнивает поле компании с глобальным: в одном разделе могут сосуществовать одноимённые своё и платформенное поля, и оба попадут в список. * Глобальные поля видны в списке, но недоступны для изменения и удаления — операции с конкретной записью ищут её только среди полей текущей компании и отвечают «не найдено». * В выдаче списка нет признака принадлежности: по ответу нельзя понять, какое поле принадлежит компании, а какое платформе, хотя редактировать можно только свои. * Список полей отдаётся без сортировки — порядок определяется базой и может измениться после правок. * Наборы разделов и типов у двух поколений не совпадают, а перенос выполнялся в обход проверок: перенесённые записи могут хранить раздел «документ клиента» и старые обозначения продукта и комплекта, которых в новом перечне нет. * Признаки обязательности, показа в таблице и доступности в фильтрах нигде на сервере не читаются: карточка сохранится даже без заполненного обязательного дополнительного поля. * В старом формате подпись можно не передавать (тогда она останется пустой), но явно переданная пустая подпись отклоняется как ошибка. * При сохранении записи в новом справочнике раздел и тип проверяются по спискам допустимых значений, имя и подпись обязательны, а варианты значений должны быть списком; состав вариантов и их соответствие типу значения не проверяются. * Числовые дополнительные поля аренды заявлены как дополнительные варианты сортировки отчёта по скидкам, но при применении сортировка по ним отбрасывается — упорядочить отчёт по такому полю нельзя. * Отбор по заполненности имени и типа и по числовым типам делают только итоги смены и метрики скидок; генерация документов такого отбора не выполняет и берёт все описанные поля своих разделов. **Полезно знать** * Перенос старых полей в отдельные записи выполнен однократно при обновлении: поля без имени пропущены, подпись при отсутствии взята из имени, тип по умолчанию — строка, конфликты игнорировались; постоянной синхронизации нет. * Отдельной страницы для дополнительных полей в административной панели нет — глобальные поля платформы заводятся не через интерфейс администратора. * Список полей кэшируется на сутки, тогда как общий срок жизни записей кэша в системе — 15 секунд; это намеренное исключение. * Сбой кэша не ломает выдачу списка: ошибка только записывается в журнал, а данные читаются напрямую из базы, что увеличивает нагрузку при проблемах с кэшем. * Удаление описания поля не стирает уже введённые значения — они остаются в дополнительных данных карточек и снова станут видны, если создать поле с тем же именем в том же разделе. * Перевод внутренних потребителей на новый справочник подготовлен, но отключён: список полей по разделам сразу возвращает значение старой настройки, а заготовка чтения из справочника оставлена неактивной. ## Связанные страницы Полный перечень полей записи справочника, разделов и типов значений. Обзорная страница модуля со всеми разделами настроек компании. Полный перечень параметров компании, их значения по умолчанию и порядок чтения и сохранения. Как значение настройки попадает в базу, кэшируется по компаниям и почему правка сбрасывает кэш целиком. Как компания меняет названия разделов и статусов под свою нишу, включая формы слова. Сохранённый состав, порядок и ширина колонок отдельно по каждой таблице компании. Показ баннеров платформы внутри системы: частота, отметка о просмотре и исключения. Общий счётчик компании для номеров клиентов, артикулов инвентаря и номеров документов. Служебный экран платформы для просмотра и правки настроек компании со сбросом к умолчанию.