Classification: сервис классификации объектов сущностей

Сервис позволяет классифицировать объекты различных сущностей по полям этих объектов. Команды могут приходить как по HTTP, так и через Kafka в топик classification_commands.

В сервисе реализованы следующие команды: - Получение иерархии классов - Получение ветви иерархии классов до определенного узла - Статистика количества классов у сущности - Получение класса
- Классификация типа - Список полей объекта для классифицированного типа - Создание нового класса - Редактирование класса - Удаление класса - Обновления атрибутов EntityObject с учетом классификации - Классы категоризированные по правилу генерации атрибутов - Обновление правил генерации в классах

Optimistic Lock

У нескольких команд реализован механизм оптимистичных блокировок. Для этого в данных присутствует поле version. Задача оптимистичных блокировок - предотвратить одновременное редактирование объекта из двух открытых форм. Сначала фронтэнд запрашивает данные объекта и получает в ответе версию данных - поле version. Он прикладывает эту версию в ответе. Если на бэкэнде она совпадает с исходной (не было других модификаций), тогда данные сохраняются, а версия поднимается. Иначе сохранения не происходит, данные не перетираются.

Сервис разбит на несколько модулей, в виде sbt проектов:

• domain, в котором содержатся все доменные модели и их различные представления.
• commands, в котором содержатся все? что связано с командами, их описанием и обработчиками.
• infrastructure, в котором содержится описание взаимодействия с другими сервисами.
• storage, содержит сервисы для сохранения и чтения их разных хранилищ доменных моделей.
• service, содержит сервисы бизнес логики, которые определяют правила взаимодействия компонентов между собой.
• utils, в котором содержатся разные хелперы.
• boot, содержит зависимости и описание для сборки и запуска сервиса.

Информация по добавлению команд можно прочитать в описании шаблона

Конфигурирование Classification

Требования к запуску Classification

Запуск сервиса осуществляется локально через sbt, на стенде в docker на jvm.

Для корректной минимальной работы сервиса требуется обязательное подключение к PostgreSQL, Kafka, Consul. Для настройки подключения к ним нужно заполнить обязательные переменные окружения из раздела ниже.

Для нормальной работы сервису дополнительно требуется окружение Verdi: CommandStatus, ApiGateway. В этом случае нужно уделить внимание настройкам, связанным с ServiceDiscovery и CommandDiscovery.

Запуск Classification из консоли с помощью SBT

CLASSIFICATION_DB_HOST=localhost CLASSIFICATION_DB_PORT=5432 CLASSIFICATION_DB_NAME=classification_db CLASSIFICATION_DB_USER=postgres CLASSIFICATION_DB_PASSWORD=12345 sbt boot/run

Список переменных окружения Classification

Все доступные переменные окружения для настройки сервиса.

Список команд сервиса Classification

Список реализованных в сервисе команд, моделей EntityType и действий Actions, которые можно использовать при настройке авторизации.

В описании команд используется путь/route для отправки команды в сам сервис, а не в ApiGateway. В качестве Input-а для команд, сервис всегда ожидает CommandRequest (как и любой другой сервис, принимающий команды), так что в описании команды указано лишь описание поля payload для CommandRequest.

ListEntityClassHierarchy (classification)

Payload для команды

"Tag"

Результат выполнения команды

[
        {
            "entityClass": {
                "id": "0becc650-2909-4769-869d-2521c3e452e1",
                "parentId": null,
                "entityType": "Tag",
                "title": "Арматура",
                "controlFieldCode": "tagType",
                "controlFieldValue": "763a967d-625f-44be-ad7c-d8ccd9e3af19",
                "managedFields": [
                    {
                        "fieldCode": "istochnik_dannyх",
                        "isMandatory": false
                    },
                    {
                        "fieldCode": "klapan",
                        "isMandatory": true
                    },
                    {
                        "fieldCode": "diametr",
                        "isMandatory": false
                    }
                ],
                "valueGenerationRuleIds": ["5f80e530-1ccc-41e3-a088-03d719ba3f23"],
                "created": 1719594386281,
                "createdBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
                "modified": 1722498718415,
                "modifiedBy": "00000000-0000-0000-0000-000000000000",
                "version": 9
            },
            "subclasses": []
        }
]

Возвращает дерево сущностей классов

• На входе: EntityTypeId (String)
• На выходе: EntityClassHierarchyDTO[]

ListEntityClassParents (classification)

Payload для команды

{
  "entityType": "mechanism",
  "entityId": "23792ab1-0f47-4dd6-b186-9502931c67fb"
}

Результат выполнения команды

