آداپتورهای ارائه دهنده

آداپتور ارائه دهنده - یک لایه یکپارچه سازی جدا شده (لایه ضد فساد، ACL) که یک قرارداد تامین کننده خارجی (ارائه دهنده بازی، دروازه پرداخت، KYC/AML، امتیاز دهی ریسک، اطلاعیه ها و غیره) را به یک زبان دامنه داخلی ترجمه می کند و بالعکس. این دامنه را از API های ناپایدار، ناهنجاری های شبکه، تکامل طرح و سیاست های امنیتی محافظت می کند.

اهداف کلیدی:

1. جدا شدن: هیچ بار خارجی «خام» به هسته نمی رسد.

2. قابلیت اطمینان: خرابی ها را مدیریت کنید (زمان، تلاش مجدد، DLQ، قطع کننده مدار).

3. سازگاری: idempotency، نظم کلیدی، پیام های معاملاتی.

4. عملیات: معیارها، ردیابی، محدودیت ها، جداسازی انتقال و اقامت.

1) منطقه آداپتور مسئولیت

قراردادها: شرح طرح های خارجی/نقاط پایانی ؛ نگاشت → فرمانهای داخلی/رویدادها.
حمل و نقل: REST/gRPC/WebSocket/SQS/Kafka/SFTP ؛ استخر اتصال، فشار پشتی.
امنیت: mTLS، OAuth2، HMAC، کلید/گواهی در هر مستاجر/منطقه، چرخش اسرار.
قابلیت اطمینان: زمان خاموش، retrays با لرزش، قطع کننده مدار، deduplication.
Idempotency: 'Idempotency-Key '/' request _ id'، ذخیره پاسخ ها/وضعیت ها.
قابلیت مشاهده: معیارهای SLO، سیاهههای ساختاری، ردیابی.
Versioning: پشتیبانی از چندین نسخه از طرح ها/نقاط پایانی.
عملیات: ficheflags، انتشار قناری، sandboxes، صدور گواهینامه.

2) در صورت لزوم (زمینه های مثال)

بازی/RGS: شروع/بستن دور, شرط/برنده, نشانه جلسه, وضعیت ارائه دهنده.
پرداخت/PSP: سپرده ها/برداشت ها، وضعیت وب سایت ها، بازپرداخت، 3-D امن.
KYC/AML: تأیید، تأیید/چک های POP، نظارت بر معاملات.
ریسک/تقلب: به ثمر رساندن، راه اندازی، مسدود کردن توصیه ها.
ارتباطات: ایمیل/SMS/فشار، محدودیت های پستی، قالب ها.

هر نوع ماشین حالت رویداد خود و SLA دارد - آداپتور موظف است آن را عادی کند.

3) قرارداد و نقشه برداری (داخلی ↔ خارجی)

اصول:

ما زبان منتشر شده را در داخل آداپتور وارد می کنیم و هرگز زمینه های ارائه دهنده را بیرون نمی کشیم.
تمام پیام ها حمل '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) بی نظمی و نظم

درخواست حذف: 'Idempotency-Key: <operation_id>' در درخواستها ؛ داستان '(op_id → وضعیت نهایی/پاسخ)' با TTL.
Webhook de-dup: جدول 'صندوق ورودی (ارائه دهنده، event_id)' به عنوان PK.
ترتیب بر اساس کلید: فراخوانی و پردازش توسط 'aggregate _ id' (به عنوان مثال، 'round _ id' یا 'psp _ tx _ id').
صندوق خروجی/صندوق ورودی: پیام های معاملاتی در هر دو لبه خط لوله.

5) قابلیت اطمینان: زمان خاموش، عقب نشینی، قطع کننده مدار

مدت زمان: کوتاه سمت مشتری (p95 گرا)، جداگانه برای اتصال/خواندن.
Retrays: فقط retryable (5xx/timeout/429)، بازگشت نمایی + لرزش کامل، حد تلاش و مهلت کل.
قطع کننده مدار: هنگامی که خطاها/تاخیر افزایش می یابد باز می شود ؛ تخریب برازنده (به عنوان مثال، غیر فعال کردن ویژگی های 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-RateLimit-'.
صف های داخلی + فشار پشتی روی محصول.

7) ایمنی و انطباق

حمل و نقل: mTLS، TLS 1. 2 +، مجموعه های رمزنگاری فعلی، گواهینامه های پین کردن در صورت امکان.
احراز هویت: OAuth2 client-credentials/MTLS، HMAC (هش بدنه امضا شده + برچسب زمان)، کلیدهای API.
به حداقل رساندن PII: فقط زمینه های مورد نیاز ؛ پوشش/ویرایش در سیاهههای مربوط و DLQ.
اسرار: KMS/HashiCorp Vault، چرخش خودکار، انزوا در هر مستاجر/منطقه.
انطباق: PCI DSS برای PSP، ذخیره سازی توکن به جای PAN، GDPR/قوانین داده محلی.

8) چند مستاجر و چند منطقه

