نظام تعبئة الرصيد وإعادة الشحن

يوفر نظام تعبئة الرصيد في OmniCRM بوابة إعادة شحن مسبقة الدفع للخدمة الذاتية للعملاء لإضافة رصيد أو تمديد صلاحية الخدمة عبر بوابة الخدمة الذاتية. تستخدم هذه الميزة بشكل شائع لـ:

• خدمات البيانات المحمولة - بطاقات SIM مسبقة الدفع وخدمات البيانات فقط
• خدمات النقاط الساخنة - أجهزة توجيه WiFi المحمولة وأجهزة الإنترنت المحمولة
• خدمات الإنترنت اللاسلكي الثابت - الوصول إلى الإنترنت مسبق الدفع

نظرة عامة

يسمح نظام التعبئة للعملاء بشراء أيام إضافية من الخدمة من خلال عملية دفع مبسطة متعددة الخطوات مع معالجة مدفوعات Stripe المدمجة.

الميزات الرئيسية:

• بوابة خدمة ذاتية للعملاء (لا حاجة لتدخل الموظفين)
• اختيار مرن للمدة (1-30 يومًا)
• عرض الاستخدام في الوقت الحقيقي قبل الشراء
• معالجة دفع آمنة مدعومة من Stripe
• استرداد تلقائي إذا فشلت عملية التعبئة
• إنشاء الفواتير والمعاملات
• تكامل نظام التزويد لتفعيل الخدمة

الوصول إلى بوابة التعبئة

يتم الوصول إلى بوابة التعبئة عبر رابط عام يمكن للعملاء زيارته دون تسجيل الدخول إلى نظام إدارة علاقات العملاء:

كيف يصل العملاء إليها:

• رابط مباشر يتم إرساله عبر SMS عند انخفاض الرصيد
• رمز QR على المواد المطبوعة
• رابط على بوابة الخدمة الذاتية
• مشاركة عبر دعم العملاء

تكتشف البوابة تلقائيًا خدمة العميل بناءً على عنوان IP أو IMSI الخاص بالطلب.

عملية التعبئة

تتكون عملية التعبئة من 4 خطوات:

الخطوة 1: اختيار البيانات

يختار العملاء عدد الأيام من الخدمة التي يرغبون في شرائها.

واجهة المستخدم:

• تحكم منزلق - اختيار من 1 إلى 30 يومًا
• حساب السعر المباشر - يظهر التكلفة الإجمالية بناءً على الاختيار
• عرض تاريخ انتهاء الصلاحية - يحسب ويظهر متى ستنتهي الخدمة
• عرض الاستخدام الحالي - يظهر الرصيد المتبقي/تاريخ الانتهاء قبل التعبئة

مثال على العرض:

تكوين التسعير:

• يتم تكوين سعر اليوم عبر متغير البيئة REACT_APP_TOPUP_PRICE_PER_DAY
• الافتراضي: 10 دولارات أمريكية في اليوم
• يتم تعيين العملة عبر REACT_APP_CURRENCY_CODE

الخطوة 2: معلومات الفوترة

يقدم العملاء تفاصيل الاتصال الخاصة بهم للمعاملة:

• الاسم الأول
• اسم العائلة
• عنوان البريد الإلكتروني

تستخدم هذه المعلومات لـ:

• إنشاء الفاتورة
• بريد إلكتروني لإيصال الدفع
• سجلات المعاملات
• معالجة الاسترداد (إذا لزم الأمر)

الخطوة 3: الدفع

معالجة دفع آمنة عبر Stripe Elements.

طرق الدفع المدعومة:

• بطاقات الائتمان (Visa، Mastercard، Amex)
• بطاقات الخصم
• المحافظ الرقمية (Apple Pay، Google Pay) إذا كانت مفعلة في Stripe

ميزات الأمان:

• تكامل Stripe متوافق مع PCI
• لا يتم تخزين تفاصيل البطاقة في OmniCRM
• دعم مصادقة 3D Secure
• نقل الدفع مشفر

تدفق الدفع:

1. عرض نموذج Stripe Elements مع إدخال البطاقة
2. يدخل العميل تفاصيل الدفع
3. يتم إنشاء نية الدفع للمبلغ المحدد
4. يتم خصم البطاقة على الفور
5. يتم التعامل مع نجاح/فشل الدفع

::: note ::: title ملاحظة :::

إذا نجح الدفع ولكن فشلت عملية تزويد التعبئة (مثل، خطأ في الشبكة، OCS غير متاح)، يقوم النظام تلقائيًا ببدء استرداد كامل لطريقة دفع العميل. :::

