Адаптерҳои провайдер

Адаптер провайдер - қабати алоҳидаи интегратсионӣ (қабати зиддикоррупсионӣ, ACL), ки шартномаи таҳвилгари берунаро (провайдери бозӣ, дарвозаи пардохт, KYC/AML, баҳодиҳии хавфҳо, огоҳиномаҳо ва ғайра) ба забони домени дохилӣ ва баръакс тарҷума мекунад. Он доменро аз API-ҳои ноустувор, аномалияҳои шабака, таҳаввулоти схема ва сиёсати амният муҳофизат мекунад.

1. Декуплинг: Ягон сарбории берунии "хом" ба ядро ​ ​ дучор намешавад.

2. Эътимоднокӣ: идоракунии камбудиҳо (танаффус, такрорӣ, DLQ, вайронкунандаи барқ).

3. Мутобиқат: номутобиқатӣ, тартиби асосӣ, паёмнависии транзаксионӣ.

4. Амалиёт: ченакҳо, пайгирӣ, маҳдудиятҳо, ҷудокунии интиқол ва истиқомат.

1) Минтақаи адаптер масъулият

Шартномаҳо: тавсифи схемаҳои беруна/нуқтаҳои ниҳоӣ; харитасозӣ → фармонҳо/рӯйдодҳои дохилӣ.
Нақлиёт: REST/GRPC/Web-Socket/SQS/Kafka/SFTP; ҳавзи пайвастшавӣ, backpressure.
Амният: mTLS, OAuth2, HMAC, калидҳо/шаҳодатномаҳо барои як иҷорагир/минтақа, гардиши асрори.
Эътимоднокӣ: танаффус, бозсозӣ бо ҷиттер, рахи барқ, такроршавӣ.
Idempotency: 'Idempotency-Key '/' request _ id', нигоҳ доштани посухҳо/статусҳо.
Мушоҳида: ченакҳои SLO, гузоришҳои сохторӣ, пайгирӣ.
Версия: дастгирии версияҳои сершумори схемаҳо/нуқтаҳои ниҳоӣ.
Амалиётҳо: ficheflags, релизҳои канарӣ, қуттиҳои қуттиҳо, сертификатсия.

2) Дар ҷойҳои мувофиқ (заминаҳои намуна)

Бозӣ/RGS: даври оғоз/пӯшида, гарав/бурд, нишонаҳои сессия, ҳолати провайдер.
Пардохтҳо/PSP: пасандозҳо/бозпас гирифтан, ҳолати вебҳукҳо, пардохт, 3-D Secure.
KYC/AML: санҷиш, санксия/санҷиши POP, мониторинги транзаксия.
Хавф/қаллобӣ: баҳодиҳӣ, триггерҳо, бастани тавсияҳо.
Comms: почтаи электронӣ/SMS/push, маҳдудиятҳои почта, қолабҳо.

Ҳар як намуд мошини давлатии воқеаи худро дорад ва SLA - адаптер вазифадор аст онро ба эътидол орад.

3) Шартнома ва харитасозӣ (дохилӣ ↔ беруна)

• Мо дар дохили адаптер забони нашршударо ворид мекунем ва ҳеҷ гоҳ майдонҳои провайдерро кашида намегирем.
• Ҳама паёмҳо 'иҷорагир _ ид', 'минтақа', 'провайдер _ ид', 'operation _ id', 'version _ ts' доранд.
• Мо якчанд версияҳои схемаҳои берунаро тавассути харитаҳо дастгирӣ мекунем.

yaml mapping:
provider: "AcmeRGS"
version: "v3"
inbound:
SpinResultV3 -> Round. Resulted
BonusWinV3  -> Bonus. Wagered outbound:
StartRound  -> POST /v3/sessions/{id}/start
Stake    -> POST /v3/spins compat:
accepts: ["v2","v3"]
emits:  ["v3"]

4) Idempotence ва фармоиш

Дархости de-dup: 'Калиди номутаносиб: <operation_id>' дар дархостҳо; ҳикоя '(op_id → ҳолати ниҳоӣ/вокуниш)' бо TTL.
Webhook de-dup: ҷадвали 'паёмдони (провайдер, event_id)' ҳамчун PK.
Фармоиш аз рӯи калид: зангҳо ва коркарди сериалро тавассути 'agregate _ id' (масалан, 'round _ id' ё 'psp _ tx _ id').
Outbox/Inboxing: паёмнависии транзаксионӣ дар ҳарду канори қубур.

5) Эътимоднокӣ: танаффус, ақибнишинӣ, рахи барқ

