Робота з цифровими документами у Кабінеті користувача

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

Поточний технічний дизайн сфокусований на загальних аспектах реалізації вимог щодо роботи із файлами через Кабінети користувача та на особливостях взаємодії між підсистемами "Lowcode" та "Дата Фабрика" в цьому контексті.

1. Функціональні можливості

Для забезпечення вимог по роботі з цифровими документами через кабінет користувача, платформа надає наступні можливості:

Завантаження цифрових документів користувачами через UI-форми задач бізнес-процесів
Вивантаження та перегляд цифрових документів користувачами через UI-форми задач бізнес-процесів

2. Загальні принципи реалізації

Файли цифрових документів, завантажені через UI-форми задач, підлягають збереженню в об’єктному сховищі Ceph до моменту закінчення бізнес-процесу
Для усіх файлів цифрових документів, завантажених через UI-форми задач, генерується SHA256-геш та зберігається у вигляді атрибуту Ceph-документа для подальшого використання при накладанні підпису
Файли цифрових документів, завантажені через UI-форми задач, та дані форми зберігаються у вигляді окремих Ceph-документів в різних бакетах (lowcode-file-storage та lowcode-form-data-storage)
Для забезпечення цілістності даних, отриманих від користувача та завантажених ним файлів цифрових документів через UI-форму, Ceph-документ даних форми містить унікальні ідентифікатори Ceph-документів файлів та згенеровані з них SHA256-геші
Файли цифрових документів не є об’єктом виконання операцій на рівні бізнес-процесів на відміну від їх ідентифікаторів
При накладанні підпису приватним ключем користувача на дані форми з завантаженими файлами цифрових документів, підпис генерується на документ даних UI-форми, який містить унікальні ідентифікатори Ceph-документів та SHA256-геші файлів
Обмін цифровими документами між підсистемами платформи "Low-code" та "Дата Фабрика" реалізується внаслідок обміну унікальних ідентифікаторів та їх Ceph-документів через окремий Ceph-бакет "lowcode-file-storage"
Усі документи, які завантажені в рамках бізнес-процесу, зберігаються у вигляді Ceph-об’єктів в "lowcode-file-storage" бакеті під ключами з ознакою групування за префіксом (process/{processInstanceId}/{id}) процесу
Бакет "low-code-file-storage" призначений для тимчасового зберігання цифрових документів у процесі виконання бізнес-процесів. Для перманентного зберігання використовується окремий бакет "Дата Фабрики" - "registry-file-storage"

3. Взаємодія компонентів системи

На даній діаграмі зображено задіяні для реалізації вимог сервіси платформи та взаємодію між ними. Додатково зображено важливі особливості, які необхідно прийняти до уваги в рамках реалізації.

3.1. Сервіс цифрових документів

За реалізацію вимог по роботи з ціфровими документами через кабінет, відповідає окремий компонент "Сервіс цифрових документів", який використовує Ceph у якості сховища файлів.

Детальніше з дизайном компоненти "Сервіс цифрових документів" можна ознайомитися за посиланням

3.2. Обмін цифровими документами між підсистемами платформи

Файли цифрових документів є невід’ємною частиною сутності, в рамках створення якої вони були збережені
REST API підсистеми "Дата Фабрика" оперує лише UUID-ідентифікаторами та SHA256-гешами на рівні структур даних сутностей
При виконанні запиту на збереження сутності, яка містить UUID-ідентифікатори, Дата Фабрика очікує, що в бакеті "lowcode-file-storage" є наявні Ceph-документи з ключами, які відповідають конвенції іменування process/{processInstanceId}/{UUID} (значення processInstanceId передається у вигляді заголовка "X-Source-Business-Process-Instance-Id" разом з запитом), SHA256-геші яких співпадають з тими, які були передані разом с запитом
При виконанні запиту на отримання сутності, яка містить UUID-ідентифікатори, Дата Фабрика гарантує клієнту наявність у бакеті "lowcode-file-storage" Ceph-документів з ключами, які відповідають конвенції іменування process/{processInstanceId}/{UUID} (значення processInstanceId передається у вигляді заголовка "X-Source-Business-Process-Instance-Id" разом з запитом), SHA256-геші яких співпадають з тими, які передані як частина сутності
Доступ до файлів, завантажених як вкладення до сутності, на рівні підсистеми "Low-code" можливий лише через отримання даних цієї сутності та послідуюче отримання документа за UUID-ідентифікатором документа через компоненту "Сервіс цифрових документів"

3.3. Контракт взаємодії між підсистемами платформи

Канонічний вигляд тіла запиту до Дата Фабрики на збереження даних сутності з файловими вкладеннями

{
  "<file_property_name>": [
    {
      "id": "{UUID}",
      "checksum": "{SHA256-hash}"
    }
  ]
}

