Пайвандҳои ҳамгироии HUB ва API

1) Нақши HUB ва соҳаи масъулият

• протоколҳо ва форматҳоро муттаҳид кунед;
• эътимоднокиро таъмин кунед (бознишастагӣ, навбатҳо, сиёсати танаффус, танаффус);
• кафолати амният (MTLS, OAuth2, JWT, HMAC, IP-allowlist);
• мутамарказ кардани мушоҳида (гузоришҳо, ченакҳо, пайҳо);
• Содда кардани провайдери тағирёбанда (адаптерҳо + харитасозии майдон)
• барои гурӯҳҳои маҳсулот шартномаҳои устувор медиҳанд.

2) Принсипҳои тарроҳӣ

Шартномаҳои пайваста: DTO/рӯйдодҳои ягона, нақшаи қатъӣ ва версия.
Idempotency - калидҳои дархостӣ, такрорӣ, такрори бехатар.
Нобудшавии пешфарз: таваққуф, ақибмонӣ, сиёсати рахна.
Мушоҳида ҳамчун функсия: ҳама чиз чен карда мешавад ва пайгирӣ карда мешавад.
Ҷудосозии ҳамгироӣ аз домен: адаптерҳо мантиқи тиҷоратии ядро ​ ​-ро "намедонанд".
Арзиши ҳодиса: барои равандҳои асинхронӣ нашр/обуна шавед.
Версия: Шартномаҳои Semver ва деприция идора карда мешаванд.

3) Меъмории сатҳи баланд

Дарвозаи API: аутентификатсия, маҳдудиятҳои нархҳо, релизҳои канарӣ, WAF.
Оркестр/роутер: масир аз ҷониби провайдерҳо, афзалиятҳо, нокомӣ, масири интеллектуалӣ.

Адаптерҳои провайдер: REST/g

Автобуси EDA (Kafka/RabbitMQ/NATS): чорабиниҳо "пардохт сохта шудааст", "KYC гузашт", "ҷаласаи бозӣ оғоз ёфт".
Хадамоти шартнома/нақша: Феҳристи схема барои JSON/Avro/Protobuf.
Нигоҳдории давлатии ҳамгироӣ: калидҳои idempotence, таносуб, статус.
Мушоҳидаҳо: Prometheus/OT bel + панелҳо ва огоҳиҳо.
Dev: Portal: феҳристҳои ҳамгироӣ, OpEN API/Protobuf, намунаҳо, қуттиҳои қуттӣ.

4) Шартномаҳо ва схемаҳои маълумот

Схемаҳои қатъӣ (JSON Schema/Avro/Protobuf), санҷиши ҳатмии вуруд/баромад.
Феҳристи схема бо сиёсати қафо мувофиқ.
Конвенсияҳои хатогии тоза (формати рамзи/тафсилоти ягона).

5) Протоколҳои дастгирӣ

REST (OpEN API): бисёрҷониба, ҳуҷҷатгузорӣ осон.
GRPC: иҷрои баланд барои алоқаи дохилӣ.
Диаграммаи QL: вақте ки намунаҳои ҷамъшуда лозиманд.
Webhooks: рӯйдодҳо ба системаҳои беруна; Имзои HMAC, redelivery.
SSE/Websocket: ҷараёнҳои мустақим (ҳолати зинда, транзаксияҳо).

6) Амният ва дастрасӣ

MTLS байни хизматрасониҳои дохилӣ.
OAuth2/OIDC барои мизоҷони беруна, нишонаҳои кӯтоҳмуддат.
JWT барои Федератсияи хидматҳои шахсият; даъвои аудит.
Имзои HMAC барои webhooks/collbacks интиқодӣ.
IP-allowlist, WAF, RASP, филтрҳои зидди бот.
Идоракунии махфӣ (KMS/HSM), гардиши калидӣ, тақсимоти дониш.
DSS GDPR/PCI: кам кардани маълумоти шахсӣ ва кортӣ, токенизатсия.

7) Масир ва оркестр

Масир дар асоси сиёсат: аз рӯи гео, асъор, ченакҳои ноком, провайдери SLA.
Нокомӣ: пайдарпаии PSP/провайдер, таназзули автоматӣ.
Breaker Circuit: шохаҳои зуд таҳаммулпазир барои хатогиҳои зуд.
Bulkhead: ҷудокунӣ аз ҷониби провайдер/иҷорагир/ҳавзи ришта.
Saga/orchestration барои равандҳои дароз (бақайдгирӣ → KYC → амонат).

8) Idempotence ва маҳз як маротиба (тавре ки воқеӣ аст)

Idempotency-Key + ҳолати/вокуниш кэш.
Такрори ҳодисаҳои автобус (калиди коррелятсия).
Нигоҳдории "дархостҳои дидашуда" бо TTL.

http
POST /payments
Idempotency-Key: 3d8c1a4f-7f0e-4a2a-9e5a-2b8d3e7e2c11
Content-Type: application/json

