Первинне завантаження даних

Загальний опис

Розробка реєстру на Платформі може передбачати міграцію даних з наявного реєстру або реєстрів на Платформу. Дані в реєстрах можуть бути представлені в табличному вигляді так і мати додатково пов’язані з ними файли. В такому випадку адміністратору реєстру необхідно завантажити ці дані до реєстру на Платформі і такі дані називаються первинні.

Ролі користувачів

Адміністратор реєстру

Загальні принципи та положення

Підтримуються тільки завантаження даних в CSV-форматі.
Завантаження даних може відбуватись тільки в порожні таблиці.
Структура файлу має повністю відповідати структурі таблиці.
Завантаження відбувається в режимі streaming так, що нема потреби завантажувати весь файл в памʼять.
Завантаження файлів до ceph кошика тимчасового зберігання первинних даних відбувається через s3-сумісний компонент на веб-інтерфейсі.
Доступ з інтерфейсу адміністрування даних реєстру для додавання та видалення файлів надається тільки до кошику тимчасового зберігання.
При первинному завантаженні даних, запис здійснюється не через процедуру.
При первинному завантаженні даних, не застосовуються перевірки RBAC та RLS.
Зберігання звʼязків між операційною та історичною таблицями відбувається прозоро в утиліті первинного завантаження даних таблиць.
В один момент часу може готуватись завантаження тільки для однієї таблиці, оскільки всі інші файли будуть переноситись як пов’язані.
В якості роздільників колонок використовується ; а для розділення елементів в масиві використовується кома - ,
Завантаження даних відбувається в одній транзакції.

Високорівневий дизайн рішення

Сервіси та їх призначення

Вебінтерфейс адміністрування даних реєстру - вебінтерфейс для створення процесів завантаження посадових осіб та первинного завантаження даних.

Сервіс адміністрування даних реєстру - сервіс який надає REST API для створення запитів на завантаження посадових осіб, завантаження первинних даних.

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

Розгортання сервісів

Схема розгортання

Ключові сценарії взаємодії сервісів

Створення тимчасової схеми в операційній БД

Використання цієї функціональності можливо лише для реєстрів в режимі розробки.

При розгортанні реєстру, створюється додаткова схема sandbox та користувач з правами на створення, видалення, зміну таблиць в рамках цієї схеми.

Завантаження даних в тимчасову схему

Використання цієї функціональності можливо лише для реєстрів в режимі розробки.

Тимчасова схема використовується для розробки, і в ній дозволені прямі маніпуляції з даними, створення та видалення таблиць. Операції в цій схемі здійснюються за допомогою веб-застосунку pgAdmin. Основною метою даної схеми в контексті первинного завантаження є:

Приведення наявних даних (історичних даних) до вигляду який відповідає сутностям в реєстрі на Платформі.
Наприклад: Конвертація типів, зміна структури зберігання даних тощо.
Побудова звʼязків між сутностями реєстру та історичними даними. Наприклад: Використання посилання на довідники які вже використовуються реєстром на Платформі.

Завантаження даних до кошика тимчасового зберігання первинних даних

Завантаження CSV файлу та, при потребі, повʼязаних з даними файлів, до s3 сумісного сховища відбувається безпосередньо з веб-інтерфейс адміністрування даних реєстру. Завантаження файлів може відбуватись в декілька ітерацій. Після завантаження файлів вони відображаються в табличному вигляді.

Figure 1. Структура форми для завантаження

Figure 2. Структура кошика тимчасового зберігання первинних даних

Таким чином компонент який використовується для завантаження даних дозволяє завантажувати тільки один файл з розширенням csv і завантажує його в корінь кошика.

Компонент для завантаження пов’язаних файлів дозволяє додавати множину файлів і завантажує їх в директорію content

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

Завантаження готових даних в операційну базу реєстру

Після завантаження даних до кошика тимчасового зберігання первинних даних адміністратор реєстру має вказати в яку структуру БД будуть завантажуватись дані, та підтвердити свій вибір.

Процес завантаження включає в себе потокову обробку файлу таким чином, що кожен рядок CSV зберігається у відповідну структуру та додатково створюється запис про вставку в історичній таблиці. В якості даних для службових полів в історичній таблиці використовується значення admin для того хто зберіг дані та initial_lodad для значення підписів.

Завантаження даних з пов’язаними файлами в операційну дану реєстру

Якщо сутність що завантажується містить пов’язані файли, то спочатку відбувається перенос файлів до кошику зберігання файлів та збереження відповідного ідентифікатора в таблицю ddm_initial_load_file_references разом з оригінальною назвою файлу. В подальшому при переносі даних з csv до операційної БД для поля що містить файлові посилання відбувається заміна назви файлу на його ідентифікатор.

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

Все дії запуску, процесу перенесення пов’язаних файлів, результату виконання та помилок у разі їх виникнення відображаються в логах та прив’язані до ідентифікатора запиту, що запустив цей процес і доступні для перегляду в Kibana

Низькорівневий дизайн сервісів

Вебінтерфейс адміністрування даних реєстру

Ключові сценарії

Запуск процесу завантаження посадових осіб.
Завантаження та видалення файлів до тимчасового кошика зберігання первинних даних.
Перегляд вмісту кошика для тимчасового зберігання первинних даних.
Запуск процесу завантаження первинних даних до операційної БД.
Отримання ключа і секрету для доступу до s3-кошика.

Структура меню

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

Завантаження первинних даних сутності реєстру.
Завантаження посадових осіб.

Компонент по роботі з S3-кошиком

Компонент являє собою існуючий drag-n-drop таблицю для файлів, з реалізацією завантаження на події компоненти. (додавання, видалення, перегляд вмісту по ключу).

При завантаженні компонента відбувається перегляд відповідного s3-кошика для налаштованого шляху.

