Патерни взаємодії учасників

(Розділ: Екосистема та Мережа)

1) Контекст і цілі

В екосистемі безліч акторів (оператори, провайдери, платіжні та KYC-сервіси, афіліати, регулятори, ком'юніті, розробники). «Патерни взаємодії» - це стійкі способи обміну цінністю і даними, які забезпечують сумісність, безпеку, економічну ефективність і масштабованість.

• Скоротити транзакційні витрати і час інтеграції.
• Підвищити надійність і спостережуваність міжвузлових потоків.
• Балансувати швидкість (latency) і узгодженість (consistency).
• Вшити комплаєнс і економічні стимули в протоколи взаємодії.

2) Таксономія учасників і ролі

Оператори/тенанти: кінцевий сервіс для користувачів, що володіють онбордингом та UX.
Провайдери/студії/контент-вузли: надають каталоги/API/івенти, SLA на видачу.
Платіжні/ризик-сервіси: авторизація, кліринг, чарджбеки, скоринг, ліміти.
Партнери/афіліати: приводять трафік, генерують вебхуки конверсій, отримують звіти.
Регулятори/аудит: вимагають журнали, звітність, локалізацію даних.
Ком'юніті/розробники: розширюють SDK, створюють додатки/боти/інтеграції.

3) Канали зв'язку і транспорт

Синхронні запити: REST/gRPC для RQ/RS, WebSockets/SSE для live-подій.
Асинхронні шини: Kafka/AMQP/потокові сервіси, Pub/Sub для подій домену.
Вебхуки: пуш-канал до зовнішнього партнера (обов'язково: підпис, таймаути, ретраї).
Файлові/батч-інтерфейси: NACHA/CSV/Parquet для звітності та backfill.
Edge/PoP: кешування, WAF, rate-limits, валідація підпису, редукція латентності.

4) Базові взаємодії (патерни рівня протоколу)

1. Request/Response (RQ/RS)

Використовувати для «рішень зараз»: авторизація платежу, перевірка лімітів, конфігурації.
Техніки: таймаути, circuit-breaker, retries з джиттером, ідемпотентні ключі.

2. Publish/Subscribe (Event-driven)

Для поширення фактів: «угода завершена», «баланс змінився», «подія гри».
Техніки: ключова партиціонізація (по user_id/tenant_id), дедуп по message-key, тривале зберігання журналу.

3. Command/Reply (Асинхронні команди)

Команда «зроби» з відкладеною відповіддю/кореляцією по correlation_id.
Техніки: outbox-патерн, гарантована публікація, компенсаційні команди.

4. Webhook Callback

Партнерський прийом повідомлень з повторною доставкою (at-least-once).
Техніки: підпис запиту, timestamp + анти-replay, ідемпотентність на приймачі.

5. Batch/Delta Sync

Нічні закриття, звітність, ре-синхронізація довідників.
Техніки: снапшоти + інкременти, контрольні суми, схеми версіонування.

5) Координація процесів: оркестрація vs хореографія

Хореографія (подієва): учасники реагують на доменні події без центрального координатора.

Плюси: слабка зв'язаність, масштабованість. Мінуси: складніше трасування/інциденти.
Оркестрація (саги): координатор управляє кроками і компенсаціями.

Плюси: прозорий контроль, передбачуваність. Мінуси: точка концентрації логіки.

Сага (компенсаційні транзакції): послідовність кроків з оборотними діями при збоях. Для фінансів/балансів - кращий суворий лідер і мінімізація компенсуючих операцій.

6) Консистентність і дані

Strong: платежі, ліміти, KYC-статуси (єдиний лідер, write-through, синхронні інваріанти).
Eventual/Timeline: телеметрія, каталоги, маркетингові події (асинхронна реплікація).
CRDT/версіонування: для рідкісних конфліктів в multi-master сценаріях.
Outbox/CDC: щоб подія «завжди» публікувалася разом із записом в БД.
Ідентифікатори: глобальні, сортовані (ULID/KSUID), з регіональними префіксами для діагностики.

7) Надійність і стійкість

Ідемпотентність: ключ на рівні запиту/повідомлення, дедуп на приймачі.
Ретраї: експоненціальний backoff з джиттером; обмеження за часом життя операції.
Таймаути і бюджет затримки: p95/p99 для критичних маршрутів.
Backpressure: обмеження паралелізму, черги, пріоритезація.
Degrade modes: часткова функціональність при відмовах (кеш, відкладені операції).
Chaos/GameDays: регулярні навчання з імітацією збоїв інтеграцій і каналів.

8) Безпека, довіра, комплаєнс