[
        {
            "id": "dd82aa1e-24a7-4d90-b49a-b53dbeb3f4ec",
            "parentId": null,
            "entityType": "mechanism",
            "title": "Очень длинное наименование класса Очень длинное наименование класса Очень длинное наименование класса",
            "controlFieldCode": "mechanism_catalog",
            "controlFieldValue": "cdb6eb0f-7316-4f45-863b-74b08e70e759",
            "managedFields": [
                {
                    "fieldCode": "optional_field",
                    "isMandatory": true
                }
            ],
            "valueGenerationRuleIds": ["5f80e530-1ccc-41e3-a088-03d719ba3f23"],
            "created": 1718887945200,
            "createdBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
            "modified": 1719380902380,
            "modifiedBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
            "version": 6
        }
    ]

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

• На входе: ListEntityClassParentsDTO
• На выходе: EntityClass[]

EntityTypeClassCount (classification)

Payload для команды

["Tag", "Document", "AnotherEntity"]

Результат выполнения команды

{
    "Tag": 110,
    "Document": 6,
    "AnotherEntity": 25
}

Считает количество классов с указанными сущностями

• На входе: EntityTypeId
• На выходе: Пары {EntityTypeId:количество}* ({String:Int}*)

GetEntityClass (classification)

Payload для команды

"23792ab1-0f47-4dd6-b186-9502931c67fb"

Результат выполнения команды

{
    "id": "23792ab1-0f47-4dd6-b186-9502931c67fb",
    "parentId": "dd82aa1e-24a7-4d90-b49a-b53dbeb3f4ec",
    "entityType": "mechanism",
    "title": "Заводной механизм",
    "controlFieldCode": "mechanism_catalog",
    "controlFieldValue": "adf7af2f-e5e3-4a08-bf1c-4ea792358bab",
    "managedFields": [],
    "valueGenerationRuleIds": [],
    "created": 1719379649875,
    "createdBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
    "modified": 1719379649875,
    "modifiedBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
    "version": 1
}

Получить сущность класса по её идентификатору

• На входе: EntityClassId (UUID)
• На выходе: EntityClass

ClassifyObject (classification)

Payload для команды

{
  "entityType": "Tag",
  "attributes": {
    "complex": "5f80e530-1ccc-41e3-a088-03d719ba3f23",
    "<другие поля производные от объектов иерархии>": "...",
    "tagType": "763a967d-625f-44be-ad7c-d8ccd9e3af19"
  }
}

Результат выполнения команды

[
  {
    "entityClass": {
      "id": "d6bfc896-2dcb-45ca-94be-1654f10ae79d",
      "parentId": null,
      "entityType": "Tag",
      "title": "Арматура 30мм",
      "controlFieldCode": "parentTag",
      "controlFieldValue": "5639bae9-e313-44b4-a3b7-8fd06c8ef7ad",
      "managedFields": [
        {
          "fieldCode": "code",
          "isMandatory": true
        },
        {
          "fieldCode": "diametr",
          "isMandatory": true
        }
      ],
      "valueGenerationRuleIds": ["5f80e530-1ccc-41e3-a088-03d719ba3f23"],
      "created": 1718885396389,
      "createdBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
      "modified": 1718885396389,
      "modifiedBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
      "version": 1
    },
    "subclasses": [
      {
        "entityClass": {
          "id": "e5bfc896-2dcb-45ca-94be-1654f10ae431",
          "parentId": "d6bfc896-2dcb-45ca-94be-1654f10ae79d",
          "<другие поля EntityClass модели>": "..."
        }
      }
    ]
  }
]

Классификация типа сущности.

• На входе: ClassifyObjectDto
• На выходе: EntityClassHierarchyDTO[]

CalculateManagedFields (classification)

Payload для команды

{
  "entityType": "Tag",
  "attributes": {
    "complex": "5f80e530-1ccc-41e3-a088-03d719ba3f23",
    "<другие поля производные от объектов иерархии>": "...",
    "tagType": "763a967d-625f-44be-ad7c-d8ccd9e3af19"
  }
}

Результат выполнения команды

[
  {
    "fieldCode": "code",
    "isMandatory": true
  },
  {
    "fieldCode": "diametr",
    "isMandatory": true
  }
]

Получить список полей объекта для классифицированного типа.

• На входе: ClassifyObjectDto
• На выходе: ManagedField[]

CreateEntityClass (classification)

Payload для команды

{
      "parentId": null,
      "entityType": "Tag",
      "title": "Арматура 30мм",
      "controlFieldCode": "parentTag",
      "controlFieldValue": "5639bae9-e313-44b4-a3b7-8fd06c8ef7ad",
      "managedFields": [
        {
          "fieldCode": "code",
          "isMandatory": true
        },
        {
          "fieldCode": "diametr",
          "isMandatory": true
        }
      ],
      "valueGenerationRuleIds": ["5f80e530-1ccc-41e3-a088-03d719ba3f23"]
    }

