API. Create Care Plan Activity_UA

1 Ціль
2 Основні положення
3 Специфікація
4 Авторизація
5 Перевірити юридичну особу
6 Перевірити План лікування
7 Перевірити пацієнта
8 Перевірити користувача
9 Первірити електронний підпис
10 Перевірити активність
- 10.1 Перевірити ідентифікатор активності
- 10.2 Перевірити ідентифікатор плану лікування
- 10.3 Перевірити автора активності
- 10.4 Перевірити деталі активності
  - 10.4.1 1. Тип
  - 10.4.2 2. Продукт
  - 10.4.3 3. Код статусу
  - 10.4.4 4. Посилання на причину
  - 10.4.5 5. Ціль
  - 10.4.6 6. Кількість
  - 10.4.7 7. Плановість
  - 10.4.8 8. Місце надання послуги
  - 10.4.9 9. Виконавець
  - 10.4.10 10. Добова кількість
  - 10.4.11 11. Медична програма
  - 10.4.12 12. Мітка “не виконувати”
11 Логіка сервісу
12 Ціль
13 Основні положення
14 Специфікація
15 Авторизація
16 Перевірити юридичну особу
17 Перевірити План лікування
18 Перевірити пацієнта
19 Перевірити користувача
20 Первірити електронний підпис
21 Перевірити активність
- 21.1 Перевірити ідентифікатор активності
- 21.2 Перевірити ідентифікатор плану лікування
- 21.3 Перевірити автора активності
- 21.4 Перевірити деталі активності
  - 21.4.1 1. Тип
  - 21.4.2 2. Продукт
  - 21.4.3 3. Код статусу
  - 21.4.4 4. Посилання на причину
  - 21.4.5 5. Ціль
  - 21.4.6 6. Кількість
  - 21.4.7 7. Плановість
  - 21.4.8 8. Місце надання послуги
  - 21.4.9 9. Виконавець
  - 21.4.10 10. Добова кількість
  - 21.4.11 11. Медична програма
  - 21.4.12 12. Мітка “не виконувати”
22 Логіка сервісу

Ціль

Даний веб-сервіс дозволяє додати активність до визначеного Плану лікування.

Основні положення

З одним запитом може бути додана тільки одна активність до Плану лікування
Активність може бути додана тільки співробітником, який має дозвіл, наданий пацієнтом на редагування даних Плану лікування
Активності додаються в асинхронний спосіб. Результатом додаткої задачі активності повинне бути посилання на створену активність (див. Get Care plan activity by ID).
Активність повинна бути підписана Електронним підписом. Підписаний контент зберігається в файловому сховищі.

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

Apiary

Авторизація

Перевірити валідність токену доступу
- в разі помилки валідації - повернути код 401 (“Invalid access token”)
Перевірити строк дії токену доступу
- в разі помилки - повернути код 401 (“Invalid access token”)
Перевірити скоупи користувачів на наявність запрошеної операції (scope = 'care_plan:write')
- в разі відсутності запрошеного скоупу повернути код помилки 403 (“Your scope does not allow to access this resource. Missing allowances: care_plan:write”)

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

