პროვაიდერების გადამყვანები

პროვაიდერის ადაპტერი არის ინტეგრაციის იზოლირებული ფენა (anti-corruption layer, ACL), რომელიც თარგმნის გარე მიმწოდებლის კონტრაქტს (თამაშის პროვაიდერი, გადახდის კარიბჭე, KYC/AML, რისკის მორიელი, ნოტიფიკაცია და ა.შ.) შიდა დომენის ენაზე და პირიქით. ის ასახავს არასტაბილური API- ების, ქსელის ანომალიების, სქემების ევოლუციებისა და უსაფრთხოების პოლიტიკოსების დომენს.

1. დეკუპლინგი: ბირთვში არ შედის „ნედლეული“ გარეგანი პაილოდი.

2. საიმედოობა: აკონტროლეთ წარუმატებლობები (timeouts, retries, DLQ, circuit breaker).

3. კოორდინაცია: idempotence, საკვანძო წესრიგი, გარიგების მესიჯი.

4. ოპერაცია: მეტრიკა, ტრეისი, ლიმიტები, ტრანს - ჩრდილოვანი იზოლაცია და აღდგენა.

1) ადაპტერის პასუხისმგებლობის არეალი

კონტრაქტები: გარე სქემების/ენდოინტების აღწერა; mapping - შიდა გუნდები/მოვლენები.
ტრანსპორტი: REST/gRPC/WebSocket/SQS/Kafka/SFTP; კავშირების აუზი, backpressure.
უსაფრთხოება: mTLS, OAuth2, HMAC, გასაღებები/სერთიფიკატები per tenant/region, საიდუმლოებების როტაცია.
საიმედოობა: taimauts, retrais ერთად jitter, circuit breaker, deduplication.
Idempotence: 'Idempotence-Key '/' request _ id', პასუხების/სტატუსის შენახვა.
დაკვირვება: SLO მეტრიკა, სტრუქტურული ლოგოები, ტრეკერი.
ვერსია: სქემების/ენდოინების რამდენიმე ვერსიის მხარდაჭერა.
ოპერაციები: ფიჩეფლაგები, კანარის გამოშვებები, ქვიშის ყუთები, სერტიფიკაცია.

2) სად გამოიყენება (კონტექსტის მაგალითები)

თამაშის/RGS: რაუნდის დაწყება/დახურვა, განაკვეთები/მოგება, სესიის ნიშნები, პროვაიდერის სტატუსები.
Payments/PSP: ანაბრები/დასკვნები, webhooks სტატუსები, chargeback, 3-D Secure.
KYC/AML: გადამოწმება, სანქციები/REP შემოწმება, გარიგების მონიტორინგი.
Risk/Fraud: მორიელი, გამომწვევი, საკეტების რეკომენდაციები.
Comms: el-mail/SMS/push, ფოსტის ლიმიტები, შაბლონები.

თითოეულ ტიპს აქვს საკუთარი state ღონისძიების მანქანა და SLA - ადაპტერი ვალდებულია მისი ნორმალიზება.

3) კონტრაქტი და მაპინგი (შიდა და გარე)

• ჩვენ წარმოგიდგენთ Published Language- ს ადაპტერის შიგნით და არასოდეს გავაგრძელებთ პროვაიდერის ველს.
• ყველა შეტყობინებას აქვს 'tenant _ id', 'region', 'provider _ id', '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 და წესრიგი

Request de-dup: 'Idempotency-Key: <operation _ id>' მოთხოვნით; სტორიმი '(op _ id - საბოლოო სტატუსი/პასუხი)' TTL- ით.
Webhook de-dup: ცხრილი 'inbox (provider, event _ id)' როგორც PK.
საკვანძო ბრძანება: სერიული გამოწვევები და დამუშავება 'aggregate _ id' (მაგალითად, 'round _ id' ან 'psp _ tx _ id').
Outbox/Inboxing: გარიგების მესიჯი კონვეიერის ორივე კიდეზე.

