محولات المزود

محول المزود - طبقة تكامل معزولة (طبقة مكافحة الفساد، ACL) تترجم عقد المورد الخارجي (مزود اللعبة، بوابة الدفع، KYC/AML، تسجيل المخاطر، الإشعارات، إلخ) إلى لغة نطاق داخلي والعكس صحيح. إنه يحمي المجال من واجهات برمجة التطبيقات غير المستقرة، وشذوذ الشبكة، وتطورات المخطط، والسياسات الأمنية.

1. الفصل: لا توجد حمولة خارجية «خام» تصطدم بالنواة.

2. الموثوقية: إدارة الإخفاقات (المهلات، الإعادات، DLQ، قاطع الدائرة).

3. الاتساق: الخصوصية، ترتيب المفتاح، رسائل المعاملات.

4. العملية: المقاييس، والتعقب، والحدود، وعزلة النقل، والإقامة.

1) مجال مسؤولية التكيف

العقود: وصف المخططات/نقاط النهاية الخارجية ؛ رسم خرائط → الأوامر/الأحداث الداخلية.
النقل: REST/gRPC/WebSocket/SQS/Kafka/SFTP ؛ بركة اتصال، ضغط خلفي.
الأمان: mTLS، OAuth2، HMAC، المفاتيح/الشهادات لكل مستأجر/منطقة، تناوب الأسرار.
الموثوقية: المهلة، إعادة التدوير مع النبض، قاطع الدائرة، التفريغ.
الخصوصية: 'Idempotency-Key '/' request _ id'، تخزين الردود/الحالات.
إمكانية الرصد: مقاييس SLO، السجلات الهيكلية، التعقب.
النسخ: دعم إصدارات متعددة من المخططات/نقاط النهاية.
العمليات: ficheflags، إطلاقات الكناري، صناديق الرمل، الشهادة.

2) حيثما ينطبق ذلك (سياقات مثال)

اللعبة/RGS: جولة البداية/الإغلاق، الرهانات/الانتصارات، رموز الجلسة، أوضاع المزود.
المدفوعات/PSP: الودائع/عمليات السحب، أوضاع خطوط الويب، رد التكاليف، 3-D Secure.
KYC/AML: التحقق، وفحص الجزاءات/الملوثات العضوية الثابتة، ورصد المعاملات.
المخاطر/الاحتيال: التسجيل، المحفزات، منع التوصيات.
الاتصالات: البريد الإلكتروني/الرسائل القصيرة/الدفع، حدود البريد، القوالب.

كل نوع له آلة حالة الحدث الخاصة به و SLA - المحول ملزم بتطبيعه.

3) العقود ورسم الخرائط (الداخلية ↔ الخارجية)

• ندخل اللغة المنشورة داخل المحول ولا نسحب مجالات المزود أبدًا.
• تحمل جميع الرسائل "مستأجر _ معرف" و "منطقة" و "مزود _ معرف" و "تشغيل _ معرف" و "إصدار _ 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) الفراغ والنظام

طلب إلغاء: "مفتاح الخصوصية: <operation_id>' في الطلبات ؛ القصة «(op_id → الحالة/الاستجابة النهائية)» مع TTL.
Webhook de-dup: table «inbox (مزود، event_id)» as PK.
الطلب حسب المفتاح: تسلسل المكالمات والمعالجة بواسطة 'مجموع _ معرف' (على سبيل المثال، 'round _ id' أو 'psp _ tx _ id').
Outbox/Inboxing: رسائل المعاملات على حافتي خط الأنابيب.

5) الموثوقية: المهلة، التراجعات، قاطع الدائرة

الوقت المستقطع: جانب العميل القصير (موجه p95)، منفصل للاتصال/القراءة.
Retrays: قابل للتجربة فقط (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، Burst، concurrency).
تطبيق WFQ/DRR لكل مستأجر (عدالة) حتى لا يستهلك العميل «الصاخب» الميزانية.
احترم رؤوس «Retry-After »/« X-RateLimit-».
قوائم الانتظار الداخلية + الضغط الخلفي على المنتج.

7) السلامة والامتثال

النقل: mTLS، TLS 1. 2 +، أجنحة التشفير الحالية، تثبيت الشهادات إن أمكن.
المصادقة: OAuth2 بيانات اعتماد العميل/MTLS، HMAC (تجزئة الجسم الموقعة + الطابع الزمني)، مفاتيح واجهة برمجة التطبيقات.
التقليل إلى أدنى حد: المجالات المطلوبة فقط ؛ الإخفاء/التحرير في السجلات و DLQ.
الأسرار: KMS/HashiCorp 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، إعادة التوليد - النجاح.
• السجلات الإنشائية: "مستأجر _ معرف"، "مزود _ معرف"، "تشغيل _ معرف"، "نقطة النهاية"، "حالة"، "محاولة"، "تراجع _ ms'.
• التتبع: واحد 'trace _ id', spans' seriale → send → receive → receive → publish ", tags 'schema _ version', 'region'.

