إنتقل إلى المحتوى الرئيسي

RFC-001: محول الدفع الإلكتروني

الحقلالقيمة
الحالةمتوقف عند بوابة اعتماد المزود
المؤلففريق التطوير
آخر تحديث2026-08-24

القرار الحالي​

الدفع النقدي CASH هو وسيلة الدفع الوحيدة المتاحة للعميل في الإنتاج. لا تستطيع الشركة أو الإدارة تشغيل شام كاش أو البطاقة أو التحويل البنكي من الإعدادات.

يمكن تشغيل محول محاكاة محلي فقط عندما تكون البيئة غير إنتاجية ويحمل المتغير:

ONLINE_PAYMENTS_MODE=development

أما الإنتاج فيجب أن يحمل دائماً:

ONLINE_PAYMENTS_MODE=disabled

يفرض الكود وضع disabled عند NODE_ENV=production حتى لو كانت قيمة المتغير خاطئة، ويرفض فحص ما قبل النشر أي وضع آخر.

سبب القرار​

  • لا تملك شام باص عقد تاجر معتمداً أو مواصفات webhook رسمية قابلة للتحقق.
  • لا يجوز تخمين مسارات API أو التوقيع أو حالات التسوية من مكتبات غير رسمية.
  • الشركات هي التي تستلم النقد من الركاب؛ المنصة لا تستلم أموال الحجز حالياً.
  • تشغيل بوابة ناقصة يعرض الحجز والمحاسبة والاسترداد والتسوية لخطر مالي مباشر.

نشرت شام كاش قناة رسمية لطلب API في https://shamcash.sy/ar/apiRequest، لكن طلب الوصول لا يعادل عقد تكامل مكتمل.

حدود المجال​

يوفر OnlinePaymentAdapter واجهة موحدة للمزود المستقبلي من دون ربط الحجز باسم بوابة محددة. المحول التطويري الحالي:

  • ينشئ معرف محاكاة يبدأ بـDEV- فقط؛
  • لا يتصل بأي خادم خارجي؛
  • لا يقرأ بيانات اعتماد؛
  • لا يغير حجزاً أو معاملة مالية؛
  • لا يقبل webhook لعدم وجود عقد توقيع رسمي؛
  • لا يعلن المزود متاحاً للعملاء أبداً.

تبقى قيم المزود القديمة في الأنواع وتقارير السجل لحفظ التاريخ المالي، ولا تعني إتاحة الوسيلة عند الدفع.

عقد API الحالي​

تقبل مسارات إنشاء الدفع العامة CASH فقط. تعيد محاولة SHAMCASH أو CARD:

{
  "code": "ONLINE_PAYMENTS_DEVELOPMENT_ONLY",
  "available_methods": ["CASH"]
}

مع حالة HTTP 409. تعيد محاولة وسيلة غير معروفة 400. لا يقرأ الخادم بيانات الحجز أو يكتب أي سجل مزود قبل رفض الوسيلة غير المتاحة.

مسار webhook الحالي إشارة جاهزية فقط:

  • يعيد 404 عندما يكون الوضع معطلاً؛
  • يعيد 501 OFFICIAL_CONTRACT_REQUIRED في التطوير؛
  • لا يقرأ payload ولا يحدث قاعدة البيانات.

حماية قاعدة البيانات​

يفرض الترحيل 00278_online_payments_development_only.sql ما يلي:

  1. إعادة كل إعدادات الشركات إلى النقد فقط ومسح بيانات المزود والبنك القديمة.
  2. قيد يمنع تفعيل وسيلة غير نقدية في company_payment_settings.
  3. triggers تمنع جلسات anon وauthenticated من إدخال مزود غير نقدي في payment_transactions وpassenger_payment_methods وtrip_payments.
  4. إبقاء دور الخدمة متاحاً للترحيلات والاستيراد التاريخي والتسوية المصرح بها.

تفاصيل الفوترة​

تفاصيل الفوترة المهنية اختيارية ولا تستخدم إلا في تدفق بطاقة مستقبلي. لا يطلبها الحجز النقدي ولا يعرضها المستند إذا لم تكن موجودة. تبقى snapshot الفاتورة الصادرة ثابتة ولا تتغير بتعديل لاحق لبيانات العميل.

بوابة اعتماد مزود حقيقي​

لا ينتقل أي مزود إلى sandbox متصل أو إنتاج قبل اكتمال جميع البنود:

  1. عقد التاجر وملكية التسوية والمسؤولية عن الاسترداد والنزاع.
  2. مواصفات رسمية ذات إصدار للمصادقة والإنشاء والحالة والإلغاء والاسترداد.
  3. عقد webhook رسمي يشمل التوقيع، الطابع الزمني، replay protection، وإعادة الإرسال.
  4. idempotency موثق لكل أمر مالي.
  5. sandbox وحساب اختبار من المزود.
  6. اختبارات عقد وحالات فشل وانقطاع وتأخير واستجابة مكررة.
  7. تسوية مالية وتقارير فروقات ومسار دعم وتشغيل وحوادث.
  8. مراجعة أمن وخصوصية وإدارة أسرار ودوران مفاتيح.
  9. إطلاق تدريجي ومراقبة ومفتاح إيقاف وخطة rollback.
  10. ترحيل وإصدار إنتاج منفصلان بعد موافقة صريحة.

الاختبارات المطلوبة​

  • قرار الوضع في التطوير والإنتاج.
  • عدم تنفيذ أي اتصال شبكي في المحاكاة.
  • رفض كل وسيلة غير نقدية في customer وadmin وdashboard وdriver.
  • منع إعدادات الشركات من تشغيل الوسائل المخفية.
  • عقد PostgreSQL لجلسات العميل ودور الخدمة.
  • اختبار preflight يمنع نشر إنتاج بوضع تطويري.
  • اختبارات عقد المزود الرسمية قبل أي إطلاق لاحق.

خارج النطاق الحالي​

  • تحصيل بطاقة حقيقية أو حفظ بطاقة.
  • شام كاش حقيقي أو QR دفع خارجي.
  • تحويل بنكي يرفق إثباتاً.
  • استرداد إلكتروني أو chargeback.
  • عمولة منصة أو احتفاظ المنصة بأموال العملاء.