5) საიმედოობა: Taimauts, retrai, circuit breaker

Taimauts: მოკლე client-side (p95 ორიენტირებული), ცალკეული connect/read.
Retryable: მხოლოდ retryable (5xx/timeout/429), ექსპონენციური backoff + full jitter, მცდელობების ლიმიტი და საერთო ვადა.
Circuit Breaker: გახსნათ შეცდომების/ლატენტობის ზრდის დროს; graceful degradation (მაგალითად, გამორთეთ 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, burst, concurence).
გააცნობიერეთ პირველი ჩრდილოვანი WFQ/DRR ისე, რომ „ხმაურიანი“ კლიენტი არ ჭამს ბიუჯეტს.
პატივს სცემთ 'Retry-After '/' X-RateLimit-' სათაურებს.
შიდა ხაზები + backpressure მწარმოებელზე.

7) უსაფრთხოება და შესაბამისობა

ტრანსპორტი: mTLS, TLS 1. 2 +, შესაბამისი cipher suites, შესაძლებლობის სერთიფიკატების მიღება.
ავთენტიფიკაცია: OAuth2 client-credentials/MTLS, HMAC (ხელმოწერილი სხეულის ჰეშები + timestamp), API გასაღებები.
PII მინიმიზაცია: მხოლოდ საჭირო ველები; შენიღბვა/გამოცემა ლოგოებში და DLQ.
საიდუმლოებები: KMS/HashiCorp Vault, ავტომატური როტაცია, per tenant/region იზოლაცია.
შესაბამისობა: PCI DSS PSP- სთვის, ტოქსინების შენახვა PAN- ის ნაცვლად, GDPR/ადგილობრივი მონაცემთა კანონები.

8) მულტფილმები და მულტფილმის რეგიონი

გასაღებების/ენდოინების კონფიგურაცია ტენანტზე/რეგიონში.
მონაცემთა აღდგენა: ზარები მზადდება „საშინაო“ რეგიონიდან; ჯვარედინი რეგიონი მხოლოდ ერთეულებია.
იზოლაცია: ნაერთების საკუთარი აუზები და per tenant ლიმიტები.

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 ლატვია მეთოდით.
• Rate-limit სამუშაო, გახსნა/დახურვა breaker, DLQ-rate, redrive-success.
• სტრუქტურული ლოგოები: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• ტრეისი: ერთი 'trace _ id', სპილენძი „serialize-send 'receive' map 'publish“, ჭდეები' schema _ version ',' region '.

10) ვერსიები და ფიჩეფლაგები

შეინარჩუნეთ გარე კონტრაქტი v1/v2 პარალელურად; მიგრაცია - კანარის/ტენანტებისთვის.
ნებისმიერი ახალი მიმღები - დროშის უკან; გადართვის გარეშე.
ევოლუციის ხელშეკრულება: additive-first, სქემების მკაცრი შესაბამისობა (JSON Schema/Proto).

11) Playbooks (runbooks)

1. 429/ლიმიტის მასშტაბი: ჩართეთ გლობალური trottling, პატივი სცეთ 'Retry-After- ს ", გადანაწილდით ფანჯრებს შორის.
2. ტაიმაუთების ზრდა: შეამციროს კონკურენცია, ფრთხილად გაზარდოს ტაიმაუტები, გახსნათ breaker, ჩართოთ fick- ის დეგრადაცია.
3. Schema mismatch: გაყინვა redrive, ჩართეთ თავსებადი mapper, შეასრულეთ backfill/rejection.
4. ვებჰუკების ფლოპი: გადასვლა pull/reconcile რეჟიმში, გამოიყენეთ inbox-dedup.
5. ინციდენტი პროვაიდერს აქვს: გადართეთ ქვიშის ყუთში/სარეზერვო DC (თუ არსებობს), გააქტიურეთ „დაგვიანებული“ ოპერაციები.

12) ტესტირება