Вақтсанҷҳо: тарафи муштарии кӯтоҳ (p95-нигаронидашуда), алоҳида барои пайвастшавӣ/хондан.
Бозёфтҳо: танҳо бознишаста (5xx/timeout/429), бозгашти экспоненсиалӣ + jitter пурра, маҳдудияти кӯшиш ва мӯҳлати умумӣ.
Қатъи гардиш: ҳангоми зиёд шудани хатогиҳо/таъхир; таназзули зебо (масалан, хомӯш кардани хусусиятҳои дуввуми RGS, муқаррар кардани "интизории натиҷа").
DLQ: паёмҳои "заҳролуд" бо мета-иттилооти бой, азнавсозии бехатар.

yaml reliability:
timeout_ms:
connect: 1000 read:  1500 retry:
max_attempts: 6 initial_backoff_ms: 200 max_backoff_ms: 8000 jitter: full retry_on: [TIMEOUT, 5xx, 429]
circuit_breaker:
failure_rate_threshold: 20%   # за окно slow_call_threshold_ms: 1500 half_open_max_calls: 10

6) Меъёри меъёрҳо, квотаҳо, рақобатпазирӣ

Маҳдудиятҳои провайдерро риоя кунед (RPS, таркиш, мувофиқат).
Ба ҳар як иҷорагир WFQ/DRR (адолат) татбиқ кунед, то муштарии "ғавғо" буҷаро нахӯрад.
Ба сарлавҳаҳои 'Retry-After '/' X-Rate' Limit- 'эҳтиром гузоред.
Навбати дохилӣ + пуштибонии маҳсулот.

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

Нақлиёт: MTLS, TLS 1. 2 +, люксҳои ҷории рамзӣ, агар имкон бошад, шаҳодатномаҳои пинҳонӣ.
Аутентификатсия: OAuth2 муштарӣ-эътимоднома/MTLS, HMAC (hash бадан имзо + timestamp), калидҳои API.
Кам кардани PII: танҳо майдонҳои зарурӣ; ниқоб/таҳрир дар гузоришҳо ва DLQ.
Асрҳо: KMS/HashI Corp Vault, гардиши автоматӣ, ҷудокунӣ ба иҷорагир/минтақа.
Мувофиқат: PCI DSS барои PSP, нигаҳдории токен ба ҷои PAN, GDPR/қонунҳои маҳаллӣ.

8) Бисёр иҷорагир ва бисёр минтақа

Танзимоти калидҳо/нуқтаҳои ниҳоӣ барои иҷорагир/минтақа.
Резидентураи маълумот: зангҳо аз минтақаи "хона" садо медиҳанд; салиб - танҳо агрегатҳо.
Ҷудокунӣ: ҳавзҳои пайвастшавӣ ва маҳдудиятҳои як иҷорагир.

yaml tenants:
T1:
region: eu-central provider_keys:
acme_rgs: { client_id: "...", cert_ref: "vault://..." }
psp_foo: { hmac_key_ref: "kms://..." }
endpoints:
acme_rgs: "https://eu. api. acme-rgs. com"
psp_foo: "https://eu. api. psp-foo. com"
T2:
region: sa-east
...

9) Мушоҳида: ченакҳо, гузоришҳо, пайгирӣ

• Муваффақиятҳо/хатогиҳо аз рӯи синф (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 таъхир бо усул.
• Амали меъёри маҳдудият, шикастани кушодан/пӯшидан, сатҳи DLQ, redrive-муваффақият.
• Гузоришҳои сохторӣ: 'иҷорагир _ ид', 'провайдер _ ид', 'operation _ id', 'endpoint', 'status', 'кӯшиш', 'backoff _ ms'.
• Пайгирӣ: ягонаи 'trace _ id', spans "serialize → serialize → ирсоли → харита → нашр кардан", барчасбҳо 'schema _ version', 'минтақа'.

10) Версия ва phicheflags

Дастгирии v1/v2 шартномаи беруна мувозӣ; муҳоҷират - канарӣ/аз ҷониби иҷорагирон.
Ҳама гуна хусусияти провайдери нав дар паси парчам аст; гузариш бе озодкунӣ.
Шартномаи эволютсия: иловаи аввал, санҷиши қатъии схемаҳо (JSON Schema/Proto).

11) Китобҳои бозӣ (китобчаҳо)

1. Squall 429/маҳдудиятҳо: фурӯзон кардани глобалии ҷаҳонӣ, эҳтиром 'Retry-After', тақсим кардани тирезаҳо байни иҷорагирон.
2. Афзоиши вақт: мувофиқатро коҳиш диҳед, танаффусро бодиққат зиёд кунед, вайронкунандаи кушода, таназзули хусусиятро фароҳам оваред.
3. Номутобиқатии схема: redrive-ро ях кунед, харитасозии мувофиқ, backfill/коркард.
4. Парпечи Webhook: гузариш ба ҳолати кашидан/оштӣ кардан, дедупи паёмдонро истифода баред.
5. Ҳодиса дар провайдер: гузариш ба қуттии қуттӣ/нусхаи эҳтиётии DC (агар бошад), амалиёти "таъхиршуда" -ро фаъол созед.

