تشغيل نظام التسويق بالعمولة

هذا الدليل هو مرجع التشغيل لنظام Affiliate في ChatAman. يشرح ما يفعله المسوّق، ما تعتمده الإدارة، متى تُنشأ العمولة، وكيف تُدار السحوبات والاستردادات بأمان.

1. الأدوار والصلاحيات

لا يستطيع المسوّق قراءة اتفاقيات أو وثائق KYC أو سجلات مالية تخص مسوّقاً آخر. ملفات KYC والعقود الموقعة خاصة؛ تنزيلها يمر عبر مسار مصرح به.

2. المصطلحات المهمة

3. رحلة المسوّق من التسجيل حتى السحب

flowchart TD
    A[المستخدم يسجل في Affiliate] --> B[الإدارة تعتمد الحساب]
    B --> C[يشارك رابط /ref/{code}]
    C --> D[زائر يسجل مؤسسة]
    D --> E[Referral بحالة pending]
    E --> F[أول دفعة ناجحة]
    F --> G[Referral تصبح active وعمولة pending]
    G --> H[اعتماد العمولة]
    H --> I[KYC verified + Agreement signed]
    I --> J[طلب سحب]
    J --> K[الإدارة تعتمد السحب]
    K --> L[الإدارة تسجل الدفع]

3.1 التسجيل والاعتماد

1. يدخل المستخدم إلى /affiliate.
2. إذا لم يكن مسجلاً، يختار عملة الحساب وطريقة السحب ثم يرسل طلب التسجيل.
3. ينشئ النظام كود إحالة ورابطاً بالشكل https://dev.chataman.com/ref/{CODE}.
4. يعتمد مدير النظام الحساب من لوحة الإدارة. لا يبدأ المسوّق في الحصول على عمولات قبل أن تكون حالة الحساب active.

3.2 مشاركة رابط الإحالة

الرابط العام هو /ref/{code} وليس رابط تسجيل مباشر. عند فتحه:

• يسجل النظام النقرة مع حماية rate limit (throttle:affiliate-clicks).
• يحتفظ بكود الإحالة حتى يتم تسجيل المؤسسة.
• تربط المؤسسة بأول إحالة صالحة فقط؛ لا يمكن لمسوق آخر خطف نفس المؤسسة لاحقاً.

3.3 التحويل وأول دفعة

عند تسجيل المؤسسة من كود صالح ينشئ النظام Referral بحالة pending. عند أول BillingTransaction إيجابية من نوع payment:

1. تتحول Referral إلى active.
2. يحفظ النظام الخطة المرتبطة بالمؤسسة إن وجدت.
3. يختار قاعدة العمولة الأنسب.
4. ينشئ Commission بحالة pending.

إذا كانت القاعدة غير متكررة (is_recurring = false) فلا تنشأ عمولة أخرى لنفس العميل. إذا كانت متكررة، تلتزم بحد الأشهر إن تم ضبطه.

4. إدارة قواعد العمولات

المسار الإداري: /admin/affiliates/commission-rules/list.

الحقول الرئيسية:

ترتيب الاختيار ثابت لتفادي النتائج المفاجئة:

1. مسوّق محدد + خطة محددة.
2. مسوّق محدد لجميع الخطط.
3. جميع المسوقين + خطة محددة.
4. القاعدة العامة.
5. داخل نفس المستوى، الأعلى priority ثم الأحدث بالمعرف.

مثال عملي

• قاعدة عامة: 10% لجميع الخطط، أولوية 100.
• قاعدة Gold: 15% لخطة Gold، أولوية 10.
• قاعدة خاصة للمسوّق أحمد على Gold: 20%، أولوية 1.

دفعة عميل أحمد على Gold تستخدم 20% لأن القاعدة الأكثر تخصيصاً تتقدم على الأولوية العامة.

5. حالات العمولة والأرصدة

لا تعتمد الحسابات على قيمة العمولة وحدها؛ تستخدم القيم التالية:

الصافي المتاح للعمولة = commission_amount - reversed_amount - paid_amount - الحجوزات النشطة

