Versions Compared

Old Version 57

changes.mady.by.user valeriia denysenko

Saved on

compared with

New Version 58

changes.mady.by.user valeriia denysenko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Інтеграція тригериться тільки при створенні award в модель даних beneficiariesGeneralInfo
  2. Запит асинхронний
  3. Дані записуються тільки якщо валідні
  4. Запис — атомарний (все або нічого):
    1. або записуються всі КБВ (якщо хоча б один КБД не валідний  - не записується жоден)
    2. або записується один fallback - обʼєкт
    3. Основний сценарій:
    4. Створюється award
    5. Перевіряються умови
    6. Виконується аутентифікація в ЄДР
    7. Виконується запит до ЄДР
    8. Отримується відповідь
    9. Відбувається валідація
    10. Якщо валідно:
      • запис у award.beneficiaries[]
      • оновлення:
        • award.dateModified
        • procedure.dateModified
        • systemDateModified
  5. Retry (до 3 разів) тільки для: 500, 502
    1. retry з exponential backoff
    2. після 3 спроб → fallback де beneficiaries.fallback.systemReason = "Не вдалось отримати інформацію з сервісу" beneficiaries.status = error
  6. API_TOKEN зберігається:
    - у захищеному конфігураційному середовищі
    - не логуються
    - не передається у відкритому вигляді
  7. Порожній результат (200 без даних) НЕ є помилкою API, але вимагає fallback
  8. Асинхронність має пріоритет над статусом award — відповідь завжди обробляється
  9. Timeout прирівнюється до технічної помилки (500/502)

...

  1. Обробка 401

    1. означає невалідний або відкликаний токен

    2. retry НЕ виконується

    3. надсилається Slack alert

    4. статус інтеграції → auth_error

  2. Обробка 404
    1. Отримано 404
    2. запис в поле beneficiaries.fallback.systemReason = "Суб'єкт не знайдено в ЄДР"зміна  beneficiaries.status з processing на error

Slack повідомлення

Відправляються для:

...

Назва

Отримання та запис КБВ з ЄДР в award
Актори
  • ЦБД (primary)
  • ЄДР API (external)
Передумови
  • Процедура входить в перелік дозволених (LLE, LLD, …, SUD)
  • Учасник є юридичною особою
    • award.buyers.identifier.scheme = UA-EDR
  • award.status ∈ {pending_waiting, pending_admission, pending}
  • інтеграція має статус active
Основний сценарій

Дані невалідні → UC2

Помилка API → UC3/UC11-15

  1. Учасник подає заявку
  2. Майданчик активує заявку
  3. Заявка переходить у кваліфікацію
  4. ЦБД створює award
  5. ЦБД перевіряє умови запуску інтеграції
  6. ЦБД змінює beneficiaries.status на processing
  7. ЦБД формує запит до ЄДР із заголовками:
    1. Authorization: Token {API_TOKEN}
    2. Accept: application/json
  8. ЦБД відправляє запит до ЄДР з code = ЄДРПОУ
  9. ЄДР повертає дані КБВ (може бути список)
  10. ЦБД валідовує відповідь
  11. Дані відповідають моделі beneficiariesGeneralInfo
  12. ЦБД записує дані в award.beneficiaries
  13. ЦБД змінює beneficiaries.status з processing на complete
  14. Оновлює:
  • award.dateModified
  • procedure.dateModified
  • systemDateModified
Результат

award містить список валідних КБВ (може бути декілька)

...

Назва

Відмова у записі КБВ
Актори
  • ЦБД (primary)
  • ЄДР API (external)
Передумови

Отримано відповідь ЄДР

Основний сценарій
  1. ЦБД отримує дані
  2. Перевіряє дані на відповідність моделі даних
  3. Якщо дані:
    • неповні / некоректні / не мапляться
  4. ЦБД НЕ записує дані
  5. ЦБД змінює beneficiaries.status з processing на error
Альтернативний сценарійВсі КБВ валідні → UC1
Результат

award без змін

...

Назва

Повторна спроба отримання даних
Актори
  • ЦБД (primary)
  • ЄДР API (external)
Передумови

Отримано HTTP код:
500, 502

