ЕСОЗ - публічна документація

ARCHIVE_(GraphQL) Update Person_Дубль

Owned by Dmytro Omelchenko (SoE eHealth)
Last updated: Jul 04, 2024 by Yuliia Mazur (UA SoE eHealth)
8 min read

Мета

Надати можливість адміністратору НСЗУ/Дата стюарту (співробітник НСЗУ з відповідними скоупи) зберегти оновлення персональних даних персон, на основі отриманих від персон офіційних звернень в НСЗУ, які по факту є легальною авторизацією на зміну персональних даних пацієнтів.

Схема

Дизайн

Почати редагування, гляхом вибору 'Редагування'

Ввести зміни

Порівняння змін перед підписом

Специфікація

"Creates a person_request record with the status SIGNED (in il.person_request) with following update of a person record (in mpi.persons)." createPersonRequest( input: CreatePersonRequestInput! ): CreatePersonRequestPayload

 

 

""" Input for `createPersonRequest` mutation. User must have a scope **person_request:write_nhs** """ input CreatePersonRequestInput { "Signed data to create Person_Request for update of a person record in mpi.persons" signedContent: SignedContent! "This parameters is MPI.person.(id of edited person).inserted_at, saved in FE at the beginning of editing process and should be transferred to BE for validation of parallel editing" updatedAtForValidation: DateTime! } """ Return type for `createPersonRequest` mutation. """ type CreatePersonRequestPayload { "Updated data of a Person - from mpi.persons" person: Person! }

 

Ключові положення

Процес ініціюється співробітником НСЗУ (тільки через адміністративну панель НСЗУ) з відповідними скоупами та ініціює передачу (за допомогою graphQL мутації) підписного контенту (signed_content). Це включає JSON з персональними даними, де id існуючої персони та no ключів та параметрів методів аутентифікації.

Він має схожість до частини оновлення (update part) в поцесі IL.Update-person-request (w/o declaration) , але є основні відмінності:

  1. Запис по Person_request створюється на BE в статусі SIGNED на основі signed_content(який підписано цифровим підписом) з FE. Без проміжних записів до DB з такими статусами, як NEW, APPROVED.

  2. Під час процесу оновлення персональних даних персони до таблиці MPI.person відсутня необхідність в підтвердженні від персони в форматі ONLINE/OFFLINE.

  3. Є два нових параметри для контролю об'єму змін та уникнення ризику надлишкової автоматичної дедублікації:

    1. PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ADMIN

    2. PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ADMIN
      Дані параметри можуть бути включені\виключені за допомогою:

      1. PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ACTIVE = true

      2. PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ACTIVE = true

  4. Наявні наступні обов'язкові поля в запиті:

    1. nhs_request_number nhs_request_comment

  5. Та є наступні відмінності в полях, значеннях та перевірках:

    1. $.patient_signed та $.process_disclosure_data_consent не повинні бути вказані в запиті та тому значення null має бути встановлено в IL.person_requests. Та нарешті, в таблиці MPI.persons дані значення повинні бути перезаписані.

    2. друкована форма не обов'язкова

    3. IL.person_requests.(new record).channel = 'NHS'

  6. Один додатковий параметр переданий від FE до BEupdatedAtForValidation

  7. second_name та unzr мають бути встановлені в null. no_tax_id та tax_id можуть бути передані в повідомленні як null, якщо вони обидва встановлені в null.

 

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

Скоупи та ролі

Назва скоупу

Ролі

Опис

Назва скоупу

Ролі

Опис

Новий

person_request:write_nhs

  1. ADMIN

  2. NHS ADMIN VERIFIER

Скоуп для створеня записуperson_request з послідуючим оновлення запису person. Без погодження персони по online/offline . Оскільки паперовий запит до НСЗУ - це юридична авторизація на зміни персональних даних персони.

Пов'язані статті

#

Шлях

Посилання та стаття

#

Шлях

Посилання та стаття

1

E-Health > Persons > Ідентифіковані персони > Person Requests Technical Requirements

IL.Create/Update person request (w/o declaration)

