Falcon Space. Работа с сущностями

Введение в сущности

Сущность - это некий объект, который должен иметь возможность последовательно менять свой статус.

При этом возможна реализация разграничения полномочий на смену статуса между ролями. А также автоматизация дополнительных функционалов при смене статуса сущностью (например, отправка уведомлений, формирование неких других объектов, добавление комментариев, и т. д.).

В системе автоматически ведется лог изменения статусов сущности.

Реализация механизма Сущности

Будем рассматривать на примере. Допустим есть такой объект в нашей системе как Проект. Мы хотим реализовать Проект как Сущность.

1. Создание новой сущности, описание возможных статусов

В меню Компоненты / Сущности добавим запись о новой сущности Проект, указав её код project. При этом в БД добавится новая запись в системную таблицу as_en_entities.

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

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

Обязательно указывайте номер по порядку для статуса, а также цвет.

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

Например, из статуса Черновик проект можно перевести только в статус Опубликован, либо в Аннулирован. Причем право на выполнение этого перехода есть только у роли customer. На кнопках выбора следующих статусов будет написано соответственно Опубликовать и Аннулировать.

2. Экземпляры сущности

Сама сущность Проект - это одна запись в таблице as_en_entities с кодом project.

Экземпляры сущности, например, Проект №1, Проект №2, Проект №3, и т. д., будут храниться в таблице as_en_entityInstances.

В первом пункте мы создали сущность Проект. Необходимо теперь привязать это понятие к нашим проектам в базе данных. Делается это следующим образом.

Допустим наши проекты и вся информация по ним лежит в таблице au_projects. Теперь необходимо добавить в эту таблицу еще одно поле - instanceID. Это будет внешний ключ к таблице as_en_entityInstances. Таким образом, создастся связь типа “один к одному” между au_projects и as_en_entityInstances.

Перечень экземпляров сущности, в нашем случае - перечень конкретных проектов, выводятся на страницу с помощью обычного сниппета таблицы


Разумеется, необходимо предварительно реализовать в системе таблицу projects.

3. Добавление нового экземпляра сущности

Самый простой способ создания нового экземпляра сущности - это реализация FastCreate в таблице с перечнем экземпляров данной сущности.

Например, в таблице проектов projects быстрым созданием по названию будет создаваться новый проект. При этом необходимо в crud_projects_fastCreate прописать вставку новой записи не только в au_projects, но и предварительно вставку новой записи в as_en_entityInstances. И только потом с полученным новым instanceID вставлять новую запись в au_projects.

4. Страница экземпляра сущности

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

В нашем случае создадим форму entityProject для управления полями объекта Проект.

После этого создадим страницу для экземпляра сущности, на которой расположим сниппеты:

  • Обычный сниппет формы:
    <div class="as-form" data-code="{formCode}" data-itemid="falcon-space--rabota-s-sushchnostyami"></div>
  • Cниппет для управления статусами экземпляра сущности:
    <div class="entity" data-code="{entityCode}" data-itemid="falcon-space--rabota-s-sushchnostyami" data-type="item"></div>

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

Таким образом, указатель текущего статуса и кнопки для доступных дальнейших переходов будут расположены в правой колонке от формы проекта:

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

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

Когда вы делаете одну из колонок таблицы ссылкой на страницу экземпляра, то под видом itemID следует передавать не id из проектной таблицы экземпляров, а именно instanceID.

Например, в случае с нашими проектами:

6. Важное замечание о логировании смены статусов

Запись о смене статуса в лог as_en_statusesLog производится автоматически только в случае естественного перевода экземпляра в следующий статус - нажатием пользователем соответствующей кнопки перевода в статус.

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

7. Схема БД реализации механизма сущностей

Хранимые процедуры для работы с сущностями

Процедура ДО изменения статуса

Процедура en_{entityCode}_checkStatus вызывается для выполнения необходимых проверок перед сменой статуса у экземпляра сущности.

Параметры: instanceID, fromStatusCode, toStatusCode, username

Результат Select: msg, result, bit softMode, okButtonStyle, okButtonText, cancelButtonStyle, cancelButtonText.

Параметр softMode:

  • Если softMode = 1, то это означает, что ограничение является нежестким и можно по подтверждению все равно сменить статус.
  • Если softMode = 0, то в случае невозможности сменить статус, идет сообщение об этом, без возможности принудительно сменить статус.

okButtonText,cancelButtonText - задают текст кнопки для Отмены и для Подтверждения действия.

okButtonStyle, cancelButtonStyle - задают стиль кнопки. Значения - danger, warning,success, secondary, primary, info, light

Процедура ПОСЛЕ изменения статуса

Процедура en_{entityCode}_afterChangeStatus вызывается после успешной смены статуса у экземпляра сущности.

Параметры: instanceID, statusCode, username

Результат

SELECT 1: msg, result

SELECT 2: вызовы внешних действий (почта, смс, уведомление и т.д.). См. вызов внешних действий.

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

Процедура вывода дополнительной панели для статуса

Процедура en_{entityCode}_getStatusAdditionalToolbar содержит в себе вывод дополнительной разметки под кнопками переходов в доступные статусы.

Параметры: instanceID, entityCode, statusCode, username, langID

Результат Select: msg, result

В данном случае msg содержит строку разметки дополнительной панели.

Например, когда проект будет переведен в статус Выполнен, можно добавить в дополнительную панель кнопку “Добавить отзыв”. Тогда msg должна содержать, к примеру, вызов модальной формы на добавление отзыва исполнителю проекта.

CREATE PROCEDURE [dbo].[project]
	@instanceID int,
	@entityCode nvarchar(32),
	@statusCode nvarchar(32),
	@username nvarchar(32),
	@langID int = 1
AS
BEGIN
	if @statusCode = 'done'
           SELECT 'Добавить отзыв' Msg,
                   1 Result
        else
           SELECT '' Msg, 0 Result
END

Выглядеть это будет так:

Хранимая процедура вывода доступных статусов

По умолчанию используется стандартная процедура as_en_getAvailableStatusesForInstance.

Если вам необходима своя процедура, то вы устанавливаете режим Кастомная процедура AvailStatuses = ДА и реализуете процедуру en_{entityCode}_getAvailableStatusesForInstance (столбец SQL доступных статусов)

Примечание