Результат выполнения команды

"00001111-2222-3333-4444-555566667777"

Добавление нового класса сущности.

• На входе: CreateEntityClassDTO
• На выходе: ID нового класса (UUID)

UpdateEntityClass (classification)

Результат выполнения команды

{
  "id": "d6bfc896-2dcb-45ca-94be-1654f10ae79d",
  "title": "Арматура 30мм",
  "controlFieldCode": "parentTag",
  "controlFieldValue": "5639bae9-e313-44b4-a3b7-8fd06c8ef7ad",
  "managedFields": [
    {
      "fieldCode": "code",
      "isMandatory": true
    },
    {
      "fieldCode": "diametr",
      "isMandatory": true
    }
  ],
  "valueGenerationRuleIds": ["5f80e530-1ccc-41e3-a088-03d719ba3f23"],
  "version": 1
}

Результат выполнения команды

true

Обновление класса сущности.

• На входе: UpdateEntityClassDTO
• На выходе: Boolean

DeleteEntityClass (classification)

Payload для команды

"00001111-2222-3333-4444-555566667777"

Результат выполнения команды

true

Удаление класса сущности.

• На входе: ID класса сущности (UUID)
• На выходе: Boolean

updateObjectWithReclassification

Payload для команды

{
  "entityType": "Order",
  "objectId": "18b1011b-9db3-4186-a53c-971016030068",
  "version": 2,
  "attributes": {
    "date": 1577869200,
    "number": 514
  }
}

Результат выполнения команды

true

Или ошибка, если объект не существует

{
  "businessError": null,
  "message": "ERROR: Entity object not found",
  "stackTrace": null,
  "data": null
}

Или ошибка, если объект был обновлен из другого места

{
  "businessError": null,
  "message": "ERROR: object version is not actual (Optimistic Lock)",
  "stackTrace": null,
  "data": null
}

Изменение объекта сущности. Использует оптимистичную блокировку. Если изменяемый объект был изменен параллельно (например, из другой формы другим пользователем), тогда вернется ошибка ERROR: object version is not actual (Optimistic Lock), показывающая, что не произошло обновления из-за некорректной версии.

Поддерживается асинхронный и синхронный вызов. Результат выполнения команды журналируется.

• На входе: UpdateEntityObject
• На выходе: boolean, true - обновление успешно, false - неуспешно.

EntityClassesByValueGenerationRules

Payload для команды

{
  "valueGenerationRuleIds": ["5f80e530-1ccc-41e3-a088-03d719ba3f23"]
}

Результат выполнения команды

[
  {
    "valueGenerationRuleId": "5f80e530-1ccc-41e3-a088-03d719ba3f23",
    "entityClasses": [
      {
        "id": "e718335f-8ea9-45c3-ab66-164965e2bbb9",
        "parentId": null,
        "entityType": "testEntity3",
        "title": "Новый тестовый 123",
        "controlFieldCode": "testEntity",
        "controlFieldValue": "9af6310c-dbf4-4907-9cda-8f8657e98d8d",
        "managedFields": [],
        "valueGenerationRuleIds": [
          "4f80e530-1ccc-41e3-a088-03d719ba3f23",
          "5f80e530-1ccc-41e3-a088-03d719ba3f23"
        ],
        "created": 1718799645926,
        "createdBy": "2cf81fee-3fe9-45e9-9580-8aabf7d5f357",
        "modified": 1718799645926,
        "modifiedBy": "2cf81fee-3fe9-45e9-9580-8aabf7d5f357",
        "version": 1
      },
      {
        "id": "814f6890-e030-4b3e-a652-5e2986466aab",
        "parentId": null,
        "entityType": "construction",
        "title": "Деревянные конструкции",
        "controlFieldCode": "construction_type",
        "controlFieldValue": "eb299170-0f60-42e6-8756-ee793b885e69",
        "managedFields": [
          {
            "fieldCode": "construction_foreign",
            "isMandatory": true
          },
          {
            "fieldCode": "construction_type",
            "isMandatory": false
          }
        ],
        "valueGenerationRuleIds": [
          "5f80e530-1ccc-41e3-a088-03d719ba3f23"
        ],
        "created": 1718716494252,
        "createdBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
        "modified": 1718716494252,
        "modifiedBy": "a21002d0-bd59-4b4d-8b6f-6707a2e1cc21",
        "version": 1
      }
    ]
  }
]