Create/Update person request

Create/Update person request

2

Public. Medical Service Provider Integration Layer > Person Requests

https://uaehealthapi.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/person-requests

https://uaehealthapi.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/person-requests

Авторизація

  1. Перевірити валідність токену доступу

    1. Повернути помилку 401 в разі неуспішної валідації

  2. Перевірити скоупи користувача person_request:write_nhs

    1. Повернути помилку 403 в разі невалідних скоупів

Цифровий підпис

Декодувати контент: що зашивровано в цифровому підписі.
Використати цифровий підпис запиту. Метод перевіряє цифровий підпис та повертає результат.
Див сервіс specification

Перевірити ДРФО

  1. Перевірити, що DRFO в деталях сертифікату присутній в запиті

  2. Перевірити, що DRFO в деталях сертифікату відповідає DRFO для Party

    1. Отримати party.tax_id використовуючи employee_id в даних персони

    2. Порівняти DRFO в сертифікаті з party.tax_id

      1. Змінити DRFO та TAX_ID на великі літери

      2. Порівняти DRFO та TAX_ID на літери кирилиці

      3. Змінити DRFO на кирилицю та перевірити на коректність

    3. В разі неуспішних валідацій - віддати помилку 422

Співвідношення латиниці та кирилиці

Перевірка підписного контенту

Отримати глобальні параметри

Для подальших перевірок, викликати Global parameters для отримання:

  • no_self_auth_age 

cURL приклад

 

Валідації

Валідації

1

Перевірка на одночасні корегування даних (нове)

Якщо дані персони не змінювались іншими користувачами (MSP, NHS) в системі НСЗУ. Шляхом попереднього збереження updateAt (збережено після початкового запиту персональних даних під час початку процесу редагування) та перевірити в момент збереження даних:

  • Якщо MPI.person.(id = $.id).update_At = $.updatedAtForValidation то Ok

    • в іншому випадку повернути помилку 422, 'Person's data were changed while you were editing. Please repeat your steps for update'

2

Перевірити статус персони в базі даних та інструментах дедублікації

  • Якщо person.id в запиті, то 

    • якщо $.person.id в UUID та UUID_version($.person.id is UUID) = 4 то ok

      • в разі помилки, повернути помилку 422, “person.id is not UUID type or UUID version is not appropriate“

    • знайти персону по person.id в MPI 

      • в разі помилки повернути код 404, "not found"

    • Якщо MPI.persons.($.id).status = “active” то ok

      • в разі помилки повернути код 422 - та повідомлення "The Person is not active, therefore any updates of personal data are prohibited”

    • Скор рівня оновлень

      Перевірити декодований підписний контент шляхом використання інструментів дедублікації в частині двої перевірок . I.e.

      • Перевірка дедублікації 1 перевірити, що рівень змін є “so high” що потрібно призупинити (відмовити) в збереженні змін.

        • якщо calculated_score (current data, updates_of_Person) >  PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ADMIN
          то Перевірка 1 пройдена, пройти інші перевірки

          • в іншому випадку повернути код 409, "Level of conducted changes is higher than permitted. Updates can't be saved. Please check whether you have selected appropriate Person for changes. Calculated score: <calculated_score>. Permitted score: PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ADMIN) "

      • Перевірка дедублікації 2 - на відсутність такої персони, яка дуже схожа на поточну з врахування корегувань

        • якщо calculated_score (updates_of_Person, other_similar_Persons) <  PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ADMIN
          то Перевірка 2 пройдена, пройти ініші перевірки

          • в іншому випадку повернути код 409, "We have found Person(s) with high similarity in DB. Calculated score is equal or greater than permitted PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ADMIN. Please check whether you have selected appropriate Person for changes and investigate possible duplicates of the Person."

    • Перевірки дедублікації 1 та 2 можуть бути вимкнені шляхом встановлення кожного окремо наступні параметри

      • PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ADMIN_OFF = true

      • PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ADMIN_OFF = true

3

Перевірити “patient_signed” признак.