Основний сценарій
  1. ЦБД відправляє запит
  2. Отримує 500 або 502
  3. Виконує retry
  4. Повторює до 3 разів
  5. Якщо успіх → UC1
Альтернативний сценарій

Всі retry невдалі → UC4 beneficiaries.status змінюється з processing на error

Результат
  • або дані записані
  • 500/502: Slack alert не відправляється на кожну помилку, але відправляється після 3 невдалих retry.

...

1

GivenОтримано 500/502

When

Виконується retry

Then

Система повторює запит до 3 разів

2

GivenВсі retry невдалі

Then

Записується повідомлення в поле beneficiaries.fallback.systemReason:
"Не вдалось отримати інформацію з сервісу"status змінюється з processing на error


...


USE CASE 4 —

...

Назва

...

ЦБД (primary)

...

retry завершився невдачею

...

  1. Формується fallback-об’єкт
  2. Записується в beneficiaries.fallback.systemReason

...

award містить fallback

Acceptance Criteria

...

1

...

Then

...

AND

...

Відправляється повідомлення в Slack

...

Інтеграція не запускається

Назва

Неініціювання запиту до ЄДР
Актори

ЦБД (primary)

Передумови

Будь-яка з умов НЕ виконується:

  • процедура не з визначеного переліку
  • відсутній x_ultimateBeneficiaryInfo
  • не юрособа
    • award.buyers.identifier.scheme ≠ UA-EDR
  • статус award не підходить
Основний сценарій
  1. Створюється award
  2. ЦБД перевіряє умови
  3. Інтеграція НЕ запускається
Результат

Жодних запитів до ЄДР

Acceptance Criteria

1

GivenУмови не виконані

When

Створюється award

Then

запит до ЄДР не виконується


...

USE CASE

...

5 — Обробка множинних КБВ

Назва

Запис кількох бенефіціарів
Актори
  • ЦБД (primary)
  • ЄДР API (external)
Передумови
  • Виконується UC1 
  • ЄДР повертає список КБВ
Основний сценарій
  1. ЦБД мапить кожен запис (кожен КБВ проходить однаковий mapping)
  2. Формує list of objects
  3. Записує в award.beneficiaries[]
  4. усі КБВ з відповіді ЄДР зберігаються, а не тільки перший;
  5. порядок не змінюється
Альтернативний сценарійхоча б один невалідний КБВ → UC2
Результат

Збережено всі КБВ

Acceptance Criteria

1

GivenЄДР повертає кілька КБВ

When

Відбувається запис

Then

Всі КБВ зберігаються в масиві

...

ЯкЦБД Prozorro.Sale
я хочузупиняти направлення запитів до ЄДР після першого отримання помилки 402 або 429
щобне створювати зайве навантаження на сервіс, не витрачати ліміти та уникати повторних неуспішних запитів до моменту відновлення доступу/поповнення коштів. 
додатковоПісля внесення коштів або відновлення ліміту система має відновити направлення запитів до ЄДР.

USE CASE

...

6 — Зупинка запитів після отримання 402

Назва

Автоматичне призупинення інтеграції з ЄДР при помилці 402 Payment Required
Актори
  • ЦБД
  • ЄДР
  • Адміністратор/відповідальна команда
  • Slack канал
Передумови
  • Інтеграція з ЄДР активна
  • ЄДР повертає HTTP 402
Основний сценарій
  1. ЦБД направляє запит до ЄДР.
  2. ЄДР повертає відповідь 402 Payment Required.
  3. ЦБД фіксує помилку
  4. ЦБД змінює внутрішній статус інтеграції з ЄДР на → payment_required
  5. ЦБД припиняє направлення нових запитів до ЄДР.
  6. ЦБД відправляє повідомлення в Slack канал.
  7. Для нових awards, які підпадають під умови інтеграції, запит до ЄДР не виконується.
Результат
  • Інтеграція зупинена
  • Нові запити до ЄДР не направляються.
  • Команда отримала повідомлення про необхідність внесення коштів.
  • Дані КБВ для нових awards тимчасово не збагачуються.
Acceptance Criteria

1

GivenЦБД отримала від ЄДР відповідь 402

When

Система обробляє відповідь

Then

Інтеграція з ЄДР переходить у статус призупинення.

2


Given