Получить список классов содержащих переданные идентификаторы правила, и сгруппированные по ним. Классы могут дублироваться в категориях

Поддерживается только синхронный вызов. Результат выполнения команды не журналируется.

• На входе: EntityClassesByValueGenerationRulesInput
• На выходе: EntityClassesByValueGenerationRulesOutput

UpdateValueGenerationRuleEntityClasses

Payload для команды

{
  "valueGenerationRuleId": "5f80e530-1ccc-41e3-a088-03d719ba3f23",
  "entityClassIds": ["41bc3c4c-44fa-43cc-8e07-3d2207cf033c"],
  "clearOtherClasses": true
}

Результат выполнения команды

[
  {
    "id": "41bc3c4c-44fa-43cc-8e07-3d2207cf033c",
    "parentId": null,
    "entityType": "testEntity3",
    "title": "подкласс",
    "controlFieldCode": "testEntity",
    "controlFieldValue": "be231b97-6d37-4821-b78b-4c2ce8c1dea0",
    "managedFields": [],
    "valueGenerationRuleIds": [
      "5f80e530-1ccc-41e3-a088-03d719ba3f23",
      "3f80e530-1ccc-41e3-a088-03d719ba3f23"
    ],
    "created": 1718804181037,
    "createdBy": "2cf81fee-3fe9-45e9-9580-8aabf7d5f357",
    "modified": 1718804181037,
    "modifiedBy": "2cf81fee-3fe9-45e9-9580-8aabf7d5f357",
    "version": 2
  }
]

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

Поддерживается асинхронный и синхронный вызов. Результат выполнения команды не журналируется.

• На входе: UpdateValueGenerationRuleEntityClassesInput
• На выходе: EntityClass[]

Объекты сервиса classification

ClassifyObjectDto

Входные данные классификации

ListEntityClassParentsDTO

Входные данные классификации

EntityClassHierarchyDTO

Дерево сущностей класса

EntityClass

Сущность класса

CreateEntityClassDTO

Объект создания сущности класса

UpdateEntityClassDTO

Объект обновления сущности класса

ManagedField

Управляемое поле

UpdateEntityObject

Изменение объекта сущности

EntityClassesByValueGenerationRulesInput

EntityClassesByValueGenerationRulesOutput

UpdateValueGenerationRuleEntityClassesInput

Exporter: сервис для экспорта данных

Сервис принимает команды для работы с игроками и командами. Состояние хранится в PostgreSQL. Команды могут приходить как по HTTP, так и через Kafka в топик exporter_commands.

Сервис разбит на несколько модулей, в виде sbt проектов:

• domain, в котором содержатся все доменные модели и их различные представления.
• commands, в котором содержатся все? что связано с командами, их описанием и обработчиками.
• infrastructure, в котором содержится описание взаимодействия с другими сервисами.
• storage, содержит сервисы для сохранения и чтения их разных хранилищ доменных моделей.
• service, содержит сервисы бизнес логики, которые определяют правила взаимодействия компонентов между собой.
• boot, содержит зависимости и описание для сборки и запуска сервиса.

Информация по добавлению команд можно прочитать в описании шаблона

Локальный запуск

При запуске сервиса ожидается, что уже развернута необходимая инфраструктура:

• PostgreSQL база по адресу localhost:5432/exporter_db
• Kafka по адресу localhost:9092
• Consul по адресу localhost:8500
• Адрес Kafka будет указан в application.conf
• Добавлены необходимые переменные окружения:
  • EXPORTER_DB_HOST
  • EXPORTER_DB_PORT
  • EXPORTER_DB_NAME
  • EXPORTER_DB_USER
  • EXPORTER_DB_PASSWORD

Запуск из консоли с помощью SBT

EXPORTER_DB_HOST=localhost EXPORTER_DB_PORT=5432 EXPORTER_DB_NAME=exporter_db EXPORTER_DB_USER=postgres EXPORTER_DB_PASSWORD=12345 sbt boot/run

Список переменных окружения сервиса Exporter

Все доступные переменные окружения для настройки сервиса.

Список команд сервиса Exporter

Список реализованных в сервисе команд, моделей EntityType и действий Actions, которые можно использовать при настройке авторизации.

В описании команд используется путь/route для отправки команды в сам сервис, а не в ApiGateway. В качестве Input-а для команд, сервис всегда ожидает CommandRequest (как и любой другой сервис, принимающий команды), так что в описании команды указано лишь описание поля payload для CommandRequest.

ListExportProcess

Payload для команды

 {
  "query": "",
  "context": {},
  "sorting": {
    "fieldName": "entityType",
    "order": "desc"
  },
  "paging": {
    "page": 1,
    "count": 10
  }
}

