Атрибуты и модель данных

Атрибуты и модель данных#

Общая позиция#

Проектный разработчик не должен добавлять атрибут в существующий типовой класс напрямую без анализа способа реализации.

Перед добавлением атрибута необходимо определить:

  • зачем нужен атрибут;

  • где он будет храниться;

  • кто будет его заполнять;

  • где он будет отображаться;

  • участвует ли он в фильтрации;

  • участвует ли он в отчетах;

  • участвует ли он в интеграциях;

  • требуется ли индекс или внешний ключ;

  • должен ли атрибут переживать обновления типовой поставки без конфликтов.

Характеристика через интерфейс#

Если дополнительное проектное поле добавляется через интерфейс, оно оформляется как объектная или универсальная характеристика. Такой способ не добавляет атрибут в ODM/ORM-модель класса и не требует изменения схемы БД.

Такой подход подходит для:

  • дополнительных аналитических признаков;

  • проектных комментариев;

  • признаков, используемых в интерфейсе;

  • данных, которые различаются по типам объекта;

  • значений по умолчанию и дополнительных проверок, настраиваемых через интерфейс;

  • полей, которые нужно быстро добавить без поставки нового кода.

Для таких полей используется объектная или универсальная характеристика с проектным суффиксом _z. Правила именования проектных характеристик описаны в разделе Проектное именование.

Атрибут ODM через код#

Если поле должно стать частью устойчивой модели данных класса, оно добавляется через ODM и поставляется как часть проектного модуля.

Такой подход обязателен, если:

  • атрибут нужен в массовой обработке;

  • атрибут участвует в бизнес-логике Api или Pkg;

  • атрибут используется в частых отчетах или сложных запросах;

  • атрибут должен индексироваться;

  • атрибут является внешним ключом;

  • атрибут должен участвовать в транзакционной логике;

  • по атрибуту требуется выполнять производительную фильтрацию;

  • атрибут входит в интеграционный контракт.

Для проектного атрибута ODM также используется суффикс _z. Правила именования проектных атрибутов описаны в разделе Проектное именование.

При добавлении через ODM необходимо:

  1. Добавить атрибут в проектный ODM-файл.

  2. Выполнить генерацию исходного кода.

  3. Выполнить генерацию или миграцию таблицы поддерживаемым способом.

  4. Проверить сгенерированные Dpi/Dvi и прикладные Api/Avi.

  5. Добавить отображение атрибута в выборки и карточки, если это требуется.

  6. Добавить тестирование логики, использующей атрибут.

JSON-атрибуты и формат дат#

Если дата хранится в JSON, она должна сохраняться в едином формате:

dd.mm.yyyy hh24:mi:ss

При формировании JSON на стороне БД дату необходимо явно преобразовывать через to_char с заданным форматом. При чтении даты из JSON в запросе необходимо использовать to_date с заданным форматом.

Не следует рассчитывать на неявное преобразование даты средствами БД. На результат может влиять настройка формата даты в СУБД, например DateStyle.

Если JSON формируется SQL-запросом, даты необходимо явно приводить к формату, который ожидает прикладный парсер. Если дата была сформирована через неявное преобразование БД, последующая обработка JSON в прикладном коде может завершиться ошибкой.

Создание нового проектного класса#

Новый проектный класс создается, если требуется самостоятельная проектная сущность, которая должна храниться в отдельной таблице и иметь собственную бизнес-логику.

Для нового класса необходимо определить:

  • назначение класса;

  • супертип класса;

  • состав атрибутов;

  • связи с другими классами;

  • коллекции;

  • бизнес-объект, если класс входит в состав бизнес-объекта;

  • выборки и отображения;

  • права доступа;

  • необходимость аудита;

  • необходимость участия в интеграциях и репликации;

  • правила установки начальных данных.

Выбор супертипа класса#

Супертип выбирается по назначению класса:

Супертип

Когда использовать

reference

для справочников и списочных сущностей

document

для документов с жизненным циклом и состояниями

collection

для табличных частей и подчиненных данных

vcollection

для коллекций с переменной ссылкой на родителя

journal

для журналов и больших массивов записей с ограниченной логикой

trait

для переиспользуемой логики без собственной таблицы

mixin

для общей структуры или логики, подключаемой к разным классам

Генерация кода#

После изменения ODM выполняется генерация исходного кода.

При генерации создаются доменные и прикладные элементы:

  • Dpi — доменная автономная логика;

  • Api — прикладная автономная логика;

  • Dvi — доменная интерактивная логика;

  • Avi — прикладная интерактивная логика;

  • Dvm — доменная разметка выборки;

  • Avm — прикладная разметка выборки;

  • POJO/ARO-объекты интеграции с ORM.

Доменная часть перезаписывается при кодогенерации. Проектная логика должна размещаться в прикладной части.

Запрещено размещать ручной проектный код в файлах, которые перезаписываются кодогенератором.

Команду Generate Tables Force запрещено выполнять от папки application, папки модуля или пакета. Ее можно использовать только по конкретным ODM-файлам и только при понимании последствий.

Запрет на ручное изменение БД#

Физическое изменение структуры таблиц напрямую в БД без отражения в проектных исходниках запрещено.

Если проектное изменение требует изменения схемы БД, оно должно быть воспроизводимо:

  • через ODM;

  • через миграционный пакет;

  • через SQL-скрипт миграции;

  • через другой поддерживаемый механизм поставки.

Ручное изменение БД допустимо только как разовая диагностическая или аварийная операция, если оно согласовано и зафиксировано отдельно. Такое изменение не считается полноценной проектной поставкой и должно быть воспроизведено в коде или миграции, если оно должно сохраниться.

Содержание