# 07 — طبقة التكاملات

> المبدأ: كل تكامل خارجي = **محوّل (Adapter)** خلف واجهة موحّدة، يُفعَّل من [country pack](06-tenant-model.md). إضافة مزوّد جديد = ملف adapter واحد، لا مساس بالمنطق.

## 1. الدفع (Payment Adapters)
```
interface PaymentAdapter {
  charge(ctx, amount, currency): PaymentResult
  refund(ctx, txId): RefundResult
  status(txId): PaymentStatus
}
```
| المزوّد | الأولوية | السوق |
|---------|---------|-------|
| Cash | اليوم الأول | الكل |
| CliQ | P2 | الأردن |
| ZainCash | P2 | الأردن |
| Syriatel Cash / MTN Cash | P2 | سوريا |
| Binance Pay | P2 (عمل جاهز في مستودعك) | عابر |
- التسويات (settlements) للسائقين والمستأجر عبر BullMQ + سجل `payouts`.

## 2. OTP و SMS
- **ذاتي أولاً** (أصل موجود من مشروعك) + **مزوّد احتياطي لكل دولة**.
```
interface SmsAdapter { send(phone, message): SmsResult }
```
- طول الـ OTP و TTL من country pack.

## 3. واجهة المنظّم الحكومي (ميزة تُباع لا عبء)
- نقطة **تصدير/بث موحّدة**: رحلات، سائقون، مركبات — قابلة للتشكيل لكل هيئة.
- مصمّمة على شاكلة متطلبات **هيئة تنظيم النقل البري (تعليمات النقل الذكي)**.
```
interface RegulatorAdapter {
  exportTrips(range): RegulatorPayload
  streamTrip(trip): void      // بث لحظي حيث يُطلب
}
```
- **فصل الأدوار قانونياً:** نحن مزوّد تقنية، المستأجر هو المشغّل المرخّص (يُوثَّق في العقد).

## 4. الإشعارات
- **FCM** للراكب والسائق (قوالب من `notifications`).
- **Webhooks عامة** للمستأجرين المتقدمين (أسطول+/سيادة): نظام محاسبة، ERP أسطول... — توقيع HMAC + إعادة محاولة.

## 5. الخرائط (انطلق) — الخندق التنافسي
- البلاطات عبر **Martin** (HTTPS)، الترميز/التوجيه/snapping من واجهات انطلق.
- **صفر اعتماد على Google** في القلب.
- **طبقة تجريد** في الباك إند والموبايل تسمح بتبديل مزوّد البلاطات لأي مستأجر خارج تغطية انطلق.
- سطر البيع: «خرائط غير محدودة مشمولة — بلا فاتورة للأبد».

## هيكل الكود
```
backend/src/integrations/
├── payments/  { cash, cliq, zaincash, syriatel, mtn, binance }.adapter.ts
├── sms/       { self, twilio, local-jo, local-sy }.adapter.ts
├── regulator/ { ltrc, generic }.adapter.ts
└── registry.ts   # يربط اسم المزوّد (من country pack) بالمحوّل
```

← السابق: [06-tenant-model](06-tenant-model.md) · التالي: [08-data-model](08-data-model.md)