Отриманий client_id з токену
Перевірити статус юридичної особи (status = ACTIVE)
- в разі помилки - повернути код 409 ('client_id refers to legal entity that is not active'
Перевірити тип юридичної особи відповідє конфігураційному параметру ME_ALLOWED_TRANSACTIONS_LE_TYPES
- в разі помилки - повернути код 409 ('client_id refers to legal entity with type that is not allowed to create medical events transactions')

Перевірити План лікування

Отримати ідентифікатор Плану лікування з URL
Первірити План лікування:
- належить пацієнту (з url)
  - в разі помилки - повернути код 422 ('Care plan with such id is not found')
- не в final status
  - в разі помилки - повернути код 422 ('Invalid care plan status')
- Для Плану лікування period.end >= current date.
  - в разі помилки - повернути код 422 ('Care Plan end date is expired')

Перевірити пацієнта

Отримати person_id з URL
Перевірити, що статус пацієнта активний
- в разі помилки - повернути код 409 ('Person is not active')
Перевірити, що verification_status не рівний NOT_VERIFIED.
- в разі помилки повернути код 409, "Patient is not verified"

Перевірити користувача

Отримати user_id з токену.
Перевірити, що користувач належить активному та погодженому співробітнику для даної юридичної особи (token), що:
- має активний дозвіл наданий пацієнтом на редагування даних Плану лікування (id плану лікування з URL)
  - Повернути 403 ('Access denied') у випадку, коли співробітник не має дозволу на редагування

Первірити електронний підпис

Перевірити, що на запит закладено підпис
- в разі помилки - повернути код 422 (“document must be signed by 1 signer but contains 0 signatures”)
Перевірити валідність цифрового підпису, та строк його дії
Перевірити, що цифровий підпис належить автору Плану лікування ($.author)
- Первірити, що DRFO електронного підпису та party.tax_id автору співпадають
  - в разі помилки - повернути код 409 (“Signer DRFO doesn't match with requester tax_id“)

Перевірити активність

Активність повинна бути валідована/перевірена. Користувач заповнює наступні поля в активності:

Перевірити ідентифікатор активності

Перевірити, що заповнено значення в полі field $.id

Перевірити, що він унікальний в комбінації з Планом лікування та має формат UUID
- Повернути 422 ("Activity with such id already exists")

Перевірити ідентифікатор плану лікування

Ідентифікатор повинен бути частиною підписного контенту в $.care_plan, як частина запиту.

Перевірити, що значення відповідає ідентифікатору плану лікування з URL
- в разі помилки - повернути код 409 ('Care Plan from url does not match to Care Plan ID specified in body')

Перевірити автора активності

Перевірити, що заповнене значення поля $.author

Перевірити, що спеціальність належить користувачу та юридичної особи (з token)
Співробітник є:
- користувачем, який має активний дозвіл на редагування Плану лікування
- належить користувачу
  - в разі помилки - повернути код 422 ('User is not allowed to create care plan activity for the employee')

Перевірити деталі активності

1. Тип

Перевірити заповненність значенням поля $.detail.kind

Перевірити значення в форматі enum: medication_request, service_request
- Повернути помилку 422 ('value is not allowed in enum')

2. Продукт

Перевірити заповненність значенням поля $.detail.product_reference

Якщо $detail.kind=medication_request:

Перевірити, що посилання на мед ресурс є валідним.
- Повернути помилку 422 ('Cannot refer to service for kind = medication_request')
Перевірити мед препарат:
- на активність
  - в разі помилки - повернути код 422 ('Medication should be active')
- тип дорівнює INNM_DOSAGE
  - в разі помилки - повернути код 422 ('Medication does not exist')
Перевірити, що відсутні дублі активностей в Плані лікування (status=scheduled, in_progress) з тим самим мед препаратом
- Повернути 422 (“Another activity with status ‘scheduled' or ‘in_progress' already exists in the current Care plan”)

Якщо $.detail.kind=service_request:

Перевірити, що значення є посиланням на сервіс (service) чи групу сервісів (service_group)
- Повернути 422 ('Cannot refer to medication for kind = service_request')
Перевірити, що сервіс (service) чи група сервісів (service_group) активні
- Повернути 422 ('<Service/Service group> should be active')
Перевірити, що в Плані лікування відсутні активності (status=scheduled, in_progress) з тим самим сервісом (service) чи групою сервісів (service_group)
- Повернути 422 (“Another activity with status ‘scheduled' or ‘in_progress' already exists in the current Care plan“)

3. Код статусу

Перевірити заповненність значенням поля $.detail.reason_code

Перевірити, що значення відповідає допустимим значенням з довідника eHealth/ICD10_AM/condition_codes
- в разі помилки - повернути код 422 ('value is not allowed in enum')

4. Посилання на причину

Перевірити заповненність значенням поля $.detail.reason_reference

Перевірити, що значення посилань відповідає значенням з масиву медичних станів (condition), обстежень (observation) або діагностичних звітів (diagnostic report) або клінічних оцінок.
- в разі помилки - повернути код 422 ('value is not allowed in enum')
Перевірити, що кожне посилання:
- валідна медична подія
- належить пацієнту ($.subject)
  - в разі помилки - повернути код 422 ('<medical event type> with such ID is not found')
Якщо $.detail.reason_reference=clinical_impression:
- Перевірити, що клінічна оцінка це валідна основа для clinical_impression.code.coding.code та CLINICAL_IMPRESSION_PATIENT_CATEGORIES_<CODE.CODING.CODE>_VALIDITY_PERIOD конфігураційного параметру: різниця між now() та clinical_impression.inserted_at дата повинні бути меньше ніж значення конфігураційного параметру (вказано в config для відповідної категорії плану лікування) для коду клінічної оцінки
  - в разі помилки - повернути 422 ("Clinical impression with patient category exceeds validity period")
- Перевірити, що клінічна оцінка базується на активному налаштуванні бізнес-правил (існуючий запис в колекції rule_engine_rules зі is_active=true, code.code=clinical_impression.code.coding.code, code.system=clinical_impression.code.coding.system)
  - якщо істина - перевірити, що клінічна оцінка досі відповідає конфігураційному правилу (https://e-health-ua.atlassian.net/wiki/spaces/PCR/pages/16741466119/UPD+Submit+Encounter+Data+Package+modified+EN#Validate-Clinical-impression )
    - в разі помилки - повернути 422 (“Clinical impression with patient category does not correspond to rule engine rule“)
  - якщо не істина - пропустити перевірку правил

5. Ціль

Перевірити заповненність значенням поля $.detail.goal

Перевірити, що значення відповідає значенням з довідника eHealth/care_plan_activity_goals
- в разі помилки - повернути код 422 ('value is not allowed in enum')

6. Кількість

Перевірити значення поля $.quantity (якщо надано)

Перевірити, що $.quantity.value не пусте, число більше нуля
- Повернути помилку валідації схеми - 422
Встановити remaining_quantity.value = $.quantity.value

7. Плановість

Якщо вказано, перевірити, що дані відповідають одному з полів $.detail.scheduled_[x]: scheduled_timing, scheduled_period або scheduled_string.

Повернути код 422 ('Only one of the parameters must be present') якщо вказано більше ніж одне

Перевірити вказане значення scheduled_timing:

Перевірити, що схема відповідає типу таймінг
- в разі помилки валідації схеми - повернути код 422
Якщо вказано, перевірити значення event для $.CarePlan.Period
- в разі помилки - повернути код 422 ('event is not within care plan period range')
Якщо вказано, перевірити bounds_period для $.CarePlan.Period
- в разі, якщо для bounds_period.end отримана помилка валідації - повернути код 422 ('Period end time must be within care plan period range, after period start date')
- в разі, якщо для bounds_period.start отримана помилка валідації - повернути код 422 ('Period start time must be within care plan period range')
Якщо вказано, перевірити bounds_duration для $.CarePlan.Period. Порахувати обмеження дати старту дії як дату початку дії плану лікування у випадку, коли активності були створені до дати створення плану лікування. В противному випадку, якщо активності створені в період виконання плану лікування - обмеження для дати початку розраховуються як дата створення активності. Обмеження зати завершення: як обмеження для дати початку плюс кількість днів вказані в bounds_duration.
- Якщо поле comparator для bounds_duration - використати його для порівняння значення bounds_duration та тривалості плану лікування (possible values >, >=, =, <=, <)
- В разі помилки - повернути код 422 ('Bounds duration must be within care plan period range')
Якщо вказано, перевірити поле when на відповідність значення значенням довідника EVENT_TIMING
- в разі помилки - повернути код 422 ('value is not allowed in enum')
Якщо вказано, перевірити bounds_range для $.CarePlan.Period: розрахувати обмеження для початку - дата завершення для bounds_range.low та bounds_range.high як описано для bounds_duration (але без поля comparator). Також, перевірити low.code = high.code, high.value > low.value
- для випадку помилки валідації bounds_range.low - повернути код 422 ('low must be within care plan period range, less than high, have the same code as high')
- для випадку помилки валідації bounds_range.high - повернути код 422 ('high must be within care plan period range')

Перевірити вказане значення поля scheduled_period:

Перевірити значення на відповідність схеми типу Period
- в разі помилки валідації - повернути код 422
Перевірити значення для $.CarePlan.Period
- для помилки валідації period.end - повернути код 422 ('Period end time must be within care plan period range, after period start date')
- для помилки валідації period.start - повернути код 422 ('Period start time must be within care plan period range')

8. Місце надання послуги

Перевірити вказаного значення поля $.detail.location

Перевірити, що значення є валідним посилання на підрозділ
Перевірити, що підрозділ активний та юридична особа підрозділу має активний статус
- Повернути 422 ('Division is not active')

9. Виконавець

Перевірити вказане значення в полі $.detail.performer

Перевірити, що значення є валідним посилання на співробітника
Перевірити, що співробітник активний та погоджений
- Повернути 422 ('Invalid employee status')

10. Добова кількість

Перевірити вказане значення в полі $.detail.daily_amount.

Перевірити тип активності medication_request
- Повернути помилку 422 ('Field is allowed for medication request activities only') для випадків коли тип не дорівнює medication_request

11. Медична програма

Перевірити вказане значення в полі $.program

Перевірити, що програма існує та активна
- якщо не знайдено або is_active==false повернути код 404 "Program not found"
Перевірити, що продукт доступний для вказаної програми:
- Якщо продукт це медпрепарат medication - перевірити, що медпрепарат має вказаний бренд, який є активним для програми (таблиця program_medications)
  - якщо не знайдено або is_active==false повернути 422 "Medication is not included in the program"
- Якщо продукт це сервіс (service) - перевірити, що сервіс є активним учасником програми
  - якщо не знайдено або is_active==false повернути 422 "Service is not included in the program"
- Якщо продукт це група сервісів (service_group) - перевірити, що група сервісів є активним учасником програми
  - якщо не знайдено або is_active==false повернути 422 "Service group is not included in the program"
Перeвірити налаштування медичної програми (prm.medical_programs table):
- якщо вказано параметр SPECIALITY_TYPES_ALLOWED:
  - Перевірити, що спеціальність автора відповідає SPECIALITY_TYPES_ALLOWED
    - в разі помилки - повернути 422 “Author’s specialty doesn't allow to create activity with medical program from request”
- якщо вказано параметр CONDITIONS_ICD10_AM_ALLOWED або/та CONDITIONS_ICPC2_ALLOWED:
  - Перевірити, що пов'язаний план лікування містить коди станів в полі addresses , який посилається на коди, вказані в CONDITIONS_ICD10_AM_ALLOWED або/та CONDITIONS_ICPC2_ALLOWED (залежно від довідника - eHealth/ICD10_AM/condition_codes або eHealth/ICPC2/condition_codes)
    - в разі помилки - повернути 422 “Care plan diagnosis with code #{condition_code} is not allowed for the medical program“
- Якщо вказано параметр PROVIDING_CONDITIONS_ALLOWED:
  - Перевірити, що пов'язаний план лікування має значення в полі terms_of_service та включений в список параметрів PROVIDING_CONDITIONS_ALLOWED
    - в разі помилки - повернути 422 “Care plan’s terms of service are not allowed for the medical program“

12. Мітка “не виконувати”

Перевірити значення в полі $.do_not_perform

Перевірити, що значення false
- якщо помилка - повернути код 422 ('not allowed in enum')

Логіка сервісу

Зберегти підписаний контент до файлового сховища
Зберегти дату до колекції care_plan_activities в БД у відповідності до Care plan data model_UA
Зберегти посилання з файлового сховища до $.signed_content_links field в колекції активностей плану лікування
Якщо план лікування має статус = new:
- Встановити = active
- Перевірити, якщо пацієнт має інший активний та/або новий План лікування з таким же кодо станів в полі addresses:
  - Якщо такий План лікування знайдено - встановити для таких Планів лікування статус TERMINATED
Створити задачу та повернути його id.