Також на компоненті налаштовується перевірка розширень файлів.

Для того, щоб не створювати додаткове навантаження на Сервіс адміністрування даних реєстру при роботі з S3-кошиком яким міг би виступати лише як proxy для Rados Gateway компонент інтерфейсу працює безпосередньо з Rados Gateway.

Для автентифікації JS s3-клієнта, ключ і секрет отримується запитому до Сервісу адміністрування даних реєстру.

Сервіс адміністрування даних реєстру

Ключові сценарії

Запуск K8s Job по завантаженню посадових осіб.
Запуск K8s Job по завантаженню первинних даних сутності реєстру.
Отримання переліку таблиць доступних для завантаження.
Отримання статусу виконання завантаження.

Технічний стек

Як основний framework використовується Spring Boot 3.15 та використання Native Image та in container build.

Аудит

Дії користувачів які фіксуються в аудиті:

Старт процесу завантаження посадових осіб.
Отримання доступу до завантаження даних в s3 кошик.
Старт процесу завантаження первинних даних.
Статус завершення процесу завантаження первинних даних.

База даних

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

Утиліта первинного завантаження сутностей в таблиці

Ключові сценарії

Копіювання даних з тимчасового кошика зберігання даних до кошика архівного зберігання даних.
Запис даних з csv файлів до операційної БД в таблиці сутностей та історичних таблиць.

Технічний стек

Як основний framework використовується Spring Boot 3.15 та використання Native Image та in container build.

Вхідні параметри

USER_ACCESS_TOKEN - токен користувача який ініціалізував процес завантаження даних+ TABLE_NAME - назва таблиці в яку відбувається завантаження
CSV_FILE - назва csv файла дані з якого будуть завантажуватись в таблицю вказану в параметрі TABLE_NAME
REQUEST_ID - ідентифікатор X-B3-TraceId для відслідковування

Аудит

Дії користувачів які фіксуються в аудиті:

Старт процесу завантаження
Завершення процесу завантаження

База даних

Окрім користувача з доступом до вставки даних в таблиці реєстру існує окрема таблиця ddm_initial_load_file_references

CREATE TABLE public.initial_load_file_references (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY NOT NULL,
    file_bucket_uuid UUID NOT NULL,
    initial_load_file_name TEXT NOT NULL,
    CONSTRAINT pk_initial_load_file_references PRIMARY KEY (id)
);

Table 1. Призначення колонок таблиці
Назва колонки	Призначення	Приклад
id	ідентифікатор запису	42
file_bucket_uuid	ідентифікатор з яким було збережено файл до кошика збереження файлів	dd969351-6255-4ae3-ab44-098ea8425c30
initial_load_file_name	назва файлу в csv-файлі	sidorenko_passport_scan.jpg

Завантаження даних до операційних таблиць.

<createTable tableName="person" ext:historyFlag="true">
    <column name="user_id" type="UUID" defaultValueComputed="uuid_generate_v4()">
        <constraints nullable="false" primaryKey="true" primaryKeyName="pk_property_id"/>
    </column>
    <column name="first_name" type="TEXT"/>
    <column name="last_name" type="TEXT"/>
    <column name="passport" type="FILE"/>
    <column name="inn" type="TEXT"/>
</createTable>

Приклад SCV файла

firstName;lastName;passport;inn
Петро;Петренко;petrenko_passport_scan.jpg;11111111
Микола;Сидоренко;sidorenko_passport_scan.jpg;22222222

Figure 3. Приклад організації s3-кошика init-data-load-raw для завантаження даних

Кроки завантаження даних:

Перенесення файлів з initial-data-load-raw папки content до file-ceph-bucket зі зміною імені на ідентифікатор (uuid).
Збереження в таблиці ddm_initial_load_file_references відповідності імені до ідентифікатора.
Динамічне формування запиту вставки сутностей за допомогою pg copy в операційну і історичну таблицю.
Потокове опрацювання csv файлу з заміною назви файлів на ідентифікатор за допомогою таблиці ddm_initial_load_file_references
Вставка даних в операційну таблицю та історичну таблицю.
У випадку помилки вставки в БД, видалення файлів з file-ceph-bucket за ідентифікаторами з ddm_initial_load_file_references
Видалення даних з таблиці ddm_initial_load_file_references

З міркувань швидкодії всі файли переносяться до сховища файлів без перевірки використання їх в даних таблиці.

Figure 4. Перенесення повʼязаних файлів

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

Високорівневий план розробки

План розробки

Розробка нового вебінтерфейсу
- POC для обрання drug-n-drop компонента.
- Локалізація і конфігурація логотипів та favicon
- Перенос екранів звантаження посадових осіб.
- Імплементація завантаження даних в S3 сумісний кошик.
Розробка сервісу
- Перенос API для завантаження посадових осіб
- Імплементація точок інтеграції для отримання інформації про таблиці (інтеграція з БД)
- Імплементація точок інтеграції для отримання ключа і секрета для s3-кошика (інтеграція з OpenShift API)
Розробка утиліти
- Реалізація переносу файлів
- Реалізація завантаження даних
- Реалізація механізму очистки кошика зберігання файлів у випадку помилок при завантаженні даних
Адмін портал
- Видалення коду по завантаженню посадових осіб
- Переіменування згадки адмін порталу
Control plane
- Додавання посилань на новий портал
- Зміна назви адмін порталу на екранах швидких посилань та управління розгортання компонентів реєстру.
- Додавання екрану управління розгортанням порталу управління даними реєстру
Розгортання БД
- Створення додатковох користувачів (ролей) в Postgres та схеми на етапі розгортання реєстру.
Логування
- Побудова Kibana Dashboard для перегляду перебігу процесу завантаження