Інтеграція має статус призупинення через 402

When

Створюється новий award, який відповідає умовам інтеграції

Then

ЦБД не направляє запит до ЄДР.

3

GivenОтримано 402
WhenСистема фіксує помилку

Then

Повідомлення надсилається в Slack канал.


...

USE CASE

...

7 — Зупинка запитів після отримання 429

Назва

Автоматичне призупинення інтеграції з ЄДР при помилці 429 Many Requests
Актори
  • ЦБД
  • ЄДР
  • Slack канал
  • Адміністратор/відповідальна команда
Передумови
  • Інтеграція з ЄДР активна
  • ЄДР повертає HTTP 429 (означає, що вичерпано обмеження запитів до ресурсу)
Основний сценарій
  1. ЦБД направляє запит до ЄДР.
  2. ЄДР повертає відповідь 429 Many Requests.
  3. ЦБД фіксує помилку.
  4. ЦБД змінює внутрішній статус інтеграції з ЄДР на → rate_limit_exceeded
  5. ЦБД призупиняє направлення нових запитів до ЄДР.
  6. ЦБД відправляє повідомлення в Slack канал. (Перевищено ліміт запитів до ЄДР)
  7. Нові awards, які підпадають під інтеграцію, не ініціюють запит до ЄДР.
Результат
  • Інтеграція тимчасово зупинена.
  • Нові запити до ЄДР не виконуються.
  • Команда повідомлена про перевищення ліміту.
  • Дані КБВ для нових awards тимчасово не збагачуються.
Acceptance Criteria

1

GivenЦБД отримала відповідь 429

When

Система обробляє відповідь

Then

Направлення нових запитів до ЄДР зупиняється.

2


Given

Інтеграція призупинена через 429

When

Створюється новий award

Then

ЦБД не направляє запит до ЄДР

3

GivenОтримано 429
WhenСистема обробляє помилку

Then

Повідомлення надсилається в Slack канал.


...

USE CASE

...

8 — Відновлення запитів після внесення коштів

Назва

Ручне або автоматичне відновлення інтеграції з ЄДР після внесення коштів
Актори
  • Адміністратор/відповідальна команда
  • ЦБД
  • ЄДР
Передумови
  • Інтеграція з ЄДР була призупинена через 402
  • Статус інтеграці = payment_required
  • Кошти внесено / доступ до сервісу відновлено
Основний сценарій
  1. Відповідальна команда вносить кошти.
  2. Адміністратор ініціює відновлення інтеграції.
  3. ЦБД змінює статус інтеграції з payment_required на active
  4. ЦБД відновлює направлення запитів до ЄДР.
  5. При створенні наступного award ЦБД знову виконує стандартну логіку запиту до ЄДР.
  6. Якщо ЄДР повертає 200, дані КБВ обробляються та записуються в award.
Результат
  • Інтеграція з ЄДР активна.
  • Запити до ЄДР відновлені.
  • Система продовжує автоматичне збагачення awards даними КБВ.
Acceptance Criteria

1

GivenІнтеграція призупинена через 402
AndКошти внесено

When

Адміністратор активує інтеграцію

Then

Статус інтеграції змінюється на active.

2


Given

Інтеграція активна після відновлення

When

Створюється новий award

Then

ЦБД направляє запит до ЄДР

3

GivenЄДР після відновлення повертає 200
WhenЦБД отримує валідні дані

Then

Дані записуються в award.beneficiaries


...

USE CASE

...

9 — Відновлення після вичерпання ліміту запитів

Назва

Відновлення інтеграції після помилки 429
Актори
  • Адміністратор/відповідальна команда
  • ЦБД
  • ЄДР
Передумови
  • Інтеграція була призупинена через 429
  • Статус інтеграці = rate_limit_exceeded
  • Ліміт запитів поновлено або відповідальна команда підтвердила можливість повторного використання сервісу
Основний сценарій
  1. Відповідальна команда перевіряє, що ліміт запитів відновлено.
  2. Адміністратор активує інтеграцію.
  3. ЦБД змінює статус інтеграції з rate_limit_exceeded на active
  4. Наступні awards знову запускають запит до ЄДР.
  5. Якщо ЄДР повертає успішну відповідь — дані обробляються за стандартним сценарієм.