Автентифікація/авторизація: OAuth2/OIDC, mTLS для S2S, короткоживучі токени.
Підпис повідомлень/вебхуків: HMAC + timestamp + nonce.
Приватність/локалізація: PII/PCI в «зоні довіри» регіону, мінімізація поля даних в подіях (data minimization).
Аудит і незмінні логи: кореляція за trace_id, зберігання доказів доставки/читання.
Секрети та ключі: KMS per-region, ротація, policy-as-code.
Антифрод і ризик: скоринг на вході, ліміти по учаснику/каналу, поведінкові сигнали.

9) Економіка взаємодій і стимули

Контракти монетизації: RevShare/роялті, тарифи API (tiered), штрафи/кредит-ноти за SLA.
Fair use: квоти, rate-limits, пріоритезація за партнерськими рівнями.
Cost-aware routing: якщо кілька постачальників рівнозначні по SLA - вибирати більш економічний.
Прозора звітність: статуси доставок, дешборди споживання, self-service ліміти.

10) Спостережуваність і SLO

Трасування: наскрізний trace_id/span_id в RQ/RS і подіях.
Метрики: latency p50/p95/p99, error rate, лаг черг, частка кеш-хітів, egress.
Логи: структуровані, з tenant_id/partner_id/region/release.
Алертінг: SLO per-канал та інтеграцію; пріоритезація за бізнес-впливом (напр., платежі> телеметрія).

11) Типові шаблони контрактів

1. REST/gRPC контракт:

Версіонування SemVer, обов'язкові поля: idempotency-key, request-id, trace-context.
Відповіді: детерміновані коди помилок, retry-hints, link на статус асинхронної операції.

2. Подієвий контракт:

Поля: event_id, occurred_at, producer, subject_id, version, schema_ref.
Гарантії: як мінімум один раз, ключова партія, TTL/retention.

3. Webhook контракт:

Заголовки: signature, timestamp, nonce, delivery-id.
Поведінка: 2xx = підтвердження; ретраї з backoff до N годин, ідемпотентність на приймачі.

12) Патерни онбордингу партнерів

Пісочниця і тест-ключі, публічний каталог API/івентів, Postman/SDK, приклади.
Self-service портал: створення вебхуків, налаштування фільтрів подій, перегляд логів доставки.
Вбудовані гвард-рейли: ліміти по дефолту, попередження перед автодеградацією.
Сертифікація інтеграцій: чек-листи, автотести контрактів, «маркетплейс» статусу.

13) Ризики та анти-патерни

Синхронний «ланцюжок доміно»: довгі RPC по чужих системах → каскадні фейли.
Відсутність ідемпотентності: дубль платежу/події.
Схеми без версіонування: ламають споживачів при релізах.
Глобальний «майстер-правди» для всього домену: дорога/крихка міжрегіональна консистентність.
Непрозора економіка: партнери не бачать споживання → конфлікти і недовіру.

14) Метрики здоров'я взаємодій

Успішність доставок подій (%) і середній лаг.
p95/p99 затримки за критичними маршрутами (оплата, розрахунок результатів).
Помилки 4xx/5xx по інтеграції/каналу, MTTR інцидентів.
Частка ідемпотентно оброблених дублів, рівень кеш-хітів.
Вартість на 1k запитів/івентів і egress по партнерам.
Конверсія онбордингу партнерів: час «key-to-first-success».

15) Чек-лист впровадження

1. Класифікуйте взаємодії: синхронні vs подієві, критичність консистентності.
2. Визначте SLO і таймаути, увімкніть circuit-breakers і backoff.
3. Введіть ідемпотентність всюди (ключі, дедуп, replays).
4. Оформіть версії схем/контрактів і політику «expand → migrate → contract».
5. Увімкніть підписи і анти-replay для вебхуків, KMS per-region.
6. Побудуйте наскрізну спостережуваність і портали self-service.
7. Автоматизуйте сертифікацію партнерів і regression-тести контрактів.
8. Вбудуйте економіку: квоти, ліміти, звітність, cost-aware роутинг.
9. Регулярно проводьте GameDays для інтеграцій (деградація каналів, масові ретраї).
10. Переглядайте матрицю доменів раз на квартал: де посилити strong, де послабити.

16) FAQ

Що вибрати: оркестрацію чи хореографію? Для складних і критичних процесів - оркестрація; для широкого масштабування - хореографія з чіткими контрактами.
Як уникнути «дублів»? Ідемпотентні ключі + дедуп на приймачі + логіка «exactly-once-like» на споживачах.
Як прискорити онбординг партнерів? Пісочниця, готові SDK/приклад-скрипти, автоматичні перевірки вебхуків і статус-сторінки.
Як вбудувати комплаєнс? Мінімізуйте поля PII в подіях, зберігайте ключові операції в «зонах довіри», ведіть незмінний аудит.

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