Канонічний вигляд відповіді Дата Фабрики на запит отримання даних сутності з файловими вкладеннями

{
  "<file_property_name>": [
    {
      "id": "{UUID}",
      "checksum": "{SHA256-hash}"
    }
  ]
}

3.4. Загальна структура Ceph-об’єктів, які задіяні в обміні між "Lowcode" та "Дата Фабрикою"

Назва атрибуту	Атрибут JSON-документа	Атрибут Ceph об’єкта	Значення
Ключ Ceph-об’єкта		key	Унікальний ідентифікатор Ceph-документу для збереження файла в області доступу поточного бізнес-процесу. Автоматично формується на базі згенерованого id згідно конвенції process/<processInstanceId>/<id>
Ідентифікатор цифрового документу	id	UserMetaData.id	Унікальний ідентифікатор файла, зформований з використанням генератора псевдо-випадкових чисел (cad2e994-0e32-4a9f-9959-b420e20d4522)
Назва файлу	name	UserMetaData.name	<Назва файлу>
Тип контента	type	Content-Type (UserMetaData.type)	application/pdf, image/png, image/jpeg
Розмір	size	Content-Length (UserMetaData.size)	<Розмір файлу>
Контент документа	content	input	<Контент файла>
Геш документа	checksum	(UserMetaData.checksum)	Згенерований SHA256-геш файла

Назва атрибуту

Атрибут JSON-документа

Атрибут Ceph об’єкта

Значення

Ключ Ceph-об’єкта

key

Унікальний ідентифікатор Ceph-документу для збереження файла в області доступу поточного бізнес-процесу. Автоматично формується на базі згенерованого id згідно конвенції process/<processInstanceId>/<id>

Ідентифікатор цифрового документу

UserMetaData.id

Унікальний ідентифікатор файла, зформований з використанням генератора псевдо-випадкових чисел (cad2e994-0e32-4a9f-9959-b420e20d4522)

Назва файлу

name

UserMetaData.name

<Назва файлу>

Тип контента

type

Content-Type (UserMetaData.type)

application/pdf, image/png, image/jpeg

Розмір

size

Content-Length (UserMetaData.size)

<Розмір файлу>

Контент документа

content

input

<Контент файла>

Геш документа

checksum

(UserMetaData.checksum)

Згенерований SHA256-геш файла

4. Сценарії взаємодії користувача з системою

4.1. Завантаження цифрових документів

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

Канонічний вигляд структури документа у тілі запиту на збереження даних форми через серверний додаток

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  }
}

Опис формату збереження документів в Ceph у процесі обробки запиту на виконання задачі

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  },
  "x-access-token": "<X-Access-Token>"
}

4.2. Вивантаження цифрових документів

На даній діаграмі зображено сценарій отримання сутності з файловими вкладеннями, яка була попередньо збережена у Дата Фабриці та послідуюча її підготовка для відображення на UI-формі задачі користувача.

Канонічний вигляд відповіді серверного додатоку на запит отримання даних форми

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  }
}

4.3. Підпис даних UI-форм з цифровими документами

На даній діаграмі зображено сценарій підпису даних з файловими вкладеннями в рамках виконання задачі користувачем, обробка даних в рамках бізнес-процесу та їх збереження в Дата Фабрику.

Канонічний вигляд структури документа у тілі запиту на збереження підписаних даних форми через серверний додаток

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  },
  "signature": "<e-Signature>"
}

Опис формату збереження документів з підписом в Ceph

{
  "data": {
      "passport_scans": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  },
  "x-access-token": "<X-Access-Token>",
  "signature": "<e-Signature>"
}

5. Моделювання UI-форм

5.1. Типова конфігурація поля типу "File" для налаштування адміністратором регламента

Розділ меню

Назва налаштування

Значення

Опис

Display

Label

<На розсуд адміністратора>

Текстовий опис поля для користувача

API

Property Name

<На розсуд адміністратора>

Назва поля у JSON-документі структури даних

File

Storage

URL

Збереження контента завантаженого файла на сервері

File

Url

/documents

Адреса сервісу цифрових документів

File

Display as Image(s)

false

Відображення піктограм для зображень, замість табличного вигляду

Data

Multiple Values

false

Підтримка завантаження декількох файлів

File

File Pattern

application/pdf,image/jpeg,image/png

Паттерн файлів, дозволених для завантаження

File

File Maximum Size

<На розсуд адміністратора>

Максимальний розмір одного файлу

5.2. JSON-схема опису структури UI-форми з полем типу "File"

{
  "components": [
    {
      "label": "<file_property_label>",
      "storage": "url",
      "key": "<file_property_name>",
      "type": "file",
      "url": "/documents",
      "input": true
    }
  ]
}