Результат выполнения команды

{
  "items": [
    {
      "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd",
      "entityType": "abc",
      "status": "DRAFT",
      "exportConfig": {
        "title": "Sample Project Title"
      },
      "exportFile": "some file",
      "resultFile": null,
      "info": {},
      "created": 1723809067603,
      "createdBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
      "modified": 1723809067603,
      "modifiedBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
      "executed": null,
      "executedBy": null,
      "version": 1
    }
  ],
  "total": 1
}

Возвращает список всех задач экспорта.

Поддерживается только синхронный вызов.

• На входе: Option[Search]
• На выходе: Page[ExportProcess]

Доступные поля для фильтрации и виды фильтров по ним:

Доступные поля для сортировки:

GetExportProcess

Payload для команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Результат выполнения команды

{
  "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd",
  "entityType": "abc",
  "status": "DRAFT",
  "exportConfig": {
    "title": "Sample Project Title"
  },
  "exportFile": "some file",
  "resultFile": null,
  "info": {},
  "created": 1723809067603,
  "createdBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
  "modified": 1723809067603,
  "modifiedBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
  "executed": null,
  "executedBy": null,
  "version": 1
}

Поиск задачи экспорта с заданным идентификатором.

Поддерживается только синхронный вызов.

• На входе: ExportProcessId (UUID)
• На выходе: ExportProcess

CreateExportProcess

Payload для команды

{
  "entityType": "abc",
  "exportConfig": {
    "title": "Sample Project Title"
  },
  "exportFile": "some file"
}

Результат выполнения команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Добавляет новую задачу экспорта с заданными параметрами. Отправляет событие о создании задачи экспорта.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportProcessCreateDto
• На выходе: ExportProcessId (UUID)

UpdateExportProcess

Payload для команды

{
  "id": "f283aac5-88e0-43b5-8dab-56c22d91acc7",
  "entityType": "abc",
  "exportConfig": {
    "startRow": 3,
    "columnMapping": [
      {
        "property": "title",
        "columnLabel": "A"
      }
    ]
  },
  "exportFile": "bucket/file_id",
  "version": 1
}

Результат выполнения команды

true

Обновляет данные задачи экспорта. Отправляет событие об обновлении задачи экспорта.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportProcessUpdateDto
• На выходе: Boolean

DeleteExportProcess

Payload для команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Результат выполнения команды

true

Удаляет задачу экспорта с заданным идентификатором. Отправляет событие об удалении задачи экспорта.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportProcessId (UUID)
• На выходе: Boolean

ExecuteExportProcess

Payload для команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Результат выполнения команды

true

Запускает задачу экспорта с заданным идентификатором. Отправляет событие о результатах выполнения задачи экспорта.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportProcessId (UUID)
• На выходе: Boolean

CancelExportProcess

Payload для команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Результат выполнения команды

true

Останавливает запущенную задачу экспорта с заданным идентификатором.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportProcessId (UUID)
• На выходе: Boolean

GetExportProgress

Payload для команды

{
  "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd"
}

Результат выполнения команды

{
  "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd": {
    "estimateTime": "PT12H54M5.02S",
    "percent": 0.3368487274760384,
    "stats": [
      {
        "name": "?",
        "processed": {
          "succeed": 0,
          "skipped": 1723,
          "total": 1723
        },
        "errors": 0
      }
    ]
  }
}

Прогресс задач экспорта. Можно отфильтровать по идентификатору конкретной задачи. Поддерживается только синхронный вызов.

• На входе: GetExportProgressDto
• На выходе: Map[ExportProcessId, [EstimateProgressStats]]

CreateAndExecuteExportProcess

Payload для команды

{
  "entityType": "Tag",
  "exportConfig": {
    "columnMapping": [
      {
        "columnLabel": "C",
        "columnHeader": "Заголовок",
        "attributePath": [
          {
            "fieldCode": "title",
            "fieldType": "string"
          }
        ]
      },
      {
        "columnLabel": "A",
        "columnHeader": "Код",
        "attributePath": [
          {
            "fieldCode": "code",
            "fieldType": "string"
          }
        ]
      },
      {
        "columnLabel": "D",
        "columnHeader": "Диаметр",
        "attributePath": [
          {
            "fieldCode": "diametr",
            "fieldType": "number"
          }
        ]
      },
      {
        "columnLabel": "E",
        "columnHeader": "subType",
        "attributePath": [
          {
            "fieldCode": "subType",
            "fieldType": "catalogItem",
            "catalogCode": "TagSubType"
          },
          {
            "fieldCode": "tagTypeTitle",
            "fieldType": "string"
          }
        ]
      },
      {
        "columnLabel": "F",
        "columnHeader": "complex code",
        "attributePath": [
          {
            "fieldCode": "complex",
            "fieldType": "entityObject",
            "entityType": "complex"
          },
          {
            "fieldCode": "code",
            "fieldType": "string"
          }
        ]
      },
      {
        "columnLabel": "G",
        "columnHeader": "complex title",
        "attributePath": [
          {
            "fieldCode": "complex",
            "fieldType": "entityObject",
            "entityType": "complex"
          },
          {
            "fieldCode": "title",
            "fieldType": "string"
          }
        ]
      }
    ]
  },
  "search": {
    "query": "",
    "context": {
    }
  },
  "hierarchy": []
}