10) الإصدار والفيشفلاج

دعم v1/v2 من العقد الخارجي بالتوازي ؛ الهجرة - الكناري/من قبل المستأجرين.
أي ميزة جديدة للمزود خلف العلم ؛ التبديل دون إطلاق سراح.
Evolution contract: additive-first, rigerous change of schemes (JSON Schema/Proto).

11) كتب اللعب (كتب التشغيل)

1. Squall 429/limits: تشغيل الاختناق العالمي، واحترام «Retry-After»، وإعادة توزيع النوافذ بين المستأجرين.
2. نمو المهلة: تقليل التزامن، وزيادة المهلة بعناية، وفتح الفاصل، وتمكين تدهور الميزة.
3. عدم تطابق المخطط: تجميد إعادة التوليد، وتمكين مخطط متوافق، وملء/إعادة المعالجة.
4. رفرف Webhook: تبديل وضع السحب/التوفيق، تطبيق inbox dedup.
5. الحادث في المزود: التبديل إلى sandbox/back DC (إن وجد)، تنشيط العمليات «المؤجلة».

12) الاختبار

اختبارات العقد: المنتج/المستهلك مقابل إصلاحات المزود الثابت.
اختبارات الفوضى: التأخير، الإسقاط، الخروج عن النظام، التكرار، الاستجابة الجزئية، قطع الاتصال.
الأداء: الضغط على طفرات الانفجار ؛ قياس p95/p99، كسر السلوك.
الفراغ: تكرار نفس «العملية _ id» لا يخلق تأثيرات إضافية.
Sandbox E2E: happy-path/chargeback/conversy/cancellation/recalc scripts.

13) أنماط النشر

محول خدمة منفصل: + عزل، إصدارات مستقلة ؛ − شبكة إضافية.
Sidecar/plugin: + موقع المكالمات ؛ − أكثر صعوبة في إدارة الإصدارات.
المكتبة: + سهل التضمين ؛ − إصدارات عالية الاقتران ومتنوعة.

توصية: تكييف الخدمة مع واجهة برمجة تطبيقات واضحة ودورة إصدارها.

14) محول مثال واجهة برمجة التطبيقات (زائف)

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 with 'provider _ event _ id' →' inbox '(PK on' (provider,event_id)') → mapping → domain event 'PaymentInformed'.

15) أخطاء نموذجية

سحب دائرة خارجية «خام» إلى مجال → اتصال محكم وهجرات باهظة الثمن.
الافتقار إلى الخصوصية والبريد الوارد/صندوق الخروج → التأثيرات المكررة والحالات الوهمية.
Retrai بدون →/يحد من العاصفة وحظر حد السعر.
المسبح العالمي الوحيد بدون عدالة → مستأجر واحد «يضع» الجميع.
ولا يمكن التحقيق في الحوادث والمخاطر المتعلقة بالامتثال في السجلات التي لا تنطوي على تنقيحات/معرفات → لمؤشر الاستثمار الدولي.
لا توجد أعلام/كناري → الإصدار يكسر الجميع دفعة واحدة.
تجاهل «Retry-After» وجداول صيانة المزود.

16) قائمة مرجعية قبل البيع

• رسم خرائط للمخططات الخارجية → اللغة الداخلية ؛ والتوافق الخلفي.
• هوية الطلبات/الخطابات الشبكية ('التشغيل _ id'، 'inbox').
• المهلة، إعادة الدرج مع النفاخ الكامل، قاطع الدائرة، DLQ وإعادة التوليد الآمن.
• الحد и معدل الإنصاف لكل مستأجر ؛ احترام «إعادة المحاولة بعد».
• mTLS/OAuth/HMAC، التناوب السري، تقليل PII، تدقيق الوصول.
• العزلة الإقليمية والإقامة في مجال البيانات ؛ لكل مستأجر/منطقة.
• p95/p99 metrics, class risror, breaker/429/DLQ-rate; التعقب.
• صناديق الرمل واختبارات العقود ؛ طرح الكناري و phicheflags.
• كتب اللعب أثناء الحوادث والتدريب عند الطلب.
• التوثيق: اتفاقات البيئة المستدامة، والحدود، والمخططات، وعمليات التطور.

استنتاج

محولات المزود هي درع ومترجم بين مجالك والعالم الخارجي. إن الرباط الصليبي الأمامي القوي مع الخصوصية والتحكم في الخطأ وقابلية الملاحظة يجعل عمليات التكامل قابلة للتنبؤ، ويقلل من تكلفة التغيير في المزود، ويحمي من "فشل السلسلة. "محولات التصميم كمكونات مستقلة يمكن التحكم فيها - و "عالمك الخارجي" سيتوقف عن كسر البنية الداخلية.