ხელშეკრულების ტესტები: producer/consumer პროვაიდერის ჩაწერილი ფიქსატორების წინააღმდეგ.
ქაოსის ტესტები: შეფერხებები, ფრაგმენტები, out-of-order, დუბლიკატები, ნაწილობრივი პასუხი, კავშირის რღვევა.
Performance: სტრესი burst მატჩებზე; გაზომვა p95/p99, ქცევა breaker.
Idempotence: იგივე 'operation _ id' განმეორება არ ქმნის დამატებით ეფექტებს.
E2E ქვიშის ყუთებში: სკრიპტები happy-path/chargeback/სპორები/გაუქმება/recalk.

13) განხორციელების პარამეტრები

ცალკეული ადაპტერი: + იზოლაცია, დამოუკიდებელი გამოშვებები; − დამატებითი ქსელი.
Sidecar/plagin: + ზარის ადგილმდებარეობა; - უფრო რთულია ვერსიების მართვა.
ბიბლიოთეკა: + უბრალოდ ინტეგრირება; - მაღალი შეფუთვა და მრავალფეროვანი ვერსიები.

რეკომენდაცია: ადაპტერი სერვისის მკაფიო 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"
}

• Webhuk s 'provider _ event _ id' inbox '(PK an' (provider, event _ id) ') - mapping - დომენის მოვლენა „Paystault Authorized“.

15) ტიპიური შეცდომები

„ნედლეულის“ გარე სქემის დომენში გადატანა არის მკაცრი კავშირი და ძვირადღირებული მიგრაცია.
Idempotence და inbox/outbox- ის არარსებობა დუბლებს ეფექტებსა და ფანტომურ მდგომარეობებს.
Retrai გარეშე jitter/limites - ქარიშხალი და აკრძალვა.
ერთადერთი გლობალური აუზი fairness- ის გარეშე - ერთი ტენანტი „აყენებს“ ყველას.
ლოგოები PII გამოცემის/იდენტიფიკატორის გარეშე არ შეიძლება გამოიძიონ ინციდენტები და შესაბამისობის რისკი.
არ არსებობს კანარები/დროშები, გამოშვება არღვევს ყველას ერთდროულად.
„Retry-After“ - ის უგულებელყოფა და პროვაიდერის მომსახურების გრაფიკი.

16) ჩეკის სია გაყიდვამდე

• გარე სქემების Mapping არის შიდა ენა; ვერსიები და საპირისპირო თავსებადობა.
• მოთხოვნის/ვებ ჰუკების idempotence ('operation _ id', 'inbox').
• Taimauts, retrais full-jitter, circuit breaker, DLQ და უსაფრთხო redrive.
• Rate limits и fairness per tenant; პატივისცემა 'Retry-After'.
• mTLS/OAuth/HMAC, საიდუმლოებების როტაცია, PII მინიმიზაცია, წვდომის აუდიტი.
• რეგიონალური იზოლაცია და მონაცემთა აღდგენა; კონფისკაციები per tenant/region.
• მეტრიკა p95/p99, შეცდომა კლასებში, breaker/429/DLQ-rate; ტრეისი.
• ქვიშის ყუთები და ხელშეკრულების ტესტები; კანარის rollout და icheflage.
• ინციდენტების ფლეიბუკი და წვრთნა.
• დოკუმენტაცია: SLA, ლიმიტები, სქემები, ევოლუციის პროცესები.

დასკვნა

პროვაიდერების გადამყვანები არის ფარი და მთარგმნელი თქვენს დომენსა და გარე სამყაროს შორის. ძლიერი ACL იდემპოტენტურობით, შეცდომების კონტროლით და დაკვირვებით, ინტეგრაციას პროგნოზირებს, ამცირებს პროვაიდერს ცვლილებების ღირებულებას და იცავს „ჯაჭვში ჩავარდნას“. შეიმუშავეთ გადამყვანები, როგორც დამოუკიდებელი, კონტროლირებადი კომპონენტები - და თქვენი „გარე სამყარო“ შეწყვეტს შიდა არქიტექტურის დაშლას.