Результат выполнения команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Последовательное выполнение команд CreateExportProcess и ExecuteExportProcess.

Добавляет новую задачу экспорта с заданными параметрами, а затем ее запускает.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportProcessCreateDto
• На выходе: ExportProcessId (UUID)

ListExportTemplate

Payload для команды

 {
  "query": "",
  "context": {},
  "sorting": {
    "fieldName": "entityType",
    "order": "desc"
  },
  "paging": {
    "page": 1,
    "count": 10
  }
}

Результат выполнения команды

{
  "items": [
    {
      "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd",
      "entityType": "abc",
      "title": "Наименование шаблона",
      "description": "Описание которое на которое никто не смотрит",
      "exportConfig": {
        "title": "Sample Project Title"
      },
      "created": 1723809067603,
      "createdBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
      "modified": 1723809067603,
      "modifiedBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
      "version": 1
    }
  ],
  "total": 1
}

Возвращает список всех шаблонов экспорта.

Поддерживается только синхронный вызов.

• На входе: Option[Search]
• На выходе: Page[ExportTemplate]

Доступные поля для фильтрации и виды фильтров по ним:

Доступные поля для сортировки:

GetExportTemplate

Payload для команды

"b251c2e5-e12c-4792-b6f4-6578bfd4d6cd"

Результат выполнения команды

{
  "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd",
  "entityType": "abc",
  "title": "Наименование шаблона",
  "description": "Описание которое на которое никто не смотрит",
  "exportConfig": {
    "title": "Sample Project Title"
  },
  "created": 1723809067603,
  "createdBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
  "modified": 1723809067603,
  "modifiedBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
  "version": 1
}

Поиск задачи экспорта с заданным идентификатором.

Поддерживается только синхронный вызов.

• На входе: ExportTemplateId (UUID)
• На выходе: ExportTemplate

CreateExportTemplate

Payload для команды

{
  "entityType": "abc",
  "title": "Шаблон всего",
  "description": "Описание шаблона на которое никто не смотрит",
  "exportConfig": {
    "title": "Sample Project Title"
  }
}

Результат выполнения команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Добавляет новый шаблон экспорта с заданными параметрами. Отправляет событие о создании шаблона экспорта.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportTemplateCreateDto
• На выходе: ExportTemplateId (UUID)

UpdateExportTemplate

Payload для команды

{
  "id": "f283aac5-88e0-43b5-8dab-56c22d91acc7",
  "entityType": "abc",
  "title": "Шаблон всего",
  "description": "Описание шаблона на которое никто не смотрит",
  "exportConfig": {
    "startRow": 3,
    "columnMapping": [
      {
        "property": "title",
        "columnLabel": "A"
      }
    ]
  },
  "version": 1
}

Результат выполнения команды

true

Обновляет данные шаблона экспорта. Отправляет событие об обновлении шаблона экспорта.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportTemplateUpdateDto
• На выходе: Boolean

DeleteExportTemplate

Payload для команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Результат выполнения команды

true

Удаляет шаблон экспорта с заданным идентификатором. Отправляет событие об удалении шаблона экспорта.

Поддерживается асинхронный и синхронный вызов.

• На входе: ExportTemplateId (UUID)
• На выходе: Boolean

Модели сервиса Exporter

ExportProcessCreateDto

ExportProcessUpdateDto

ExportProcess

ExportTemplateCreateDto

ExportTemplateUpdateDto

ExportTemplate

ExportConfig

ColumnMapping

FieldAttribute

ExportFileInformation

ExportInfo

ProgressInfo

GetExportProgressDto

EstimateProgressStats

SheetExportTotalStatistic

StatFraction

Importer: сервис для примера

Сервис принимает команды для работы с игроками и командами. Состояние хранится в PostgreSQL. Команды могут приходить как по HTTP, так и через Kafka в топик importer_commands.

