نظام الإحالة والتسويق بالعمولة في ڤاريونس للمتاجر الإلكترونية في مصر: روابط وأكواد وتتبع ونِسَب طلبات

يُدار نظام الإحالة من مسار /dashboard/affiliate الذي يعرض مكوّن AffiliatePage بتبويبات: نظرة عامة، والتحليلات، والإدارة، والأمان، والأدوات، والموارد، مع وضعين داخل الصفحة هما «بسيط» و«متقدم». والوضع البسيط هو الجزء الحقيقي المدعوم بقاعدة بيانات، بينما اللوحات المتقدمة (التحليلات، والحملات، والعمولات، والمدفوعات، والصدارة، وكشف الغش، والجغرافيا والأجهزة، ومتعدد المستويات، والإشعارات، والصفحات المخصصة، والمقارنات، والتدريب) تقرأ حالياً بيانات تجريبية من dataStructure/affiliate/mockData ولا تحفظ في قاعدة البيانات.

الوضع البسيط مكوّن من ثلاث قطع: SimpleReferralSteps لإنشاء الرابط، وSimpleStats لعرض المجاميع، وSimpleLinksList لعرض أحدث 10 روابط مع عدد الطلبات والإيراد لكل كود. وكل رابط محفوظ في مجموعة SimpleReferralLink بحقول: userId الخاص بالتاجر، وcode بأحرف كبيرة وفريد، وname اختياري، وurl مطلوب، وعدادات clicks وsignups وconversions التي تبدأ من صفر، مع فهرس مركّب على userId وتاريخ الإنشاء لسرعة الاستعلام.

إنشاء الرابط يتم عبر POST /api/affiliate/simple/create-link بمعدل 20 طلباً في الدقيقة: الكود مطلوب بحد أقصى 20 حرفاً ويُحوَّل لأحرف كبيرة، والرابط مطلوب، والاسم اختياري. والكود فريد عالمياً فإن تكرر ردّ الخادم 409 CODE_ALREADY_EXISTS. وعند النجاح يرد 201 مع id والكود والعدادات. وقائمة الروابط عبر GET /api/affiliate/simple/links تبني رابط المتجر ديناميكياً بصيغة {subdomain}.{baseDomain}/?ref={CODE} من نطاق التاجر المخزّن في User.domain ورؤوس الاستضافة، وتُلحق بكل رابط عدد الطلبات وإجمالي الإيراد بحساب تجميعي على الطلبات. والإحصائيات عبر GET /api/affiliate/simple/stats تجمع clicks وsignups وconversions ثم تحسب totalOrders وordersPerRef من حقل data.affiliateCode في الطلبات. والتعديل عبر PUT /api/affiliate/simple/update-link والحذف عبر DELETE /api/affiliate/simple/delete-link والتحقق من الكود عبر verify-code وتتبع النقرة البسيطة عبر track-click ونسخ الرابط عبر copy-link.

تتبع الزائر يبدأ من مكوّن ReferralTracker الذي يقرأ ?ref= من الرابط ويرسل POST /api/referral/track مع معاملات UTM (utm_source وutm_medium وutm_campaign وutm_term وutm_content) إلى نظام الشراكات، فيُنشأ مستند ReferralClick يحمل partnershipId وreferralCode وعنوان IP ووكيل المستخدم والمُحيل والدولة والمدينة ومعاملات UTM وحالة التحويل converted مع convertedUserId وبيانات الاشتراك (الخطة من free إلى enterprise والمبلغ والعملة EGP وعدد الأشهر وحالة التجديد). ولمنع التكرار يستخدم المكوّن sessionStorage لكل جلسة، ويحفظ الكود في localStorage بمفتاح oro_referralCode لمدة 30 يوماً مع كوكي partner_ref لمدة سنة، بينما يحفظ النظام القديم referralCode لمدة 24 ساعة فقط. وعند التسجيل يقرأ مسار pages/api/users/register.js الكود المخزّن ويرسله إلى track-signup دون تعطيل التسجيل عند الفشل، فيزيد عدّاد signups ويُربط المستخدم الجديد بالرابط.

ونِسَب الطلبات تعتمد على حقل data.affiliateCode في مستند الطلب مع data.totals.grandTotal للإيراد، فيجمع الخادم الطلبات حسب الكود لكل تاجر على حدة. وهذا يعني أن أي طلب يحمل الكود يظهر في إحصائيات SimpleStats وفي عمودي الطلبات والإيراد داخل SimpleLinksList.

وحول النظام خدمات مساندة: أدوات مساعد الذكاء الاصطناعي في features/ai-copilot/tools/affiliate/index.ts تقرأ لوحات الإحالة وتدير الروابط البسيطة (إنشاء وتعديل وحذف) بصلاحيات marketing.view للقراءة وmarketing.create/edit/delete للتعديل، وتطبيق affiliate في سوق التطبيقات (User.enabledApps) ببوابة خطة، وتصنيف affiliate في سجلات التدقيق، ومفاتيح إشعارات affiliate في تفضيلات الإشعارات، وربط الطلبات بكود الإحالة في أعمدة جدول الطلبات.

والأزرار التي سيراها التاجر في الصفحة هي: توليد كود، وإنشاء الرابط، ونسخ الرابط، وتبويبا إنشاء رابط جديد وإدارة الروابط، وتفعيل وإلغاء تفعيل الرابط، وحذف الرابط، وتعديل الاسم، والتبديل بين البسيط والمتقدم، وأزرار التصدير CSV وExcel وPDF، وحاسبة العمولات التفاعلية، وإنشاء الحملات، ومرشحات جدول المدفوعات (مدفوع وقيد الانتظار ومرفوض)، وإعدادات الإشعارات (القنوات: اللوحة والبريد والدفع وSMS، والتكرار: فوري وكل ساعة ويومي وأسبوعي)، وقوالب صفحات الهبوط، ومفتاح الإحالة مدى الحياة، وموارد التدريب.