Результат
  • Інтеграція з ЄДР активна.
  • Запити до ЄДР відновлені.
  • Система продовжує автоматичне збагачення awards даними КБВ.
Acceptance Criteria

1

GivenІнтеграція призупинена через 429

When

Ліміт запитів відновлено

And

Адміністратор активує інтеграцію

Then

ЦБД знову направляє запити до ЄДР

2


Given

Інтеграція активована після 429

When

Створюється award

Then

Запит до ЄДР виконується

...

ЯкЦБД Prozorro.Sale
я хочукоректно обробляти всі типи помилок від ЄДР (400, 401, 403, 404, 406, 500, 502)
щобзабезпечити стабільну роботу системи, не втрачати дані та мати можливість відновлення інтеграції

USE CASE

...

10 — Обробка 401 Unauthorized при невалідному API Token

Назва

Автоматичне оновлення токена при помилці 401
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • Запит до ЄДР виконано
  • Отримано 401 Unauthorized
Основний сценарій
  1. ЦБД отримує 401
  2. Визначає, що токен невалідний
  3. НЕ виконує retry
  4. Надсилає Slack alert
  5. Статус інтеграції → auth_error
Результат
  • Інтеграція відновлюється без втручання людини
  • або помилка auth
Acceptance Criteria

1

GivenОтримано 401

When

Система обробляє відповідь

Then

Retry не виконується

2


Given

Отримано 401

When

Система фіксує помилку

Then

Статус інтеграції змінюється на auth_error

3

GivenОтримано 401

When

Система фіксує помилку

Then

Повідомлення надсилається в Slack канал

4



Given

Статус інтеграції = auth_error

When

Створюється новий award, який відповідає умовам інтеграції

Then

Запит до ЄДР не виконується до заміни/актуалізації API Token


...

USE CASE

...

11 — Помилка 400 (Bad Request)

Назва

Обробка некоректного запиту до ЄДР
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • Запит до ЄДР виконано
  • Отримано 400
Основний сценарій
  1. ЦБД отримує 400
  2. Аналізує помилку
  3. Визначає:
    • помилка у формуванні запиту
  4. НЕ виконує retry
  5. Логує помилку
  6. Надсилає повідомлення в Slack
  7. Переводить інтеграцію в статус invalid_request
Рішення

Виправлення формату запиту (dev fix)

Результат
  • запит не повторюється
  • потрібне втручання розробника
Acceptance Criteria

1


GivenОтримано 400

When

Обробляється помилка

Then

Retry не виконується

And

Slack отримує повідомлення


...

USE CASE

...

12 — Помилка 403 (Forbidden)

Назва

Обробка відсутності прав доступу
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • Запит до ЄДР виконано
  • Отримано 403
    • змінились права доступу до API
    • акаунт не має доступу
Основний сценарій
  1. ЦБД отримує 403
  2. Аналізує помилку
  3. НЕ виконує retry
  4. Відправляє повідомлення в Slack
  5. Переводить інтеграцію в статус access_denied
Рішення
  • перевірка прав доступу
  • перевидача ключів / ролей
Результат

Інтеграція не працює до виправлення

Acceptance Criteria

1


GivenОтримано 403

Then

Retry не виконується

And

Slack отримує повідомлення


...

USE CASE

...

13 — Помилка 404 (Not Found)

Назва

Обробка відсутності суб’єкта в ЄДР
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • Запит до ЄДР виконано
  • Отримано 404
Основний сценарій
  1. ЦБД отримує 404
  2. Аналізує помилку
  3. Визначає, що суб'єкт відсутній
  4. НЕ виконує retry
Записує
  1. Змінює beneficiaries
тільки fallback в поле beneficiaries.fallback.systemReason:
  • "Суб'єкт не знайдено в ЄДР"
  1. .status з processing на error
Результат
  • award без КБВ
  • award містить beneficiaries.
fallback.systemReason
  • status = error
Acceptance Criteria

1


GivenОтримано 404

Then

Retry не виконується

And

Записує beneficiaries тільки поле beneficiaries.fallback.systemReason:

"Суб'єкт не знайдено в ЄДР"

Змінює beneficiaries status з processing на error 


