Конструктор форм (List/Edit Templates)

Назначение

Декларативное описание UI-форм для просмотра списков и редактирования сущностей и документов в Employee API. Разработчик создаёт пару шаблонов (ListTemplate + EditTemplate), описывая колонки, фильтры, поля, таблицы и действия. Фреймворк автоматически разрешает типы, заголовки и значения через рефлексию и локализацию. Фронтенд получает шаблон + данные в едином ответе и отрисовывает форму без знания о конкретной сущности.

Иерархия описания полей

Param (abstract)
 └── EntityField<E>                     — поле сущности (fieldName, поддержка вложенности через ".")
      ├── ReadableField<E>              — чтение значения (valueGetter или рефлексия)
      ├── UpdateableField<E>            — запись значения (valueSetter или рефлексия)
      ├── ReadOnlyField<E>              — динамическое read-only
      ├── RequiredField<E>              — динамическая обязательность
      ├── FieldWithAvailableValues<E>   — список допустимых значений
      ├── FieldWithAdditionalData<E>    — вложенная таблица
      └── FieldWithRelatedField         — каскадная зависимость от другого поля

Типы полей (ParamType)

Тип	Отображение
TEXT	Текстовое поле
INTEGER	Целое число
FRACTIONAL_NUMBER	Дробное число (BigDecimal)
DATE	Дата (LocalDate)
DATE_TIME	Дата и время (LocalDateTime)
BOOLEAN	Чекбокс
SELECT	Выпадающий список (одно значение)
MULTISELECT	Множественный выбор
ENTITY	Ссылка на справочник
DOCUMENT	Ссылка на документ
SKU_PACKAGING	Виджет выбора упаковки товара
SKU_BATCH	Виджет выбора партии
WAREHOUSE_SPACE	Виджет выбора складского места
GROUP	Группировка вложенных полей
BASE64	Бинарные данные

Автоматическое определение: Integer/Long → INTEGER, BigDecimal → FRACTIONAL_NUMBER, LocalDateTime → DATE_TIME, Enum → SELECT, BaseDoc → DOCUMENT, BaseEntity → ENTITY.

Шаблон списка

Компоненты

Компонент	Класс	Роль
Колонка	ListColumn<E>	Отображение значения, сортировка, ссылка на редактирование
Фильтр	ListFilterParam<E>	Фильтрация по значениям, автоматическая генерация JPA Specification
Действие	ListAction	Массовые операции над выбранными записями

Автоматическая генерация фильтров

Тип поля	Генерируемый фильтр
Enum	IN (множественный выбор из списка значений)
String	LIKE (поиск по подстроке)
Boolean	isTrue / isFalse
Entity-ссылка	IN по ID
Date	dateFrom / dateTo (диапазон)
DateTime	datetimeFrom / datetimeTo

Сортировка

• Для enum-полей: автоматический CASE WHEN по локализованным значениям
• Для обычных полей: прямая JPA Criteria сортировка
• Кастомная: через sortExpressionGetter

Шаблон формы редактирования

Компоненты

Компонент	Класс	Роль
Поле	EditFormField<E>	Ввод/отображение значения, все интерфейсы поведения
Таблица	EditFormTable<E, I>	Табличный блок (позиции документа), CRUD строк
Колонка таблицы	EditFormTableColumn<E, I>	Колонка в табличном блоке
Действие	EditFormAction<E>	Операция из формы (смена статуса и т.п.)
Файлы	EditFormFileList<E, F>	Блок файлов (загрузка, скачивание, удаление)

Алгоритм сохранения (saveEntity)

1. Загрузка существующей сущности (по ID) или создание новой (createEntity())
2. Проверка привилегий на обновление
3. Разбор параметров запроса, проверка обязательных полей, удаление read-only
4. Для каждого параметра: valueSetter → additionalDataTable → рефлексия
5. Обработка таблиц: сопоставление строк по ID, создание/обновление/soft-delete
6. beforeEntitySaved() → saveEntity() → afterEntitySaved()

Базовые классы

Иерархия списков

BaseEntityViewTemplate<S, E>        — общая основа (рефлексия, локализация, контроль доступа)
 └── BaseEntityListTemplate<S, E>   — списки (фильтры, колонки, действия, пагинация)
      └── BaseDocListTemplate<M, ES, D, S> — списки документов (статусы, humanId, раскраска)

Иерархия форм

BaseEntityViewTemplate<S, E>
 └── BaseEntityEditTemplate<S, E>   — формы (поля, таблицы, действия, файлы)
      └── BaseDocEditTemplate<M, ES, D, S> — формы документов (статус, сохранение через DocManager)

Жизненный цикл шаблона

1. Конструктор → init() → addDefaultsToTop() (стандартные поля/колонки сверху)
2. Код наследника в конструкторе (свои поля/колонки)
3. @PostConstruct → addDefaultsToEnd() (стандартные поля/колонки снизу)

Автоматические возможности

Функция	Механизм
Определение типа поля	Рефлексия по Java-типу
Заголовок поля	entities_ru.properties по ключу ClassName.fieldName (с подъёмом по иерархии)
Значение поля	Introspector / bean-property getter
Допустимые значения	Автоматически для enum-полей (с локализацией)
Обязательность	По аннотациям @NotNull / @NotBlank
Раскраска статусов	Первый=серый, последний/DONE=зелёный, CANCELED=серый, ERROR=красный

Готовые группы полей

• addDimensionsFieldGroup — ширина/высота/глубина
• addPersonFieldGroup — ФИО/телефон/email
• addLegalEntityFieldGroup — название/ИНН/КПП/ОГРН
• addAddressFieldGroup — страна/регион/город/.../полный адрес

API контроллеры

EntityController (/employee-api/entities)

Метод	Endpoint	Описание
GET	/types	Типы сущностей по категориям (ORGANIZATIONS, EMPLOYEE, SKU, WAREHOUSE, OTHER)
GET	/	Быстрый поиск по типу и строке
GET	/list/template	Шаблон колонок, фильтров, действий
POST	/list	Данные списка с пагинацией
POST	/list/action	Выполнение действия над записями
GET	/edit/template	Шаблон формы + данные
POST	/edit	Сохранение
POST	/edit/action	Действие из формы
GET/POST/DELETE	/edit/file/*	Файлы
GET	/changes	История изменений (Envers)

DocumentController (/employee-api/documents)

Аналогичный набор + дополнительно:

Метод	Endpoint	Описание
GET	/types	Типы документов по категориям (WAREHOUSE, RECEIPT, SHIPMENT)
GET	/related	Дерево связанных документов (parent-child)
GET	/status-history	История смены статусов

Layout (пользовательские шаблоны)

FormTemplateElementEntityService + FormTemplateController — хранение кастомного расположения элементов формы. Позволяет администратору переопределять layout без изменения бэкенда.