Best practice
==============

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

Типы данных
------------

При создании типа данных необходимо руководствоваться следующим правилом для **выбора типа родителя**:

 .. image:: _static/best_practice/01.png
       :width: 600
       :align: center

* **Кейс** - тип для хранения записи, статус которой изменяется в процессе жизненного цикла автоматически в ходе бизнес-процесса, или вручную (например, при использовании канбан-доски). Маркером того, что тип будет кейсом является необходимость прикрепления к нему процесса и указания при создании общей информации, атрибутов, ролей, статусов и матрицы прав.
* **Справочник** - тип для хранения наборов бизнес-данных, которые будут использоваться как статические данные для документов, не участвующие непосредственно в бизнес-процессах. Маркером того, что тип будет справочником является указание при его создании только общей информации и перечня атрибутов.
* **Документ** - TBD
* **Файл библиотеки документов** - TBD
* **Публикация** - TBD
* **Остальное** - иные созданные ранее типы данных.

Подробно о :ref:`типах данных<data_types>`

Формы
------

Подробно о :ref:`формах<best_practice_form>`


Атрибуты
---------

.. _best_practice_dual_layer_default:

Авто-заполнение из связанной сущности (Dual-Layer Default Pattern)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Данный паттерн применяется, когда нужно автоматически подставить значение атрибута из связанного объекта (например, из проекта в релиз), оставляя возможность пользователю изменить его вручную.

**Задача:**

Дочерний тип (например, Релиз) должен наследовать значение поля по умолчанию от родительской сущности (например, от связанного Проекта), но пользователь должен иметь возможность переопределить значение при необходимости.

**Решение — два слоя:**

.. list-table::
   :widths: 15 30 55
   :align: center
   :header-rows: 1
   :class: tight-table

   * - Слой
     - Механизм
     - Когда срабатывает
   * - **1. Уровень типа данных**
     - :ref:`Вычисляемый атрибут<count_attributes>` типа **Attribute**, метод хранения **On empty**
     - При создании записи: если поле пустое — подтягивается значение из атрибута связанного объекта
   * - **2. Уровень формы**
     - Компонент формы с чекбоксом **«Текущий пользователь по умолчанию»**
     - Резервный вариант: если атрибут связанного объекта тоже пустой — подставляется текущий пользователь

**Конфигурация вычисляемого атрибута (слой 1):**

Перейдите в тип данных → вкладка **Атрибуты** → раздел **Вычисляемые атрибуты** и добавьте атрибут со следующими параметрами:

.. list-table::
   :widths: 25 75
   :align: center
   :class: tight-table

   * - **Тип**
     - ``Attribute``
   * - **Значение**
     - Путь к атрибуту связанной сущности, например: ``project.responsible?id``
   * - **Метод хранения**
     - ``On empty`` — значение записывается только если поле ещё не заполнено

.. tip::

   Тип ``Attribute`` поддерживает глубокую вложенность через точку. Например, если у типа «Релиз» есть ассоциация ``project`` (ссылка на «Проект»), а у «Проекта» есть атрибут ``responsible``, то путь будет: ``project.responsible?id``

   Подробнее о синтаксисе вложенных атрибутов см. :ref:`Вычисляемые атрибуты<count_attributes>`.

**Конфигурация формы (слой 2, резервный):**

Если нужен дополнительный резервный вариант (например, подставить текущего пользователя, если атрибут в связанном объекте тоже не заполнен), настройте форму:

1. Откройте форму типа данных в редакторе форм.
2. Найдите компонент нужного поля (например, «Ответственный»).
3. Перейдите на вкладку **«Кастомные»** компонента.
4. Установите чекбокс **«Текущий пользователь по умолчанию»**.
5. Сохраните компонент и форму.

.. note::

   Слой формы работает только при открытии формы создания в браузере и не влияет на программные мутации через Records API. Для надёжного резерва лучше полагаться на слой типа данных.

**Пример: Ответственный в Релизе из Проекта**

Сценарий: тип «Релиз» связан с типом «Проект» через атрибут ``project``. При создании релиза поле «Ответственный`` должно автоматически заполняться значением поля ``responsible`` из связанного проекта.

Вычисляемый атрибут в типе «Релиз»:

.. code-block:: yaml

   # В YAML-определении типа данных (секция computedAtts)
   - id: responsible
     type: ATTRIBUTE
     config:
       attribute: "project.responsible?id"
     storingType: ON_EMPTY

**Порядок применения значений по умолчанию:**

.. code-block::

   Создание записи
        │
        ▼
   [Слой 1] Вычисляемый атрибут (On empty)
        │  project.responsible?id → значение из проекта
        │
        ▼ (если атрибут проекта пуст)
   [Слой 2] Форма: «Текущий пользователь по умолчанию»
        │
        ▼
   Поле заполнено / пользователь может изменить вручную

**Преимущества паттерна:**

* Значение заполняется автоматически — пользователю не нужно вводить его вручную в большинстве случаев.
* Значение остаётся редактируемым — поле не «заморожено», пользователь может изменить его при необходимости.
* Метод хранения ``On empty`` гарантирует, что однажды установленное значение не будет перезаписано при последующих изменениях записи.
* Слои независимы: слой типа данных работает всегда (включая программные мутации), слой формы — только в UI.

См. также: :ref:`Вычисляемые атрибуты<count_attributes>` | :ref:`Типы данных<data_types>`

Шаблон уведомления
-------------------

Подробно о :ref:`шаблонах уведомлений<notification_templates>`