...

USE CASE

...

14 — Помилка 406 (Not Acceptable)

Назва

Обробка помилки формату даних
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • Запит до ЄДР виконано
  • Отримано 406
Основний сценарій
  1. ЦБД отримує 406
  2. ЦБД змінює beneficiaries.status з processing на error
  3. Аналізує помилку
  4. НЕ виконує retry
  5. Відправляє alert в Slack
  6. Переводить інтеграцію в статус invalid_request
Рішення
  • перевірка контракту API
  • виправлення формату
Результат
  • інтеграція не виконується для цього запиту
Acceptance Criteria

1


GivenОтримано 406

Then

Retry не виконується

And

Slack отримує повідомлення

...

ЯкЦБД Prozorro.Sale
я хочуоректно обробляти випадки, коли ЄДР не повертає дані або повертає пустий результат
щобзабезпечити прозору причину відсутності КБВ у системі

USE CASE

...

15 — Порожній результат (200, але без даних)

Назва

Суб’єкт не знайдений за кодом ЄДРПОУ (порожній результат)

Актори
  • ЦБД
  • ЄДР
Передумови
  • Інтеграція з ЄДР активна
  • Запит до ЄДР виконано
  • ЄДР повертає HTTP 200
  • Список beneficiaries порожній
Основний сценарій
  1. ЦБД отримує відповідь 200
  2. Перевіряє тіло відповіді
  3. Визначає, що список результатів порожній
  4. Не виконує заповнення КБВ
  5. ЦБД змінює beneficiaries.status з processing на error
  6. Записує fallback з причиною
Результат
  • Інтеграція зупинена
  • Нові запити до ЄДР не направляються.
  • Команда отримала повідомлення про необхідність внесення коштів.
  • Дані КБВ для нових awards тимчасово не збагачуються.
Acceptance Criteria

1

GivenЦБД отримала від ЄДР відповідь 200

And

Список результатів порожній

When

Система обробляє відповідь

Then

КБВ не заповнюються

2


Given

Пустий результат

Then

записується systemReason = "Суб’єкт не знайдений за кодом ЄДРПОУ"

Змінює в beneficiaries status з processing на error


...

User Story 5. Узгодженість даних при зміні статусу award

ЯкЦБД Prozorro.Sale
я хочузавершувати обробку запиту до ЄДР навіть якщо статус award змінився
щобуникнути втрати даних через асинхронність

USE CASE

...

16 — Award змінив статус під час запиту

Назва

Обробка відповіді ЄДР після зміни статусу award

Актори
  • ЦБД
  • ЄДР
Передумови
  • Запит до ЄДР вже відправлений
  • Award змінив статус (наприклад:
    • дискваліфіковано
    • cancelled
    • unsuccessful)
Основний сценарій
  1. ЦБД відправляє запит
  2. Award змінює статус
  3. ЦБД отримує відповідь від ЄДР
  4. НЕ перевіряє актуальний статус award
  5. Обробляє відповідь за стандартною логікою:
    • або запис КБВ
    • або fallback
Результат
  • Дані КБВ (або fallback) збережені незалежно від статусу award
Acceptance Criteria

1


GivenЗапит до ЄДР відправлено

And

Award змінив статус

When

Отримано відповідь

Then

Відповідь обробляється

And

Дані записуються незалежно від поточного статусу award

...

ЯкЦБД Prozorro.Sale
я хочукоректно обробляти timeout від ЄДР
щоб

забезпечити стабільність інтеграції

USE CASE

...

17 — Timeout від ЄДР

Назва

Обробка перевищення часу очікування відповіді

Актори
  • ЦБД
  • ЄДР
Передумови
  • Запит відправлено
  • Відповідь не отримано в межах timeout (5–10 сек)
Основний сценарій
  1. ЦБД очікує відповідь
  2. Timeout перевищено
  3. ЦБД фіксує помилку
  4. Виконує retry (як для 500/502)
  5. До 3 спроб
Альтернативний сценарій
  • retry успішний → UC1
  • retry неуспішний → fallback→ ЦБД змінює beneficiaries.status з processing на error
Результат
  • або отримані даніабо fallback
  • beneficiaries.status = error
Acceptance Criteria

1