Сервис разбит на несколько модулей, в виде sbt проектов:

• domain, в котором содержатся все доменные модели и их различные представления.
• commands, в котором содержатся все? что связано с командами, их описанием и обработчиками.
• infrastructure, в котором содержится описание взаимодействия с другими сервисами.
• storage, содержит сервисы для сохранения и чтения их разных хранилищ доменных моделей.
• service, содержит сервисы бизнес логики, которые определяют правила взаимодействия компонентов между собой.
• boot, содержит зависимости и описание для сборки и запуска сервиса.

Информация по добавлению команд можно прочитать в описании шаблона

Локальный запуск

При запуске сервиса ожидается, что уже развернута необходимая инфраструктура:

• PostgreSQL база по адресу localhost:5432/importer_db
• Kafka по адресу localhost:9092
• Consul по адресу localhost:8500
• Адрес Kafka будет указан в application.conf
• Добавлены необходимые переменные окружения:
  • IMPORTER_DB_HOST
  • IMPORTER_DB_PORT
  • IMPORTER_DB_NAME
  • IMPORTER_DB_USER
  • IMPORTER_DB_PASSWORD

Запуск из консоли с помощью SBT

IMPORTER_DB_HOST=localhost IMPORTER_DB_PORT=5432 IMPORTER_DB_NAME=importer_db IMPORTER_DB_USER=postgres IMPORTER_DB_PASSWORD=12345 sbt boot/run

Список переменных окружения сервиса Importer

Все доступные переменные окружения для настройки сервиса.

Список команд сервиса Importer

Список реализованных в сервисе команд, моделей EntityType и действий Actions, которые можно использовать при настройке авторизации.

В описании команд используется путь/route для отправки команды в сам сервис, а не в ApiGateway. В качестве Input-а для команд, сервис всегда ожидает CommandRequest (как и любой другой сервис, принимающий команды), так что в описании команды указано лишь описание поля payload для CommandRequest.

ListImportProcess

Payload для команды

 {
  "query": "",
  "context": {},
  "sorting": {
    "fieldName": "entityType",
    "order": "desc"
  },
  "paging": {
    "page": 1,
    "count": 10
  }
}

Результат выполнения команды

{
  "items": [
    {
      "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd",
      "entityType": "abc",
      "status": "DRAFT",
      "importConfig": {
        "title": "Sample Project Title"
      },
      "importFile": "some file",
      "resultFile": null,
      "info": {},
      "created": 1723809067603,
      "createdBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
      "modified": 1723809067603,
      "modifiedBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
      "executed": null,
      "executedBy": null,
      "version": 1
    }
  ],
  "total": 1
}

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

• На входе: Option[Search]
• На выходе: Page[ImportProcess]

Доступные поля для фильтрации и виды фильтров по ним:

Доступные поля для сортировки:

GetImportProcess

Payload для команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Результат выполнения команды

{
  "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd",
  "entityType": "abc",
  "status": "DRAFT",
  "importConfig": {
    "title": "Sample Project Title"
  },
  "importFile": "some file",
  "resultFile": null,
  "info": {},
  "created": 1723809067603,
  "createdBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
  "modified": 1723809067603,
  "modifiedBy": "7099494d-0a5f-47ff-bc52-9cfb74ffe282",
  "executed": null,
  "executedBy": null,
  "version": 1
}

Поиск задачи импорта с заданным идентификатором. Поддерживается только синхронный вызов.

• На входе: ImportProcessId (UUID)
• На выходе: ImportProcess

CreateImportProcess

Payload для команды

{
  "entityType": "abc",
  "importConfig": {
    "title": "Sample Project Title"
  },
  "importFile": "some file"
}

Результат выполнения команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Добавляет новую задачу импорта с заданными параметрами. Отправляет событие о создании задачи импорта.

• На входе: ImportProcessCreateDto
• На выходе: ImportProcessId (UUID)

UpdateImportProcess

Payload для команды

{
  "id": "f283aac5-88e0-43b5-8dab-56c22d91acc7",
  "entityType": "abc",
  "importConfig": {
    "startRow": 3,
    "columnMapping": [
      {
        "property": "title",
        "columnLabel": "A"
      }
    ]
  },
  "importFile": "bucket/file_id",
  "version": 1
}

Результат выполнения команды

true

Обновляет данные задачи импорта. Отправляет событие об обновлении задачи импорта.

• На входе: ImportProcessUpdateDto
• На выходе: Boolean

DeleteImportProcess

Payload для команды

"f283aac5-88e0-43b5-8dab-56c22d91acc7"

Результат выполнения команды

true