json
{
"tenantId": "eu-casino-12",
"userId": "u-9812",
"currency": "EUR",
"amount": 50. 00,
"method": "card",
"metadata": {"orderId": "ORD-2025-1105-001"}
}

HUB натиҷаро сарфа мекунад ва ҳамон ҷавобро дар такрорӣ бармегардонад.

9) Навбат ва автобуси ҳодиса

Kafka/NATS/RabbitMQ барои қадамҳои асинхронӣ: Натиҷаҳои KYC, ҳолати пардохт, тавозуни провайдери бозӣ.
Мавзӯъҳо бо калидҳои узвият 'иҷорагир', 'корбар' ё 'провайдери Id' мебошанд.
Нигоҳдорӣ ва DLQ (мактуби мурда) бо барқароркунии автоматӣ пас аз ислоҳ.
Намунаи Outbox дар хидматҳои ядро ​ ​ барои нашри кафолатноки рӯйдодҳо.

10) Версия ва мутобиқат

Semver оид ба шартномаҳо: 'v1', 'v1. 1 ',' v2 '.
Мавҷудияти мувозии ду нусхаи хурд, ҷадвали возеҳи фарсудашавӣ.
Адаптерҳои муҳоҷират (харитасозии майдони муваққатӣ) барои гузариши ҳамвор.

11) Риоя ва эътимоднокӣ

Нишондиҳандаҳо: таъхири p50/p95/p99, сатҳи хатогӣ, гузариш, таносуби муваффақият аз ҷониби провайдерҳо, вақти тасдиқи рӯйдодҳо, "Вақт ба ҳамён".
Пайгирӣ (OT fel): ба охир расидани 'trace _ id '/' span _ id' аз занги API ба вокуниши провайдер.
Гузоришҳо: сохташуда, бо таносуби 'дархост _ ид', ниқоби PII/PAN.
SLO: масалан, 99. 9% сатҳи муваффақият <1. 5s барои роҳҳои интиқодӣ.
Огоҳиҳо: аз ҷониби буҷаи хатои SLO, афзоиши DLQ, аномалияҳои бозгашт/вақт.

12) Қуттиҳои қуттиҳо ва схемаҳои санҷишӣ

Қуттии қуттӣ барои ҳар як провайдер: ислоҳ, эмуляторҳои ҷавоб, таҳрири маълумот.
Санҷиши шартномавӣ (Pact/Buf) ва автогенератсияи SDK.
Профилҳои боркунӣ аз рӯи сенарияҳои "мусобиқаҳои баландтарин", "мавҷҳои пардохт".

13) Категорияҳои ҳамгироӣ (мисол барои IGaming)

Пардохтҳо/бозхонд: PSP, A2A/Open бонкӣ, дарвозаҳои крипто.
KYC/AML/Хавф: санҷиши шахсият/суроға, рӯйхати таҳримот, баҳодиҳии рафтор.
Провайдерҳои бозӣ/Агрегаторҳо: Оғози сессия, Токенҳои бозӣ, Бозгашти коллексияҳо.
Алоқа: почтаи электронӣ/SMS/push/messengers.
Таҳлил/BI: Ҷараёни чорабиниҳо ва агрегатҳо.
Қаллобӣ/Пуркунандаи барқ: марказҳои баҳс, огоҳиҳо.

14) Бисёрҳуҷрагӣ ва минтақавӣ

Ҷудокунии иҷорагир: калидҳои рамзгузорӣ, квотаҳо, маҳдудиятҳо, ҳавзҳои пайвастшавӣ.
Ҷуғрофия: масир ба наздиктарин RAP/минтақа бо назардошти қоидаҳои маҳаллӣ.
Усулҳои маҳаллии провайдер/пардохт: рӯйхат аз рӯи салоҳият ва сатҳи KYC.

15) Иҷро ва кэш

Кэши токен (PSP/KYC), посухҳои метамаълумоти провайдер (TTL).
Муттаҳидсозӣ ва истифодаи дубораи ҷаласаҳои TLS.
Async I/O барои RPS баланд; butching дар адаптерҳо.
Меъёри маҳдудиятҳои периметри муштарӣ ва провайдер.

16) Сенарияҳои ниҳоӣ (мисолҳо)

16. 1 Амонат (корт)

1. 'POST/пардохтҳо' → Оркестр → PSP # 1.
2. Вақтсанҷи 2s; pri '5xx/timeout' - retry s backoff; ҳангоми таназзул - PSP # 2.
3. Пардохти чорабинӣ. ваколатдори '→ тавозуни аслӣ → BI/зидди қаллобӣ.

16. 2 KYC

1. 'POST/kyc/пешниҳод' → адаптер провайдери KYC.
2. async: webhook 'kyc. натиҷа 'аз ҷониби HMAC имзо шудааст; дар ҳолати нокомӣ - расонидани такрорӣ (то N маротиба).
3. Ҳодиса 'kyc. тафтиш карда шудааст 'ба автобус нашр карда мешавад.

16. 3 Ҷаласаи бозӣ