الخطوة 4: الانتهاء

شاشة النجاح:

تم تمديد خدمتك. تاريخ انتهاء الصلاحية الجديد: 17 يناير 2025

تم إرس��ل الإيصال إلى: <customer@example.com> رقم المعاملة: TXN-123456

شاشة الفشل:

إذا فشلت عملية التعبئة، يعرض النظام خطأ ويقوم تلقائيًا بمعالجة استرداد:

لم نتمكن من إكمال عملية التعبئة الخاصة بك. تم استرداد مدفوعتك.

خطأ: غير قادر على الاتصال بنظام الفوترة

يرجى المحاولة مرة أخرى أو الاتصال بالدعم.

معالجة الخلفية

عند إكمال العميل للدفع، يحدث ما يلي تلقائيًا:

1. التحقق من الدفع

يتحقق النظام من:

• حالة نية الدفع هي succeeded
• يتطابق مبلغ الدفع مع الأيام المحددة (days × price_per_day)
• لم تتم معالجة نية الدفع من قبل (يمنع التعبئة المزدوجة)

2. عملية التعبئة

- API endpoint: POST /oam/topup_dongle
- يتحقق من service_uuid و IMSI
- يستدعي OCS/CGRateS لإضافة الرصيد
- ينشئ وظيفة تزويد (play_topup_hotspot)

3. إنشاء السجلات

ينشئ النظام سجلات متعددة في قاعدة البيانات:

• سجل HotspotTopup - يتتبع معاملة التعبئة
  • payment_intent_id
  • service_uuid
  • imsi
  • الأيام المشتراة
  • topup_amount
  • الحالة (نجاح/فشل/تم استرداده)
• سجل المعاملة - معاملة مالية
  • العنوان: "تعبئة النقاط الساخنة - 7 أيام"
  • المبلغ: topup_amount (إيجابي)
  • مرتبط بـ service_id و customer_id
• سجل الفاتورة - فاتورة الدفع
  • تحتوي على معاملة التعبئة
  • تم وضع علامة عليها كمدفوعة على الفور
  • مرجع الدفع: Stripe payment_intent_id
• معاملة الدفع - معاملة ائتمان معاكسة
  • العنوان: "دفع لـ [عنوان الفاتورة]"
  • المبلغ: topup_amount (سلبي - ائتمان)
  • يربط دفع الفاتورة بحساب العميل

4. وظيفة التزويد

يتم إنشاء وظيفة تزويد مع كتاب التشغيل play_topup_hotspot والتي:

• تتصل بواجهة برمجة تطبيقات OCS/CGRateS
• تضيف رصيدًا إلى الحساب
• تمدد تاريخ انتهاء الصلاحية
• تنشئ إدخال سجل النشاط
• ترسل إشعار ت��كيد (إذا تم تكوينه)

ينتظر واجهة برمجة التطبيقات حتى تكتمل عملية التزويد (الاستطلاع بفواصل زمنية قدرها 0.2 ثانية، بحد أقصى 25 تكرارًا) قبل إرجاع النجاح للعميل.

5. استرداد تلقائي عند الفشل

إذا فشلت أي خطوة بعد الدفع:

if topup_provisioning_failed:
    refund = stripe.Refund.create(
        payment_intent=payment_intent_id,
        reason='requested_by_customer'  # استرداد تلقائي من النظام
    )
    status_message = "فشلت عملية التعبئة. يتم استرداد الدفع..."

يتم معالجة الاسترداد تلقائيًا ويتم إخطار العميل على الشاشة.

نقاط نهاية واجهة برمجة التطبيقات

نقطة نهاية التعبئة

POST /oam/topup_dongle
Content-Type: application/json

{
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "imsi": "310120123456789",
  "days": 7,
  "payment_intent_id": "pi_1234567890abcdef",
  "topup_amount": 70.00
}

الاستجابة (نجاح):

{
  "result": "OK",
  "status": 200,
  "provision_id": 456,
  "payment_intent_id": "pi_1234567890abcdef",
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_id": 789
}

الاستجابة (فشل):

{
  "result": "Failed",
  "Reason": "OCS connection timeout",
  "status": 500
}

فحوصات التحقق:

• جميع الحقول المطلوبة موجودة (service_uuid، imsi، days، payment_intent_id، topup_amount)
• يتطابق topup_amount مع الأيام: topup_amount × 100 == days × 1000 (بالسنتات)
• توجد نية الدفع في Stripe
• يتطابق مبلغ نية الدفع: payment_intent.amount == topup_amount × 100
• حالة نية الدفع هي succeeded
• لم تتم معالجة نية الدفع مسبقًا (يتحقق من جدول HotspotTopup)

نقطة نهاية الاستخدام

يسترجع الاستخدام الحالي ومعلومات الخدمة للعميل:

GET /oam/usage

الاستجابة:

{
  "imsi": "310120123456789",
  "service": {
    "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "service_name": "Mobile Data - 0412345678",
    "service_status": "Active"
  },
  "balance": {
    "expiry": "2025-01-10T23:59:59Z",
    "unlimited": true
  },
  "requestingIp": "203.0.113.45"
}

تستخدم هذه النقطة عنوان IP المطلوب لتحديد خدمة العميل تلقائيًا.

التكوين

متغيرات البيئة

قم بتكوين هذه في ملف OmniCRM-UI .env:

# تكوين بوابة التعبئة
REACT_APP_TOPUP_PRICE_PER_DAY=10
REACT_APP_CURRENCY_CODE=AUD
REACT_APP_SELF_CARE_NAME="YourCompany"

# تكوين Stripe
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

تكوين Stripe

يستخدم نظام التعبئة نوايا الدفع من Stripe:

1. تفعيل نوايا الدفع في لوحة معلومات Stripe الخاصة بك
2. تكوين Webhook لتلقي تحديثات حالة الدفع (اختياري ولكن موصى به)
3. إعداد طرق الدفع (بطاقات، محافظ، إلخ)
4. وضع الاختبار - استخدم مفاتيح الاختبار للتطوير

# التطوير
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

# الإنتاج
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

تكوين كتاب التشغيل

يجب تكوين كتاب التشغيل للتزويد play_topup_hotspot.yaml لـ:

• قبول متغير days
• الاتصال بواجهة برمجة تطبيقات OCS/CGRateS
• إضافة رصيد إلى الحساب
• تحديث تاريخ انتهاء صلاحية الخدمة

هيكل مثال كتاب التشغيل:

- name: Top up hotspot service
  hosts: localhost
  tasks:
    - name: Add balance to OCS
      uri:
        url: "{{ ocs_api_url }}/add_balance"
        method: POST
        body:
          imsi: "{{ imsi }}"
          days: "{{ days }}"
          service_uuid: "{{ service_uuid }}"

إشعارات الرصيد المنخفض

يمكن للنظام إرسال إشعارات تلقائية عندما يكون رصيد العميل منخفضًا:

إشعارات SMS:

عند تنشيطها بواسطة أحداث OCS (Action_Balance_Low, Action_Balance_Out, Action_Balance_Expired):

إشعارات البريد الإلكتروني:

تم تكوينها في خطط عمل OCS/CGRateS لإرسال تنبيهات الرصيد.

محفزات الإشعارات:

• Action_Balance_Low - الرصيد أقل من العتبة (مثل، 2 أيام متبقية)
• Action_Balance_Out - نفاد الرصيد
• Action_Balance_Expired - انتهاء الخدمة

تتضمن كل إشعار رابط بوابة التعبئة لسهولة وصول العميل.

استكشاف الأخطاء وإصلاحها

المشكلات الشا��عة

"نظام الدفع غير متاح"

• السبب: فشل تحميل مكتبة Stripe أو مفتاح قابل للنشر غير صالح
• الحل:
  • تحقق من أن REACT_APP_STRIPE_PUBLISHABLE_KEY تم تعيينه بشكل صحيح
  • تحقق من أن حساب Stripe نشط
  • تحقق من وحدة التحكم في المتصفح بحثًا عن أخطاء JavaScript

"فشلت عملية التعبئة. يتم استرداد الدفع..."

• السبب: فشلت وظيفة التزويد (OCS غير متاح، خطأ في كتاب التشغيل، إلخ)
• الحل:
  • تحقق من سجلات التزويد: GET /crm/provision/provision_id/<id>
  • تحقق من أن واجهة برمجة تطبيقات OCS/CGRateS متاحة
  • راجع كتاب التشغيل play_topup_hotspot.yaml بحثًا عن أخطاء
  • تحقق من سجلات Ansible

"تمت معالجة نية الدفع بالفعل"

• السبب: يحاول العميل إعادة استخدام نفس الدفع (مثل، تحديث بعد النجاح)
• الحل: يعمل هذا كما هو مصمم لمنع الفوترة المزدوجة. يجب على العميل بدء تعبئة جديدة إذا لزم الأمر.