وهذا يمنع استخدام نفس العمولة في أكثر من طلب سحب ويتيح السحب الجزئي من عمولة واحدة.

6. دورة السحب

المسار للمسوّق: /affiliate/withdrawals.

شروط إرسال الطلب

يجب أن تكون كل الشروط التالية صحيحة:

1. حساب المسوّق active.
2. KYC حالته verified.
3. يوجد عقد Affiliate موقع وغير ملغى.
4. المبلغ يساوي أو يتجاوز min_payout_threshold.
5. المبلغ لا يتجاوز الرصيد الصافي المتاح من العمولات المعتمدة.

ما الذي يحدث عند الطلب؟

ينشئ النظام Withdrawal بحالة pending، ثم يحجز بالضبط المبلغ المطلوب من أقدم العمولات المعتمدة. يمكن أن تكون الحصص كالتالي:

ما يفعله المدير

المسار الإداري: /admin/affiliates/withdrawals/list.

1. راجع هوية المسوّق وطريقة السحب والتفاصيل.
2. اعتمد المبلغ. يمكن اعتماده أقل من المطلوب، لكن ليس صفراً أو أكبر من المطلوب.
3. بعد التحويل الخارجي، سجّل transaction_reference واضغط Paid.
4. لا تضغط Paid قبل إتمام التحويل الفعلي؛ هذا الإجراء يحرك الرصيد من pending_balance إلى paid_balance ولا يعاد إذا كان السحب مدفوعاً بالفعل.

الرفض

السحب في pending أو approved يمكن رفضه. عند الرفض تحذف الحجوزات فوراً وتعود العمولات المتبقية متاحة لطلب جديد.

7. Refund وChargeback

أي BillingTransaction سالبة من نوع payment تعامل كاسترداد:

1. يبحث النظام عن العمولة الأصلية باستخدام original_transaction_id أو نفس payment entity.
2. يحسب نسبة الاسترداد من قيمة الدفعة الأصلية.
3. ينشئ Reversal فريداً؛ إرسال نفس refund مرتين لا يكرر الخصم.
4. يحدث reversed_amount ويُلغي العمولة عند عكسها بالكامل.
5. إذا كانت العمولة حُجزت في سحب نشط، يرفض النظام السحب ويلغي حجوزه.
6. إذا كانت العمولة اعتمدت، ينقص الرصيد المعلق وإجمالي المكتسب. وإذا سبق دفعها قد ينتج رصيد تسوية سلبي يحتاج متابعة مالية.

مثال

دفعة 100 USD أنتجت عمولة 20 USD. Refund بقيمة 50 USD يعكس 10 USD من العمولة، وليس 20 USD.

8. KYC والعقد

KYC للمسوّق

المسار: /affiliate/kyc.

يرفع المسوّق بيانات الفرد أو الشركة ووثائق الهوية. القيود:

• الصور: JPG/JPEG/PNG.
• المستندات: PDF مسموح حيث يلزم.
• الحد الأقصى للملف: 10 MB.
• تظل الملفات على تخزين خاص، ولا تتاح إلا عبر صلاحيات الإدارة ورابط موقع.

حالات KYC: pending وverified وneeds_update وrejected.

العقد

المسار: /affiliate/agreement.

ينشئ المدير قالب العقد من /admin/affiliates/agreement-templates ثم يرسله للمسوّق. التوقيع:

• يطبق على عقد pending فقط ويكون idempotent عند تكرار الطلب.
• يقبل توقيع PNG بصيغة base64 مع حدود الحجم والأبعاد.
• يحتفظ النظام بالنسخة الموقعة في تخزين خاص ويوفر تنزيلها للمسوّق صاحب العقد فقط.

9. المواد التسويقية والمسوقون الفرعيون والمكافآت

المواد التسويقية

المسار: /affiliate/assets.

تظهر المادة فقط إذا كانت نشطة، مناسبة للغة المسوّق، ويحقق المسوّق حد المستوى المطلوب. يستطيع المدير إدارتها من /admin/affiliates/assets وتتبع عدد التحميلات.