1. 'POST/games/session' → адаптер агрегатор → аломати сессия.
2. Маҷмӯаҳои натиҷаҳо/гаравҳо → HUB имзо ва аблаҳиро тасдиқ мекунад.
3. Бозии ҳодиса. давр мезананд. ҳалшуда 'ба ҳисоби пардохтҳо ва ҳисоботдиҳӣ дохил мешавад.

17) Хатогиҳо ва формати посухи ягона

Коды: 'Интегратсия _ TIMEOUT', 'PROVIDER _ UNAVAILABLE', 'CONTRACT _ VALIDATION _ FAIL', 'SECURITY _ SIGNATURE _ INVALID'.

json
{
"code": "PROVIDER_UNAVAILABLE",
"message": "Primary PSP degraded, switched to fallback",
"correlationId": "9f8e1b6a-1c2d-4b4e-9d31-91c6bc31c1d4",
"provider": "psp-1",
"hint": "Retry allowed; idempotency key required"
}

18) Вебхукҳои бехатар: Имзо ва такрор

X-Signature: sha256=hex(hmac_sha256(secret, body + timestamp))
X-Timestamp: 1730812800

Вақтро санҷед ва танҳо огоҳиҳои навро қабул кунед. Такрор мекунад - экспоненталӣ ба N, пас дар DLQ.

19) Идоракунии тағирот ва релизҳо

Адаптерҳои канарӣ (1-5% трафик), парчамҳои ҳар як иҷорагирро доранд.
Варақаҳои ба қафо мувофиқ: аввал адаптерҳо, баъд шартномаҳо.
CAB/CRQ барои провайдерҳои беруна, ҷойгиркунии тирезаҳо SLA пайваста мебошанд.

20) SLA/SLO/OLA

Провайдери SLA: вақти корӣ ≥ 99. 9%, webhooks ack ≤ 3c, ба охир расидани пардохт ≤ 30c (p95).
SLO HUB: p95 <1. 5c ба нуқтаҳои ниҳоӣ, дараҷаи хатогӣ <0. 3%.
OLA дар дохили: маҳдудиятҳои навбат, баргардонидани буҷа, ҳадди аксар DLQ.

21) Каталоги ҳамгироӣ ва Dev

Саҳифаҳои провайдер: статусҳо, версияҳои адаптер, талаботҳои саҳроӣ, рӯйхатҳои назоратӣ.

Автогении SDK (Open

Тугмаи "Санҷиш дар Sandbox" ва хатҳои ҳамгироии CI.

22) Бехатарӣ ва риояи

Нашри PII дар гузоришҳо, рамзгузории майдонҳои истироҳатӣ, майдонҳои PAN танҳо дар шакли токенизатсияшуда.
RBAC/ABAC барои панелҳои оператор, ҳадди аққал принсипи имтиёз.
Феҳристҳои ризоият (GDPR), ҳуқуқи нест кардан/порт.
Фурӯшанда-хатар ва DPIA барои ҳамгироии нав.

23) Нақшаи амалисозӣ (миқёси MVP →)

MVP (0-2 моҳ): Дарвоза, 1-2 PSP, 1 KYC, 1 агрегатори бозӣ, ченакҳои асосӣ, idempotency, DLQ.

Марҳилаи 2 (3-4 моҳ): Автобуси EDA, Dev

Марҳилаи 3 (5-6 моҳ): кластерҳо бо гео-роллер, масири интеллектуалӣ тавассути SLA, SLO/огоҳиҳои васеъ, автоген SDK, канарейка.

24) Рӯйхати санҷиши пеш аз фурӯш

Шартномаҳо дар Феҳрист, санҷишҳои мутобиқат гузаштанд.
Сиёсати вақт/бозсозӣ/вайронкунӣ бо санҷишҳои e2e муқаррар ва фаро гирифта шудаанд.
IdempotencY Key ба POST/PUT интиқодӣ дохил карда шудааст.
Имзоҳои Webhooks тасдиқ карда мешаванд, бозсозӣ танзим карда мешаванд, DLQ назорат карда мешавад.
Нишондиҳандаҳои p95/p99 ва хатогӣ ба SLO мувофиқанд, огоҳиҳо пайваст карда мешаванд.
Асрҳо дар KMS, ротатсия санҷида шуданд; IP-allowlist/WAF фаъол аст.
Китобҳои Runbook/дафтарҳои бозикунии ҳодисаҳо, ба нақша гирифта шудаанд.

Dev

Хулоса

Интегратсияи HUB як "сипар ва тарҷумон" -и саноатӣ байни аслӣ ва ҷаҳони хидматҳои беруна мебошад. Қувваи он дар шартномаҳои қатъӣ, аблаҳӣ, автобуси ҳодиса, ҳукми назоратшаванда ва мушоҳидаҳо ҷойгир аст. Ин меъморӣ провайдерро дар киштӣ суръат мебахшад, хатарро коҳиш медиҳад, SLO-ҳои пешгӯишавандаро таъмин мекунад ва миқёсро барои қуллаҳои ҳаракат ва ворид шудан ба бозорҳои нав содда мекунад.