طريقة استخدام Rabet

المتطلبات

• مشروع Laravel قائم يحتوي composer.json وartisan.
• Go لبناء المصدر، مع PHP وComposer لأعمال Laravel.
• حساب sandbox وتوكن من مزود الدفع، وخطة HTTPS لمسارات callback وwebhook.
• نظام تحكم بالإصدارات ونسخة احتياطية قبل التوليد.

مسار التثبيت المنشور — نسخة تأسيسية

يثبّت exact version باسم foundation الإصدار التمهيدي المعتمد، ولا يعني ذلك جاهزية الإنتاج أو يغني عن مراجعة الكود واختبار sandbox. في PowerShell يجب إبقاء اسم الحزمة المحصور ضمن علامتي الاقتباس حتى يُمرَّر الرمز @ إلى npm بدلاً من تفسيره كـsplatting.

npm install --global "@ween.aro7/rabet-kit@0.1.0-foundation.6"

تحقق من صفحة الحزمة العامة على npm. ويمكنك بدلاً من ذلك بناء المصدر في الخطوة التالية.

1. ابنِ الأداة من المصدر

تختلف صيغة مسار الملف التنفيذي بين Windows وmacOS وLinux. من جذر المستودع شغّل:

go build -trimpath -o dist/rabet ./cmd/rabet

2. اضبط sandbox

احفظ RABET_UPAYMENTS_TOKEN وRABET_WEBHOOK_SECRET في مخزن أسرار خاص واضبط RABET_UPAYMENTS_ENVIRONMENT=sandbox. هذه هي الأسماء العامة نفسها في الأداة والقالب المولّد. لا تضع القيم في المستودع أو المتصفح أو رسالة دعم.

3. افحص البيئة

شغّل ./dist/rabet doctor. يفحص الأمر وجود متغير التوكن، وينفذ طلب وصول خفيفاً إلى مضيف UPayments المحدد، ويبلغ عن اكتشاف PHP وComposer وcloudflared. لا يثبت أن بيانات الاعتماد مقبولة لدى البوابة.

4. عاين خطة الملفات

شغّل ./dist/rabet init --dir /path/to/laravel من دون --apply. راجع المسارات الثمانية وأحجامها: .env.rabet.example وapp/Models/RabetPayment.php وapp/Payment/PaymentController.php وapp/Payment/UPaymentsClient.php وapp/Payment/WebhookController.php وconfig/rabet.php وdatabase/migrations/2026_07_17_000000_create_rabet_payments_table.php وroutes/rabet.php. المعاينة خطة ملفات وليست diff كاملاً.

5. طبّق بعد المراجعة

شغّل ./dist/rabet init --dir /path/to/laravel --apply ثم وافق على التأكيد التفاعلي. يبقى التوليد داخل جذر المشروع ويتجاوز الملفات الموجودة بدلاً من الكتابة فوقها. الخيار --force يتجاوز التأكيد، وهو مخصص فقط لبيئة CI مضبوطة وليس المسار المعتاد.

6. أكمل تكامل Laravel

المولد ينشئ PaymentController وendpoint مصادقاً لإنشاء الدفع، لكنه يبقى معطلاً افتراضياً fail-closed. انسخ القيم المطلوبة من .env.rabet.example إلى ملف التطبيق الخاص .env، واضبط العروض والأسعار والتوكن، وشغّل migration، وسجّل routes/rabet.php في bootstrap/app.php أو مزود مسارات مناسب، ثم شغّله داخل Laravel server runtime. لا تلتزم بالأسرار في Git.

يحسب endpoint المبلغ والعملة والطلب على الخادم؛ ولا يقبل من المتصفح سوى offer_id وطريقة الدفع الاختيارية. لا تثق بمبلغ أو رقم طلب من DOM أو JavaScript.

rabet init لا يثبّت Web Component. نزّل نسخة المكوّن العامة المطابقة للمصدر إلى أصل عام في تطبيقك، مثل public/rabet-button.js، واخدمها من النطاق نفسه عبر /rabet-button.js. استخدم checkout-id كمعرّف معتم وفريد للمستخدم ومحاولة الدفع، ولا تضع فيه بريداً أو هاتفاً. إذا طلب المكوّن مراجعة محاولة سابقة فلا تمسح الحظر إلا بعد تحقق الخادم من الحالة، ثم استدعِ clearPreviousAttemptReview({ verified: true }) عند ثبوت إمكانية المحاولة الجديدة. بعد تهيئة endpoint المولد يمكن توصيل المكوّن بهذه الصورة:

<script type="module" src="/rabet-button.js"></script>
<rabet-button
  endpoint="/rabet/create-payment"
  offer-id="foundation"
  checkout-id="opaque-user-checkout-attempt"
  payment-method="knet">
</rabet-button>

7. اختبر وتحقق

اختبر دورة sandbox كاملة واربط الطلب المحلي بمعرف المزود. في 2026-07-17 وصلت عملية UPayments Sandbox بقيمة 1.500 KWD إلى CAPTURED ثم أكدها طلب حالة مستقل من الخادم في تشغيل ببيانات اعتماد. لم تُحفظ بيانات الاعتماد ولا يجوز إعادة استخدام أي قيمة ظهرت سابقاً. لا يعد ذلك دليلاً للإنتاج: أعاد /return العام 404 وقت الالتقاط، وتضيف هذه النسخة صفحة حالة بديلة آمنة، ولا يوجد backend أو webhook عام منشور حتى الآن.

يمكن تشغيل المستمع المحلي عبر ./dist/rabet webhook listen --port 8787 --path /rabet/webhook؛ يرتبط بـ127.0.0.1 ولا ينشئ tunnel عاماً تلقائياً. يعيد مسار webhook المولد جلب الحالة من البوابة ولا يقبل النجاح إلا عند CAPTURED.

8. استخدم MCP اختيارياً

يشغّل عميل MCP الأمر المثبّت على exact version التأسيسي npx --package="@ween.aro7/rabet-kit@0.1.0-foundation.6" -- rabet-mcp كخادم stdio؛ لا ترسل إليه أوامر shell تفاعلية. مثال إعداد العميل:

{
  "mcpServers": {
    "rabet": {
      "command": "npx",
      "args": ["--yes", "--package=@ween.aro7/rabet-kit@0.1.0-foundation.6", "--", "rabet-mcp"],
      "env": {
        "RABET_UPAYMENTS_ENVIRONMENT": "sandbox"
      }
    }
  }
}

حمّل التوكن من مخزن أسرار العملية قبل تشغيل عميل MCP، ولا تكتبه داخل ملف الإعداد. السطح العام محصور في list_payment_methods وcreate_payment_link وget_payment_status؛ ولا توجد أدوات عامة للاسترداد أو capture أو payouts.

يتطلب create_payment_link المعطيات amount الموجب وorder_id وdescription وروابط return_url وcancel_url وnotification_url. استخدم في الإنتاج روابط HTTPS يملكها التاجر: عودة النجاح، عودة الإلغاء، وwebhook للإشعار. العملة اختيارية وافتراضها KWD، وحقول العميل اختيارية.

لاختيار KNET صراحةً أرسل payment_method:"knet". يحوّله المحوّل إلى paymentGateway.src لدى UPayments، لكن ذلك يتطلب تفعيل White Label وKNET لحساب التاجر من المزود. ترك الحقل فارغاً يحافظ على صفحة اختيار UPayments المعتادة.

1. في الاستدعاء الأول أرسل المعطيات المطلوبة من دون العلم أو مع confirm:false؛ يعيد الخادم pending_confirmation ولا ينشئ الرابط.
2. على عميل التكامل عرض التفاصيل والحصول على موافقة المستخدم البشري، ثم إعادة المعطيات نفسها مع العلم الصريح confirm:true. العلم قيمة منطقية فقط ولا يثبت تقنياً حضور إنسان؛ مسؤولية الموافقة على العميل المدمج.

قائمة الانتقال إلى الإنتاج

• احصل على بيانات الإنتاج مباشرة من المزود بعد موافقته، ولا تفترض أن Rabet يفعّل حساب التاجر.
• استخدم مخزن أسرار خاصاً للأسماء الموحدة RABET_UPAYMENTS_TOKEN وRABET_UPAYMENTS_ENVIRONMENT=production وRABET_WEBHOOK_SECRET.
• استخدم HTTPS لمسارات callback وwebhook، ودوّر الأسرار، وراجع الصلاحيات والسجلات والاستجابة للحوادث.
• تحقق من المبلغ والعملة والطلب على الخادم، ونفذ اختبار sandbox ثم اختبار إنتاج محدوداً ومراقباً بعد موافقة المالك المباشرة.
• اضبط الإلغاء والاسترداد والنزاعات لدى التاجر والمزود، وأكمل المراجعة القانونية والأمنية الملائمة لنشاطك.