Удаляет задачу импорта с заданным идентификатором. Отправляет событие об удалении задачи импорта.

• На входе: ImportProcessId (UUID)
• На выходе: Boolean

ExecuteImportProcess

Payload для команды

"b251c2e5-e12c-4792-b6f4-6578bfd4d6cd"

Результат выполнения команды

true

Запускает задачу импорта с заданным идентификатором. Отправляет событие о результатах выполнения задачи импорта.

• На входе: ImportProcessId (UUID)
• На выходе: Boolean

CancelImportProcess

Payload для команды

"b251c2e5-e12c-4792-b6f4-6578bfd4d6cd"

Результат выполнения команды

true

Остановка задачи импорта с заданным идентификатором. Поддерживается только синхронный вызов.

• На входе: ImportProcessId (UUID)
• На выходе: Boolean

GetImportProgress

Payload для команды

{
  "id": "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd"
}

Результат выполнения команды

{
  "b251c2e5-e12c-4792-b6f4-6578bfd4d6cd": {
    "estimateTime": "PT12H54M5.02S",
    "percent": 0.3368487274760384,
    "stats": [
      {
        "name": "Лист1",
        "updates": {
          "succeed": 0,
          "skipped": 1723,
          "total": 1723
        },
        "creates": {
          "succeed": 569,
          "skipped": null,
          "total": 3277
        },
        "deleteRelations": {
          "succeed": 0,
          "skipped": null,
          "total": 0
        },
        "createRelations": {
          "succeed": 1139,
          "skipped": null,
          "total": 6555
        },
        "errors": 2
      }
    ]
  }
}

Прогресс задач импорта. Можно отфильтровать по идентификатору конкретной задачи. Поддерживается только синхронный вызов.

• На входе: GetImportProgressDto
• На выходе: Map[ImportProcessId, [EstimateProgressStats]]

Модели сервиса Importer

ImportProcessCreateDto

ImportProcessUpdateDto

ImportProcess

GetImportProgressDto

EstimateProgressStats

SheetImportTotalStatistic

StatFraction

ImportConfig

ColumnMapping

ImportFileInformation

ReportInformation

ImportInfo

VNP-control: сервис спец команд проекта DYG

Сервис подготавливает данные для построения деревьев ВНП Команды могут приходить как по HTTP, так и через Kafka в топик vnpcontrol_commands.

В сервисе реализованы следующие команды:

Optimistic Lock

У нескольких команд реализован механизм оптимистичных блокировок. Для этого в данных присутствует поле version. Задача оптимистичных блокировок - предотвратить одновременное редактирование объекта из двух открытых форм. Сначала фронтэнд запрашивает данные объекта и получает в ответе версию данных - поле version. Он прикладывает эту версию в ответе. Если на бэкэнде она совпадает с исходной (не было других модификаций), тогда данные сохраняются, а версия поднимается. Иначе сохранения не происходит, данные не перетираются.

Сервис разбит на несколько модулей, в виде sbt проектов:

• domain, в котором содержатся все доменные модели и их различные представления.
• commands, в котором содержатся все? что связано с командами, их описанием и обработчиками.
• infrastructure, в котором содержится описание взаимодействия с другими сервисами.
• storage, содержит сервисы для сохранения и чтения их разных хранилищ доменных моделей.
• service, содержит сервисы бизнес логики, которые определяют правила взаимодействия компонентов между собой.
• utils, в котором содержатся разные хелперы.
• boot, содержит зависимости и описание для сборки и запуска сервиса.

Информация по добавлению команд можно прочитать в описании шаблона

Конфигурирование

Требования к запуску

Запуск сервиса осуществляется локально через sbt, на стенде в docker на jvm.

Для корректной минимальной работы сервиса требуется обязательное подключение к PostgreSQL, Kafka, Consul. Для настройки подключения к ним нужно заполнить обязательные переменные окружения из раздела ниже.

Для нормальной работы сервису дополнительно требуется окружение Verdi: CommandStatus, ApiGateway. В этом случае нужно уделить внимание настройкам, связанным с ServiceDiscovery и CommandDiscovery.

Во время работы, сервис общается с другими сервисами, т.е. они нужны только в момент выполнения команд. Список сервисов приведен в таблице ниже.

Запуск из консоли с помощью SBT

VNPCONTROL_DB_HOST=localhost VNPCONTROL_DB_PORT=5432 VNPCONTROL_DB_NAME=vnpcontrol_db VNPCONTROL_DB_USER=postgres VNPCONTROL_DB_PASSWORD=12345 sbt boot/run

Список переменных окружения

Все доступные переменные окружения для настройки сервиса.

Настройки логеров описаны в общей документации.