GivenПеревищено timeout

When

Система обробляє запит

Then

Виконується retry

2


GivenRetry неуспішний

Then

Записується fallback

...

ЯкЦБД Prozorro.Sale
я хочуНе обробляти старі awards після відновлення інтеграції
щоб

Уникнути неочікуваного навантаження та складної логіки в межах POC

USE CASE

...

18 — Відсутність ретро-обробки

Назва

Обробка перевищення часу очікування відповіді

Актори
  • ЦБД
  • Адміністратор
Передумови
  • Інтеграція була в статусі:
    • payment_required або rate_limit_exceeded або suspended_manual
  • Існують awards без КБВ
  • Інтеграцію переведено в active
Основний сценарій
  1. Інтеграція відновлюється
  2. Система НЕ виконує повторну обробку існуючих awards
  3. Нові awards обробляються стандартно
Альтернативний сценарій
  • Адміністратор запускає ручну обробку → UC21/UC22
Результат
  • Старі awards залишаються без змін
Acceptance Criteria

1


GivenІнтеграція була зупинена

And

Існують awards без КБВ

When

Інтеграція відновлена

Then

Обробляються тільки нові awards

2


GivenІснують старі awards

Then

Вони НЕ обробляються автоматично

...

ЯкАдміністратор ЦБД Prozorro.Sale
я хочуМати можливість вручну керувати інтеграцією
щоб

Контролювати її роботу незалежно від автоматичних сценаріїв

USE CASE

...

19 — Ручна зупинка інтеграції

Назва

Зупинка інтеграції через Адміністративну панель

Актори
  • ЦБД
  • Адміністратор
Передумови
  • Статус інтеграції = active
Основний сценарій
  1. Адміністратор відкриває адмінку
  2. Натискає “Зупинити інтеграцію”
  3. Система встановлює статус → suspended
  4. Нові запити до ЄДР не виконуються
Результат
  • Інтеграція зупинена вручну
Acceptance Criteria

1



GivenІнтеграція активна

When

Адміністратор її зупиняє

Then

Статус = suspended

And

Запити до ЄДР не виконуються


...

USE CASE

...

20 — Ручне відновлення інтеграції

Назва

Відновлення інтеграції через Адміністративну панель

Актори
  • ЦБД
  • Адміністратор
Передумови

  • Статус:

    • suspended
    • або payment_required
    • або rate_limit_exceeded
Основний сценарій
  1. Адміністратор натискає “Відновити”
  2. Система змінює статус → active
  3. Запити до ЄДР дозволяються
Результат
  • Інтеграція відновлена
Acceptance Criteria

1



GivenІнтеграція зупинена

When

Адміністратор її відновлює

Then

Статус = active

...

Назва

Зупинка інтеграції через Адміністративну панель

Актори
  • ЦБД
  • Адміністратор
Передумови
  • Award існує
  • Користувач має права адміністратора
Основний сценарій
  1. Адміністратор обирає award (id)
  2. Натискає “Запустити інтеграцію”
  3. Система:
    • ігнорує тригер “тільки при створенні award”
    • формує запит до ЄДР
  4. Обробляє відповідь стандартно
  5. Оновлює beneficiaries
Альтернативний сценарій

Інтеграція глобально зупинена → ручний запуск дозволений

Результат

beneficiaries оновлено

Acceptance Criteria

1



GivenОбрано award

When

Адміністратор запускає інтеграцію

Then

Виконується запит до ЄДР

And

beneficiaries перезаписуються

...

Назва

Зупинка інтеграції через Адміністративну панель

Актори
  • ЦБД
  • Адміністратор
Передумови
  • Обрано список існуючих awards
  • Користувач має права адміністратора
Основний сценарій
  1. Адміністратор обирає кілька awards (id)
  2. Натискає “Запустити для вибраних”
  3. Система:
    • формує список задач
    • відправляє їх у чергу
  4. Кожен award обробляється окремо
Альтернативний сценарій

перевищено ліміт → операція блокується

Результат

всі awards оброблені асинхронно

Acceptance Criteria

1



GivenОбрано список awards

When

Запускається обробка

Then

Кожен award обробляється незалежно

2


GivenМасовий запуск
ThenОбробка виконується через чергу

...