12) Санҷиш

Санҷишҳои шартномавӣ: истеҳсолкунанда/истеъмолкунанда бар зидди ислоҳи провайдери собит.
Санҷишҳои бетартибӣ: таъхирҳо, қатраҳо, фармоишҳо, нусхабардорӣ, посухи қисман, пайвастшавӣ.
Иҷро: стресс дар хӯшаҳои дарида; андозагирии p95/p99, рафтори вайронкунанда.
Idempotency: такрори ҳамон 'operation _ id' таъсири иловагӣ эҷод намекунад.
Sandbox E2E: happy-path/chargeback/conversy/бекоркунӣ/recalc скриптҳо.

13) Намунаҳои ҷойгиркунӣ

Адаптери алоҳидаи хизматрасонӣ: + ҷудокунӣ, варақаҳои мустақил; − шабакаи иловагӣ.
Sidecar/plugin: + маҳалли зангҳо; − идора кардани версияҳо мушкилтар аст.
Китобхона: + ҷойгиркунии осон; − версияҳои баланд ва motley.

Тавсия: адаптер хидмат бо API-и равшан ва давраи барориши он.

14) Намунаи адаптер API (Псевдо)

http
POST /adapters/psp/authorize
Headers:
X-Tenant: T1
Idempotency-Key: op-uuid
Body:
{ "amount":"10. 00","currency":"EUR","method":"card","card_token":"tok_..." }

→ 202 Accepted
{
"operation_id":"op-uuid",
"status":"PENDING",
"as_of":"2025-10-31T12:00:00Z"
}

• Webhook бо 'provider _ event _ id' → 'паёмдони қуттӣ' (PK on '(provider,event_id)') → харитасозӣ → чорабинии домени 'Пардохт ваколатдор'.

15) Хатогиҳои маъмулӣ

Кашидани як схемаи берунии "хом" ба домейн → пайвасти зич ва муҳоҷирати гаронбаҳо.
Набудани idempotency ва паёмдони/outbox → эффектҳои такрорӣ ва ҳолати phantom.
Retrai бе jitter/limits → тӯфон ва манъи маҳдудияти нархҳо.
Ягона ҳавзи ҷаҳонӣ бидуни адолат → як иҷорагир ҳамаро "мегузорад".
Сабтҳо бидуни таҷдиди PII/→ идентификаторҳо наметавонанд ҳодисаҳо ва хатари мутобиқатро тафтиш кунанд.
Ягон канарейка/парчамҳо вуҷуд надоранд → озодкунӣ ҳамаро якбора мешиканад.
Нодида гирифтани 'Retry-After' ва ҷадвалҳои нигоҳдории провайдерҳо.

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

• Харитасозии схемаҳои беруна → забони дохилӣ; версияҳо ва мутобиқати қафо.
• Шиносоии дархостҳо/webhooks ('operation _ id', 'inbox').
• Вақтсанҷӣ, бозсозӣ бо пуррагӣ, сими барқ, DLQ ва redrive бехатар.
• Меъёри адолатро барои як иҷорагир маҳдуд мекунад; эҳтиром ба 'Retry-After'.
• m: TLS/OA/HMAC, гардиши махфӣ, кам кардани PII, аудити дастрасӣ.
• Ҷудокунии минтақавӣ ва будубоши маълумот; конфигуратсияҳо барои иҷорагир/минтақа.
• p95/p99 ченакҳо, хатои синф, breaker/429/DLQ-rate; пайгирӣ.
• Санҷишҳои қуттиҳо ва шартномаҳо; гардиши канарӣ ва phicheflags.
• Китобҳои бозӣ дар бораи ҳодисаҳо ва омӯзиши зангҳо.
• Ҳуҷҷатгузорӣ: SLA, маҳдудиятҳо, схемаҳо, равандҳои эволютсия.

Хулоса

Адаптерҳои провайдер сипар ва тарҷумон байни домени шумо ва ҷаҳони беруна мебошанд. ACL-и қавӣ бо idempotency, назорати хатогӣ ва мушоҳида ҳамгироиро пешгӯишаванда месозад, арзиши тағиротро дар провайдер коҳиш медиҳад ва аз "нокомии занҷир" муҳофизат мекунад. "Адаптерҳои тарроҳӣ ҳамчун ҷузъҳои мустақил, идорашаванда - ва "ҷаҳони беруна" -и шумо шикастани меъмории дохилиро бозмедоранд.