پیکربندی کلید/نقطه پایانی در هر مستاجر/منطقه.
اقامت داده: تماس ها از منطقه «خانه» انجام می شود ؛ متقابل منطقه - فقط aggregates.
جداسازی: استخر اتصال خود و محدودیت در هر مستاجر.

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-موفقیت.
سیاهههای مربوط به ساختار: 'tenant _ id'، 'provider _ id'، 'operation _ id'، 'endpoint'، 'status'، 'تلاش'، 'backoff _ ms'.
Tracing: single «trace _ id», spans «serialize → send → receive → map → publish», tags «schema _ version», «region».

10) نسخه و phicheflags

پشتیبانی v1/v2 از قرارداد خارجی به صورت موازی ؛ مهاجرت - قناری/توسط مستاجران.

هر ویژگی ارائه دهنده جدید در پشت پرچم است ؛ تعویض بدون آزادی

قرارداد تکامل: اولین افزودنی، اعتبار دقیق طرح ها (JSON Schema/Proto).

11) کتاب های بازی (کتاب های اجرا)

1. Squall 429/limits: کنترل جهانی را روشن کنید، به «Retry-After» احترام بگذارید، پنجره ها را بین مستاجران توزیع کنید.
2. رشد Timeout: کاهش همزمان، افزایش زمان خروج با دقت، شکن باز، فعال کردن تخریب ویژگی.
3. عدم تطابق طرح: سرخ کردن یخ، نقشه برداری سازگار، پر کردن/پردازش مجدد را فعال کنید.
4. فلپ Webhook: سوئیچ به کشیدن/حالت آشتی، اعمال جعبه dedup.
5. حادثه در ارائه دهنده: سوئیچ به sandbox/پشتیبان گیری DC (در صورت وجود), فعال «معوق» عملیات.

12) تست

تست های قرارداد: تولید کننده/مصرف کننده در برابر اصلاحات ارائه دهنده ثابت.
آزمون هرج و مرج: تاخیر، قطره، خارج از نظم، تکراری، پاسخ جزئی، قطع ارتباط.
عملکرد: استرس در سنبله پشت سر هم ؛ اندازه گیری p95/p99، رفتار شکن.
Idempotency: تکرار همان 'operation _ id' اثرات اضافی ایجاد نمی کند.
Sandbox E2E: اسکریپت های happy-path/chargeback/controversy/cancellation/recalc.

13) الگوهای استقرار

آداپتور خدمات جداگانه: + انزوا، نسخه های مستقل ؛ − شبکه اضافی

Sidecar/plugin: + locality of calls ؛ − مدیریت نسخه ها دشوارتر است.
کتابخانه: + آسان برای جاسازی ؛ − اتصال بالا و نسخه های رنگارنگ.

توصیه: آداپتور خدمات با 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 → آداپتور → هسته:

Webhook with «provider _ event _ id» → 'inbox' (PK on '(provider,event_id)') → نقشه برداری → رویداد دامنه 'PaymentAuthorized'.

15) خطاهای معمول

کشیدن یک مدار خارجی «خام» به یک دامنه → اتصال تنگ و مهاجرت گران قیمت.
فقدان idempotency و صندوق ورودی/صندوق → اثرات تکراری و حالت فانتوم.
Retrai بدون لرزش/محدودیت → طوفان و ممنوعیت در محدودیت نرخ.
تنها استخر جهانی بدون عدالت، یک مستاجر همه را «قرار می دهد».
سیاهههای مربوط بدون تجدید نظر PII/→ شناسه را نمی توان مورد بررسی قرار حوادث و خطر انطباق.
هیچ قناری/پرچم وجود دارد → آزادی می شکند همه در یک بار.
نادیده گرفتن برنامه های تعمیر و نگهداری «Retry-After» و ارائه دهنده.

16) چک لیست پیش فروش

نگاشت طرحوارههای خارجی → زبان داخلی ؛ نسخه ها و سازگاری با عقب.
هویت درخواست/webhooks ('operation _ id', 'inbox').
Timeouts، retrays با full-jitter، قطع کننده مدار، DLQ و redrive امن.
محدودیت نرخ и عدالت در هر مستاجر ؛ احترام به «بازگشت»
mTLS/OAuth/HMAC، چرخش مخفی، به حداقل رساندن PII، ممیزی دسترسی.
جداسازی منطقه ای و اقامت داده ها ؛ پیکربندی در هر مستاجر/منطقه.
معیارهای p95/p99، خطای کلاس، breaker/429/DLQ-rate ؛ دنبال کردن
جعبه های ماسه ای و تست های قرارداد ؛ canary rollout و phicheflags.
playbooks حادثه و آموزش در تماس.
مستندات: SLA ها، محدودیت ها، طرح ها، فرآیندهای تکامل.

نتیجه گیری

آداپتورهای ارائه دهنده یک سپر و مترجم بین دامنه شما و دنیای خارج هستند. ACL قوی با idempotency، کنترل خطا و مشاهده باعث می شود ادغام قابل پیش بینی، هزینه تغییر در ارائه دهنده را کاهش می دهد، و محافظت در برابر "شکست زنجیره ای. آداپتورهای طراحی به عنوان اجزای مستقل و قابل کنترل - و «دنیای خارج» شما متوقف خواهد شد شکستن معماری داخلی.

آداپتورهای ارائه دهنده

نتیجه گیری

با ما در تماس باشید

ارتباط سریع

ویدئو به‌زودی به‌روزرسانی می‌شود

ما در حال حاضر بسیار درگیر پروژه‌ها هستیم