المسوقون الفرعيون

يمكن للمسوّق تسجيل مسوّق مستوى ثان عبر /affiliate/sub-affiliates/register. العمولات الفرعية تخضع لضوابط النظام ولا تكرر العمولة الأصلية؛ راجع إعدادات البرنامج قبل تفعيلها تجارياً.

مكافآت الإنجاز

ينشئ المدير أهدافاً من /admin/affiliates/bonus-milestones مثل عدد الإحالات أو الإيراد أو العملاء النشطين. تظهر المكافآت المكتسبة في /admin/affiliates/bonuses ويمكن اعتمادها منفردة أو جماعياً.

10. التشغيل اليومي للإدارة

بداية البرنامج

1. أنشئ قاعدة عمولة عامة فعالة.
2. أنشئ قالب عقد افتراضياً مناسباً للغة والمستوى.
3. أضف مواد تسويقية قابلة للاستخدام.
4. اعتمد أول مسوّق اختباري.
5. افتح رابط الإحالة، سجل مؤسسة اختبارية، وسجل دفعة اختبارية.
6. راجع أن العمولة ظهرت وأن الـaudit log سجل الخطوات.

روتين يومي

1. راجع طلبات KYC الجديدة.
2. راجع السحوبات المعتمدة فقط بعد التحقق من بيانات الدفع.
3. راجع refunds والـchargebacks وأي سحب رفض تلقائياً بسببها.
4. راقب Audit Log للعمليات الحساسة.
5. راجع العمولات المعلقة والمنتهية ومؤشرات التحويل.

11. مسارات الواجهة الأساسية

للمسوّق

للإدارة

12. قائمة اختبار قبل الإنتاج

نفذ الحالات التالية ببيانات اختبار مستقلة قبل تفعيل تحويلات فعلية:

• [ ] رابط الإحالة يسجل النقرة وينسب المؤسسة للمسوّق الصحيح.
• [ ] أول دفعة تحول Referral من pending إلى active وتنشئ عمولة واحدة.
• [ ] القاعدة الخاصة بمسوّق وخطة تتغلب على القاعدة العامة.
• [ ] قاعدة غير متكررة لا تنشئ عمولة ثانية للعميل نفسه.
• [ ] سقف عمولة العميل يمنع تجاوز الحد حتى مع دفعات متزامنة.
• [ ] طلب سحب جزئي يحجز مبلغاً دقيقاً فقط.
• [ ] اعتماد سحب أقل من المطلوب يحرر الجزء غير المعتمد.
• [ ] Paid مرتين لا يخصم الرصيد مرتين.
• [ ] رفض السحب يحرر الحجوزات.
• [ ] Refund جزئي يعكس نسبة صحيحة من العمولة مرة واحدة فقط.
• [ ] Refund مع سحب نشط يرفض السحب ويمنع صرف عمولة مستردة.
• [ ] KYC والعقد يمنعان السحب حتى الاعتماد والتوقيع.
• [ ] العربية والإنجليزية لا تعرضان مفاتيح ترجمة أو اتجاه نص خاطئ.
• [ ] الموبايل لا يعرض horizontal overflow في Dashboard وCommissions وWithdrawals.

13. استكشاف الأخطاء

14. ملاحظات أمان وتشغيل

• لا تستخدم حساب مدير أو طلب سحب حقيقياً لاختبار الواجهة.
• لا تعدل أرصدة Affiliate أو حالات Withdrawal مباشرة من قاعدة البيانات.
• احتفظ بمرجع التحويل الخارجي عند تعليم السحب Paid.
• راجع Audit Log قبل وبعد أي عملية مالية يدوية.
• اختبر webhook الدفع بعد أي تغيير في Billing أو مزود الدفع؛ فهو نقطة بدء العمولة التلقائية.
• استخدم بيئة dev أو sandbox للتجارب المالية، ثم انقل الإعدادات المعتمدة فقط إلى production.