Создание карточки-сателлита
Создание карточки-сателлита¶
Карточка-сателлит - это специальная карточка, которая прозрачно для пользователя сопровождает основную карточку, т.е. пользователь явно не создаёт и не удаляет сателлит, и даже не подозревает о его существовании. Например, карточка с настройками сотрудника, которая позволяет соотнести с каждым сотрудником его настройки рабочего места, при этом не изменяя внешний вид и структуру основной карточки сотрудника.
Сателлит даёт следующие преимущества:
-
Можно изменять связанные с карточкой данные, не изменяя версию карточки.
-
Можно выполнять параллельное изменение данных (например, при параллельном согласовании), не блокируя основную карточку.
-
Можно связать данные с типом карточки, не изменяя его структуру. Это позволяет иметь нестандартное API (такое, как ролевая модель), которое продолжит корректно взаимодействовать с основной карточкой.
-
Неизменность структуры основной карточки также обеспечивает бинарную совместимость этой карточки. Т.е. ранее удалённые или экспортированные карточки без сателлита по-прежнему можно будет восстановить.
Для карточки-сателлита необходимо обеспечить:
-
Создание по первому требованию со стороны расширений. Это может быть старт бизнес-процесса или явный запрос настроек сотрудника при старте приложения.
-
Загрузка по идентификатору основной карточки. Писатели расширений должны легко получить данные сателлита как на клиенте, так и на сервере, зная только идентификатор основной карточки.
-
Автоматическое удаление при удалении основной карточки.
-
Автоматический экспорт при экспорте основной карточки.
-
Автоматический импорт при импорте основной карточки.
-
Восстановление из корзины вместе с восстановлением основной карточки.
Для упрощения разработки сателлитов карточек в системе предусмотрен механизм универсальных сателлитов, который уже обеспечивает все вышеописанные требования к сателлитам, а также позволяет их расширять с помощью дополнительно реализованного обработчика сателлитов.
Универсальные сателлиты¶
Механизм универсальных сателлитов состоит из 3 основных объектов:
-
ISatelliteTypeRegistry
- объект, в котором регистрируются новые типы сателлитов. Он реализован в платформе. -
SatelliteTypeDescriptor
- дескриптор типа сателлита. Содержит настройки типа сателлита. Создается отдельно для каждого типа сателлита. -
ISatelliteHandler
- обработчик сателлита, в котором реализуется дополнительная логика обработки сателлита. Может создаваться для как отдельно для каждого типа сателлита, так и в нескольких типах сателлита.
Дескриптор типа сателлита SatelliteTypeDescriptor
имеет следующие свойства:
-
IsSingleton
- данный флаг определяет, должен ли данный тип сателлита быть синглтоном по отношению к основной карточке или к заданию, если данный тип сателлита относится к заданию карточки. Когда для типа сателлита установлен этот флаг, а у карточки уже есть сателлит с данным типом, то при попытке создать новый сателлит будет возвращена ошибка. -
IsDeferredStore
- данный флаг определяет, будет ли сателлит автоматически сохранен в базе при его первой загрузке. Если флаг не установлен, то при попытке получить карточку сателлита, если сателлита данного типа еще нет, он будет автоматически создан и сохранен. Если флаг установлен - то только создан. -
IsTaskSatellite
- флаг определяет, отноится ли сателлит к самой карточке или к конкретному заданию карточки. -
AllowGetFromClient
- флаг определяет, доступна ли загрузка сателлита с клиента. -
AllowStoreFromClient
- флаг определяет, доступно ли сохранение сателлита с клиента. -
AllowDeleteFromClient
- флаг определяет, доступно ли удаление сателлита с клиента. -
IgnoreStorePrepare
- флаг определяет, что при сохранении сателлита не будет вызываться метод подготовки сателлита по основной карточке. Это означает, что будет проигнорирована логика работы методаPrepareSatelliteForStoreAsync
в обработчике данного типа сателлита. -
IgnoreGetPrepare
- флаг определяет, что при загрузке сателлита не будет вызываться метод подготовки сателлита по основной карточке. Это означает, что будет проигнорирована логика работы методаPrepareSatelliteForGetAsync
в обработчике данного типа сателлита. -
CopySatelliteOnCardCopy
- флаг определяет, должен ли сателлит копироваться вместе с основной карточкой. -
HandlerType
- тип обработчика, который будет использоваться в расширениях для данного типа сателлита. Методы, которые можно переопределить обработчике сателлита, описаны ниже.
Обработчик сателлита ISatelliteHandler
имеет следующие методы, которые можно переопределить:
-
IsMainCardTypeAsync
- метод для проверки, является ли тип основной карточки (для которой создается сателлит) типом, который может иметь данный сателлит. -
PrepareSatelliteForGetAsync
- метод для подготовки карточки сателлита при его загрузке. В нем можно производить заполнение виртуальных секций карточки сателлита с использованием основной карточки. Логика данного метода игнорируется, если в дескрипторе типа сателлита установлен флагIgnoreGetPrepare
. -
PrepareSatelliteForStoreAsync
- метод для подготовки карточки сателлита при его сохранении. Он также может вернуть копию основной карточки, которая будет сохранена в рамках сохранения карточки сателлита. В методе можно производить чтение данных секций карточки сателлита и переносить необходимые изменения в основную карточку. Логика данного метода игнорируется, если в дескрипторе типа сателлита установлен флагIgnoreStorePrepare
. -
PrepareSatelliteForBackupAsync
- метод для подготовки карточки сателлита при удалении основной карточки в корзину. -
PrepareSatelliteForExportAsync
- метод для подготовки карточки сателлита при экспорте основной карточки. -
PrepareSatelliteForCreateAsync
- метод для подготовки карточки сателлита при ее создании. -
CheckFileAccessAsync
- метод для проверки доступа к содержимому файла, когда содержимое загружается из карточки сателлита. -
CheckFileVersionsAccessAsync
- метод для првоерки доступа к списку версий файла, когда список загружается из карточки сателлита. -
PrepareSatelliteForImportAsync
- метод для подготовки карточки сателлита при импорте основной карточки. -
PrepareSatelliteForDeleteAsync
- метод для подготовки карточки сателлита при удалении основной карточки. -
PrepareSatelliteForRestoreAsync
- метод для подготовки карточки сателлита при восстановлении основной карточки из корзины. -
PrepareSatelliteForRepareAsync
- метод для исправления карточки сателлита, который вызывается при исправлении основной карточки.
Создание нового типа сателлита¶
Чтобы создать новый тип сателлита нужно:
-
В свой тип карточки, который необходимо сделать сателлитом, добавить секцию
Satellites
вместе с колонкамиMainCard
,Type
и, если сателлит должен относится не к самой карточке, а к некому заданию, то также необходимо добавить колонкуTask
. -
Необходимо создать объект с классом
SatelliteTypeDescriptor
с указанием идентификатора необходимого типа карточки, а также задать необходимые свойства, определяющие поведение при работе сателлита:new SatelliteTypeDescriptor(DefaultCardTypes.KrSatelliteTypeID) { HandlerType = typeof(KrSatelliteHandler), IsSingleton = true, IgnoreGetPrepare = true, }
-
В регистраторе в методе
FinalizeRegistration
необходимо зарезолвить объектISatelliteTypeRegistry
и зарегистрировать в нем через методRegister
объект дескриптора типа сателлита, созданный в предыдущем пункте:var registry = this.UnityContainer.Resolve<ISatelliteTypeRegistry>(); registry.Register(new SatelliteTypeDescriptor(DefaultCardTypes.KrSatelliteTypeID) { HandlerType = typeof(KrSatelliteHandler), IsSingleton = true, IgnoreGetPrepare = true, });
registry.Register(new SatelliteTypeDescriptor(DefaultCardTypes.KrSecondarySatelliteTypeID) { HandlerType = typeof(KrSecondarySatelliteHandler), IgnoreGetPrepare = true, });
-
Если для типа сателлита необходимо реализовать дополнительное поведение, то нужно создать свой тип, который реализует интерфейс
ISatelliteHandler
, зарегистрировать его в Unity и указать данный тип в качестве значения для свойстваHandlerType
в объект дескриптора типа сателлита. Для удобства можно наследоваться от классаSatelliteHandlerBase
:public sealed class WfSatelliteHandler : SatelliteHandlerBase { #region Fields
private readonly IKrTypesCache krTypesCache;
#endregion
#region Constructors
public WfSatelliteHandler(IKrTypesCache krTypesCache) { this.krTypesCache = NotNullOrThrow(krTypesCache); }
#endregion
#region Base Overrides
/// <inheritdoc/> public override ValueTask<bool> IsMainCardTypeAsync( CardType mainCardType, CancellationToken cancellationToken = default) { NotNullOrThrow(mainCardType);
return WfHelper.TypeSupportsWorkflowAsync(this.krTypesCache, mainCardType, cancellationToken); }
#endregion } ..... public override void RegisterUnity() { this.UnityContainer .RegisterType<WfSatelliteHandler>(new ContainerControlledLifetimeManager()) ; }
Если требуется сделать обработчик сателлита, который относится к заданию и позволяет через карточку сателлита работать с этим заданием, то в качестве базового класса рекомендуется использовать класс
TaskSatelliteHandlerBase
, который имеет базовую логику по обработке задания, а также дополнительные методы, которые позволяют работать с файлами основной карточки в рамках работы с сателлитом.Note
При создании сателлита с обработчиком
TaskSatelliteHandlerBase
следует устанавить флагиAllowGetFromClient
иAllowStoreFromClient
, если с данным сателлитом предполаается работа с клиента, а также рекомендуется не устанавливать значения для флаговIgnoreGetPrepare
иIgnoreStorePrepare
, чтобы базовая логика обработичка выполнялась при получении и сохранении сателлита.Данный класс сателлита имеет следующие дополнительные свойства и методы, которые можно переопределить:
-
LoadMainCardFiles
- флаг определяет, что при загрузке данного сателлита к нему будут добавлены на чтение все файлы основной карточки. Свойство применяется в рамках базовой реализации методаPrepareSatelliteForGetAsync
, поэтому логика данного свойства игнорируется, если в дескрипторе типа сателлита установлен флагIgnoreGetPrepare
. -
GetExternalFileSourcesAsync
- метод для получения списка пар “идентификатор карточки”-“идентификатор типа карточки”, файлы которых добавляются в данный сателлит при его загрузке. Метод вызывается в рамках базовой реализации методаPrepareSatelliteForGetAsync
, поэтому логика данного метода игнорируется, если в дескрипторе типа сателлита установлен флагIgnoreGetPrepare
. -
SetupSatelliteFileAsync
- метод для фильтрации и подготовки карточек файлов, которые были добавлены из основной карточки (при наличии флагаLoadMainCardFiles
а) или из карточек, которые вернул методGetExternalFileSourcesAsync
. В данном методе можно отфильтровать файлы, которые не должны быть переданы в сателлит, или изменить свойства файлов. Метод вызывается в рамках базовой реализации методаPrepareSatelliteForGetAsync
, поэтому логика данного метода игнорируется, если в дескрипторе типа сателлита установлен флагIgnoreGetPrepare
. -
IsMainCardFileAsync
- метод для определения, является ли данный файл - файлом основной карточки. При сохранении карточки сателлита с файлом, если файл относится к основной карточке, файл будет добавлен к основной карточке, а не карточке сателлита. По умолчанию для всех файлов возвращаетfalse
. Метод вызывается в рамках базовой реализации методаPrepareSatelliteForStoreAsync
, поэтому логика данного метода игнорируется, если в дескрипторе типа сателлита установлен флагIgnoreStorePrepare
. -
PrepareMainCardFileToStoreAsync
- метод для подготовки сохранения файла в основную карточку при сохранении карточки сателлита. Вызывается для тех файлов, для которых методIsMainCardFileAsync
вернулtrue
. Метод вызывается в рамках базовой реализации методаPrepareSatelliteForStoreAsync
, поэтому логика данного метода игнорируется, если в дескрипторе типа сателлита установлен флагIgnoreStorePrepare
.
Example
Примером такого сателлита является сателлит задания типового решения
WfTaskCard
, который использует обработчикWfTaskSatelliteHandler
. Код обработчика доступен в рамках типового решения платформы. -
Автоматические сателлиты¶
В системе есть возможность создавать карточки сателлитов без использования каких-либо расширений.
Для этого достаточно в тип карточки добавить секцию Satellites
вместе с колонками MainCard
, Type
. Система будет использовать данный тип карточки как сателлит с настройками, которые указаны в дескрипторе SatelliteTypeDescriptor.AutoSatelliteType
.
Это позволяет легко сделать карточки-сателлиты без особой логики, или логикой, реализованной собственными расширениями, которые при этом автоматически будут экспортироваться, импортироваться, удаляться, удаляться в корзину и восстанавливаться вместе с основной карточкой.