"م��لغ نية الدفع لا يتطابق"

• السبب: عدم تطابق بين حساب واجهة المستخدم والتحقق من الخلفية
• الحل:
  • تحقق من أن REACT_APP_TOPUP_PRICE_PER_DAY يتطابق مع توقعات الخلفية (افتراضي 10 دولارات)
  • تحقق من أن تكوين العملة متسق
  • امسح ذاكرة التخزين المؤقت للمتصفح وحاول مرة أخرى

مراقبة التعبئة

عرض سجلات التعبئة:

استعلام عن جدول HotspotTopup لرؤية جميع محاولات التعبئة:

SELECT
  hotspot_topup_id,
  service_uuid,
  days,
  topup_amount,
  status,
  payment_intent_id,
  created
FROM hotspot_topup
WHERE status = 'Failed'
ORDER BY created DESC;

تحقق من حالة التزويد:

GET /crm/provision/provision_id/<provision_id>

يعرض الحالة التفصيلية لوظيفة تزويد التعبئة.

لوحة معلومات Stripe:

راقب المدفوعات، والاستردادات، والمعاملات الفاشلة في لوحة معلومات Stripe الخاصة بك على <https://dashboard.stripe.com>

اعتبارات الأمان

أمان الدفع:

• يتم التعامل مع جميع بيانات البطاقة بواسطة Stripe (متوافق مع PCI المستوى 1)
• لا يتم تخزين بيانات الدفع الحساسة في قاعدة بيانات OmniCRM
• تمنع نوايا الدفع الرسوم غير المصرح بها
• تحقق من المبلغ على كل من جانب العميل والخادم

منع الاحتيال:

• اكتشاف نية الدفع المكررة يمنع الفوترة المزدوجة
• تتبع عنوان IP لربط الاستخدام
• تحقق من IMSI لضمان توجيه التعبئة إلى الخدمة الصحيحة
• تحد من الاستردادات التلقائية التعرض المالي

التحكم في الوصول:

• بوابة التعبئة عامة (حسب التصميم - يحتاج العملاء إلى الوصول)
• تتطلب نقطة نهاية الاستخدام تحديد خدمة صالح (IP أو IMSI)
• يمنع التحقق من الخلفية التعبئة العشوائية للخدمات
• يمكن للمسؤول عرض جميع سجلات التعبئة عبر واجهة CRM

أفضل الممارسات

للمشغلين:

1. اختبار تدفق الاسترداد - اختبار سيناريوهات الفشل بانتظام لضمان عمل الاستردادات
2. مراقبة التعبئات الفاشلة - إعداد تنبيهات لمعدلات الفشل العالية
3. الحفاظ على كتب التشغيل بسيطة - يجب أن تكون كتب تشغيل التعبئة سريعة وموثوقة
4. التحقق من اتصال OCS - التأكد من أن واجهة برمجة تطبيقات OCS متاحة دائمًا
5. مراجعة التسعير - تحديث REACT_APP_TOPUP_PRICE_PER_DAY حسب الحاجة

للعملاء:

1. إضافة رابط التعبئة إلى المفضلة - وصول سريع عند الحاجة
2. حفظ إشعارات الرصيد المنخفض - تحتوي الرسائل النصية على رابط مباشر
3. تحديث البريد الإلكتروني - يتم إرسال الإيصالات إلى البريد الإلكتروني المسجل
4. التحقق من انتهاء الصلاحية قبل السفر - تعبئة قبل مغادرة منطقة التغطية

للمطورين:

1. معالجة Webhooks من Stripe - تنفيذ معالجات Webhook لتحديثات حالة الدفع
2. تنفيذ idempotency - تحقق دائمًا من payment_intent_id قبل المعالجة
3. تسجيل بشكل موسع - تحتاج ��الات فشل التعبئة إلى معلومات استكشاف الأخطاء التفصيلية
4. اختبار مسارات الخطأ - تحقق من أن أتمتة الاسترداد تعمل بشكل صحيح
5. مراقبة الأداء - يجب أن يكتمل استطلاع التزويد في <5 ثوانٍ

الوثائق ذات الصلة

• payments_process - معالجة الدفع العامة
• concepts_provisioning - نظرة عامة على نظام التزويد
• integrations_stripe - تفاصيل تكامل Stripe
• payments_transaction - إدارة المعاملات
• payments_invoices - معالجة الفواتير