Дане поле не повинно передаватися. І тому BE не повинен здійснювати пошук його в DB

4

Перевірити “process_disclosure_data_consent” признак.

Дане поле не повинно передаватися. І тому BE не повинен здійснювати пошук його в DB

5

Перевірити довірену особу

Якщо для персони age < prm.global_parameters.no_self_auth_age то

перевірити на наявність confidant_person

  • в разі помилки повернути код 422 - та повідомлення "Confidant person is mandatory for children"

Перевірити вік довіреної персони >= prm.global_parameters.no_self_auth_age:

  • в разі помилки повернути код 422, " Third person must be adult”

перевірити наявність секретного слова:

  • in case of error return 422

6

Перевірити "tax_id"

  • tax_id відповідає шаблону валідації - `^[0-9]{10}$`

    • якщо не відповідає, повернути помилку 422 "string does not match pattern ..."

  • співробітник НСЗУ може оновити birth_date, але

  • (If VALIDATE_TAX_ID_WITH_BIRTH_DATE_GENDER_AND_CHECK_SUM is false then ok

    • If (GetBirthDateFromTaxId($.tax_id) != $.birth_date) then

      • в разі помилки повернути код 422 “Person's tax ID is not valid. “)

    • else ok

  • Співробітник НСЗУ може оновити tax_id:

    • з null на tax_id2, на наявність персони з таким же tax_id2
      if tax_check_cnt_1 = 0 then ok
      Для отримання tax_check_cnt_1: select count(*) tax_check_cnt_1 select * from persons where tax_id = $.person.tax_id and status = 'active' and id <> $.person.id and is_active = true

      • в разі помилки повернути код 422 “There is another active person in DB with the same Tax_id. Updates to Personal data were not saved. “

    • Та з tax_id1 на tax_id2, на наявність персони з таким же tax_id2
      if tax_check_cnt_1 = 0 then ok
      Для отриманняtax_check_cnt_1: select count(*) tax_check_cnt_1 select * from persons where tax_id = $.person.tax_id and is_active = 'active' and id <> $.person.id

      • в разі помилки повернути код 422 “There is another active person in DB with the same Tax_id. Updates to Personal data were not saved. “

    • з tax_id1 на null

    • з null на null

7

Перевірити признак "no_tax_id"

  • "no_tax_id" може бути null в повідомленні, якщо tax_id є також null.

  • If "no_tax_id"= true, tax_id повинен бути пустим

    • в разі помилки повернути код 422

  • If "no_tax_id"=false and age>14, tax_id повинен бути наявним

    • в разі помилки повернути код 422

8

Перевірити документи персони

  1. issued_at, issued_by обов'язкові для документів

  2. Перевірити дати

    1. issued_at <= now() та issued_at => birth_date

      1. в разі `issued_at > now()` відобразити помилку 422, "Document issued date should be in the past"

      2. в разі `issued_at < person.birth_date` відобразити помилку 422, "Document issued date should greater than person.birth_date "

    2. expiration_date > now()

      1. в разі помилки відобразити 422, "Document expiration_date should be in the future"

      2. expiration_date обов'язкові для document_type

        • NATIONAL_ID

        • COMPLEMENTARY_PROTECTION_CERTIFICATE

        • PERMANENT_RESIDENCE_PERMIT

        • REFUGEE_CERTIFICATE

        • TEMPORARY_CERTIFICATE

        • TEMPORARY_PASSPORT

      3. в разі помилки повернути 422, "expiration_date is mandatory for document_type $.documents.type"

  3. Перевірити documents_type.number у відповідності до схеми json 

    1. PASSPORT - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`

    2. NATIONAL_ID - `^[0-9]{9}$`

    3. BIRTH_CERTIFICATE - `^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$`

    4. COMPLEMENTARY_PROTECTION_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`

    5. REFUGEE_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`

    6. TEMPORARY_CERTIFICATE - `^(((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{4,6}|[0-9]{9}|((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{5}\\/[0-9]{5})$`

    7. TEMPORARY_PASSPORT - `^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$`

  4. 'unzr' може приймати значення null в повідомленні.

  5. якщо `unzr` існує і не є null і відповідає "^[0-9]{8}-[0-9]{5}$" перевірити їх 8 символів = birth_date

    1. в разі помилки повернути 422, повідомлення "Birthdate or unzr is not correct"

  6. якщо documents.type=NATIONAL_ID

    1. перевірити, що unzr наявний в запиті, в разі помилки повернути 422, повідомлення "unzr is mandatory for document type NATIONAL_ID"

  7. Документу numbersmaxLength < 25 

9

Перевірити поля запиту NHS

  • nhs_request_number, nhs_request_comment обов'язкові

  • Перевірити їх у відповідності до схеми json  

    • якщо не відповідає, повернути помилку 422 “ required property %{property} was not present"

 

Схема валідації JSON

Перелік додаткових вимог для панелі адміністрування НСЗУ

Основною приймається дана схема JSON Schema validator (Create/Update person request | Update person request ). Окрім:

  1. “patient_signed" та "process_disclosure_data_consent" не обов'язкові і не мають бути наявними.

  2. дозволити значення null в полі second_name об'єкту персон.

    1. "second_name": { "type": [ "string", "null" ] }

  3. дозволити значення null в полі unzr об'єкту персон

    1. "unzr": { "type": [ "string", "null" ], "pattern": "^[0-9]{8}-[0-9]{5}$" }

  4. дозволити в повідомлення обидва tax_id, no_tax_id зі значенням null якщо вони обидва приймають значення null

  5. ключ updatedAtForValidation та ключ групування nhs_request_number, nhs_request_comment перевіряються згідно наступної схеми валідації:

 

 

Виконання

Оновлення пошуку person_requests в IL.person_requests

Пошук запиту персони в IL.person_requests для попередження випадків одночасного оновлення даних:

Відмінити person_requests records в IL.person_requests

Змінити статус всіх знайдених запитів персони:

Створити новий запис в IL.person_requests

  1. Додати [new record] до IL.person_requests:

    1. Встановити status = 'SIGNED'. 

    2. Встановити id персони, person_id = $.person.id

    3. Встановити inserted_at= now() (отримати поточні дату та час)

    4. Встановити inserted_by - user_id (отримати користувача з токену)

    5. Встановити channel, IL.person_request.(newrecord).channel = 'NHS'

    6. Встановити printout_form = null

Зберегти signed_content у відповідному бакеті Person_request

Оновити персону в MPI.persons

  1. Оновити дані персони в MPI.persons.(id = $.person.id)з вказаними новими даними $ (включно два $.nhsRequestNumber та$.nhsRequestComment).

  2. Встановити updated_at - now() (Отримати поточну дату та час)

  3. Встановити updated_by - user_id (Отримати користувача з токену)

  4. Створити відповідний запис на основі вказаних нових даних $ (включно два $.nhsRequestNumber та$.nhsRequestComment) в:

    1. MPI.person_documents

    2. MPI.person_phones

    3. MPI.person_addresses

Направити персону на верифікацію

Створити або оновити існуючий запис в таблиці person_verifications для персони у відповідності до логікив секції нижче. Також, встановити:

  • updated_at = now()

  • updated_by = user uuid

  • inserted_at = now() (для нових записів)

  • inserted_by = user uuid (для нових записів)

Мануальна верифікація NHS

Встановити верифіцію персони у відповідності до логіки https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249206422/IL.Sign+person+request+modified#Manual-NHS-verification

Верифікація по реєстру DRFO

Встановити верифіцію персони у відповідності до логіки https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249206422/IL.Sign+person+request+modified#DRFO-registry-verification

Верифікація по актам смерті з реєстру DRACS

Встановити верифіцію персони у відповідності до логіки https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249206422/IL.Sign+person+request+modified#DRACS-death-acts-registry-verification

Розрахувати кумулятивний статус верифікації

Розрахувати кумулятивний статус верифікації у відповідності до логіки https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249206422/IL.Sign+person+request+modified#Calculate-cumulative-verification-status

ЕСОЗ - публічна документація