الدليل التوثيقي الشامل - إضافة Branch Games Manager (BGM) v1.6.0.1

الدليل التوثيقي الممتد لإضافة Branch Games Manager

المرجع الفني والتشغيلي الكامل لإدارة الأكاديميات والأندية الرياضية وفروعها متعددة الألعاب. يغطي التنصيب والجداول المخصصة، طابور إشعارات الواتساب، لوحة الأدمن ولوحة التحكم الميدانية للشورت كود، مصفوفة الصلاحيات لأربعة أدوار، وقواعد بيانات بوابة الذكاء الاصطناعي n8n.

1. نظرة عامة والمعمارية الشاملة

تُعد إضافة Branch Games Manager (BGM) نظاماً متكاملاً لإدارة الأكاديميات والأندية الرياضية على منصة وردبريس ووكمرس. تقوم الإضافة بدمج كافة المبيعات المالية الميدانية والإلكترونية مع التحضير الفوري عبر بطاقات الـ QR وطابور إشعارات الواتساب وبوابة الذكاء الاصطناعي n8n.

إدارة الفروع والملاعب

هيكلة شاملة للفروع (بنين / بنات / مختلط) والملاعب مع منع التعارض الزمني في المواعيد آلياً.

كروت الـ QR والتحضير

توليد بطاقات QR فريدة لكل لاعب مع كاميرا مسح مباشرة سريعة وااختيار اشتراكات الحصص.

طابور الواتساب (44 قالباً)

طابور تتابعي ذكي (Sequential Queue) لحماية الرقم من الحظر، وتخصيص مستلم لكل قالب.

2. لوحتا التحكم والصلاحيات الميدانية وشورت كود الفروع

تعتمد الإضافة على لوحتي تحكم مستقليين تماماً لضمان الأمان وفصل المهام الميدانية عن الإدارة العليا:

1. لوحة تحكم ووردبريس الأساسية (WP-Admin Dashboard)

مخصصة لـ مدير الفروع العام (Super Admin) فقط من القائمة الرئيسية BGM:

إدارة مفاتيح API الخاصة بـ WAWP والذكاء الاصطناعي n8n.
زر 🔓 فك حظر كافة الأجهزة (Unban All IP Addresses) لإلغاء حظر التخمين.
تحرير وتفعيل/تعطيل قوالب الرسائل الـ 44 وتحديد مهلة طابور الانتظار Anti-Ban.
إدارة الخزينة الشاملة، التقارير المالية العامة، وإلغاء قفل المصروفات.
ضبط مهل التهدئة الوقائية (Anti-Spam Cooldown) لرابط التجديد وكروت الـ QR.

2. لوحة التحكم الميدانية للفروع (Front-End Branch Portal)

تظهر على الواجهة الأمامية عبر الشورت كود [bgm_branch_manager_account]:

مدير الفرع (Branch Manager): مشاهدة مبيعات ومصروفات وحضور فرعه فقط ومجموعاته والمدربين.
إداري الفرع (Branch Admin): تحضير المشتركين بالـ QR، وتسجيل المصروفات اليومية للفرع والجنس المسموح (بنين/بنات).
المدرب (Coach): استعراض وجدول مجموعاته التدريبية المسندة إليه فقط وتحضير لاعبيه.
تتضمن كاميرا مسح الـ QR السريعة ونظام حاسبة الحصص المتبقية.

مصفوفة الصلاحيات التفصيلية للأدوار الأربعة (Permissions Matrix)

الدور الإداري	نطاق الرقابة والإشراف	إدارة الخزينة والمصروفات	مسح الـ QR والتحضير	إعدادات API والواتساب
مدير الفروع العام (Super Admin)	جميع فروع الأكاديمية والمباني	كامل + فك قفل المصروفات	لكافة الفروع	التحكم الكامل
مدير الفرع (Branch Manager)	فرعه المخصص فقط	إيرادات ومصروفات فرعه	لفرعه فقط	لا يملك صلاحية
إداري الفرع (Branch Admin)	فرعه والجنس المسموح (بنين/بنات)	إضافة مصروفات يومية فقط	تحضير لاعبين فرعه والجنس	لا يملك صلاحية
المدرب (Coach)	مجموعاته المسندة إليه فقط	لا يملك صلاحية	لاعبين مجموعته فقط	لا يملك صلاحية

3. دليل الشورت كودز المتوفرة (Shortcodes Guide)

الشورت كود (Shortcode)	الوصف والاستخدام الرئيسي	المستخدمين المسموح لهم
`[bgm_branch_manager_account]`	بوابة التحكم الميدانية بالفروع مع كاميرا مسح الـ QR والتحضير والمصروفات.	مدراء الفروع، الإداريين، والمدربين
`[bgm_player_portal]`	بوابة الحساب الشخصي للاعب وولي الأمر لعرض بطاقة الـ QR وجدول الحصص ورصيد الحصص.	المشتركين وأولياء الأمور
`[bgm_renew_button]`	توليد زر التجديد المباشر السريع لعضوية المشترك في الواجهات الأمامية.	جميع المستخدمين المسجلين
`[bgm_debug_notifications]`	نافذة التصحيح والتتبع اللحظي لطابور الإشعارات (تظهر للأدمن فقط).	مدير الفروع العام (Super Admin)

4. خطوات التنصيب وإنشاء جداول قاعدة البيانات

الجداول المنشأة آلياً عند التفعيل (Custom MySQL Tables):

يقوم الكلاس BGM_Install فور تفعيل الإضافة بزرع وتحديث 8 جداول رئيسية في قاعدة بيانات وردبريس لضمان الأداء الفائق والتوافق مع WooCommerce HPOS:

اسم الجدول في DB	الوصف والدور الوظيفي
`wp_bgm_branches`	تخزين بيانات الفروع، السعة الاستيعابية، والجنس (بنين / بنات / مختلط).
`wp_bgm_fields`	تخزين الملاعب الرياضية وربطها بالفروع لحظر التداخل الزمني.
`wp_bgm_groups`	تخزين المجموعات التدريبية، الساعات، الأيام، والمدرب المخصص.
`wp_bgm_attendance`	سجل تحضير الحضور والغياب اللحظي وتاريخ ومقدم الخدمة.
`wp_bgm_expenses`	سجل المصروفات الميدانية، الفواتير المرفقة، وحالة القفل المالي.
`wp_bgm_wa_queue`	طابور إشعارات الواتساب التسلسلي وخيار الإعادة وحالة الإرسال.
`wp_bgm_activity_logs`	سجل مراجعة الحركات والإجراءات الإدارية مع IP والتاريخ.
`wp_bgm_loyalty_points`	سجل نقاط الولاء والمكافآت وتوليد الخصومات التلقائية.

5. إعداد الفروع، الألعاب، الملاعب والمجموعات

إنشاء الفروع والملاعب

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

ربط المجموعات بمنتجات ووكومرس

بعد إنشاء المجموعة التدريبية، يتم ربط سماتها (Variation) بمنتج ووكومرس. فور اكتمال طلب الشراء، يتم ربط المشترك بالمجموعة وتوليد بطاقة الـ QR وإرسال إشعار الترحب آلياً.

6. إدارة طابور الواتساب وإيقاف قوالب الرسائل الـ 44

آلية عمل طابور الرسائل التتابعي (Sequential Message Queue)

لحماية رقم الواتساب الخاص بالأكاديمية من الحظر، يعتمد النظام على BGM_Bulk_Messages و BGM_Cron_Manager لتسيير الرسائل عبر طابور مجدول:

الميزة والإعداد	طريقة العمل والتأثير
المهلة العشوائية (Sequential Delay)	مهلة زمنية عشوائية (بين 5 إلى 15 ثانية) بين الرسائل المحاذية لمحاكاة السلوك البشري الطبيعي.
جدولة ختام اليوم (End-of-Day Scheduling)	جدولة إشعارات نفاد الحصص وتنبيهات الانتهاء لتُرسل تجميعياً في ختام اليوم بدلاً من الإزعاج أثناء التمرين.
دمج الأرقام المكررة (Anti-Duplicate Phone)	عندما يكون رقم هاتف اللاعب مطابفاً لرقم ولي الأمر، يتم دمج الرسائل تلقائياً وإرسال إشعار واحد فقط.
إعادة المحاولة ومراقبة الطابور	لوحة متابعة حالة الرسائل (معلقة، مرسلة، فاشلة) مع إمكانية الضغط على زر إعادة المحاولة أو إفراغ الطابور.

7. دليل قوالب الواتساب الـ 44 المفصلة

تحتوي الإضافة على 44 قالباً مفصلاً ومجهزاّ باللغة العربية مع كافة المتغيرات الديناميكية ومفاتيح التحكم المنفصلة لكل قالب:

الفئة والتصنيف	أمثلة القوالب المدرجة	الوجهة المتاحة (Recipient)
الحضور والغياب (8)	إشعار الحضور، الانصراف، الغياب، التأخير، الانصراف المبكر، الحضور المكرر، تحضير حصة، انصراف حصة.	ولي الأمر اللاعب كلاهما
الاشتراكات والعضويات (10)	الشراء لأول مرة `membership_created`، التجديد، قرب الانتهاء (3 أيام)، الانتهاء، التجميد، الاستئناف، الإلغاء، إجازات.	ولي الأمر اللاعب كلاهما
اشتراكات الحصص Smart Sessions (6)	نفاد رصيد الحصص `session_depleted`، قرب نفاد الحصص، تجميد الحصص، خصم حصة، حصص السماح.	ولي الأمر اللاعب كلاهما
بطاقات الـ QR والولاء (6)	إصدار بطاقة QR، تحديث QR، كارت QR مفقود، منح نقاط ولاء، إصدار كوبون الولاء، استبدال نقاط.	ولي الأمر اللاعب كلاهما
الخزينة والحوالات البنكية (8)	تسجيل طلب حوالة بنكية BACS، تأكيد استلام الحوالة، رفض الحوالة، إصدار فاتورة، تسجيل مصروف، قفل الخزينة.	ولي الأمر اللاعب
الجداول والمدربين والإدارة (6)	تعيين جدول جديد، تغيير موعد التمرين، تغيير الملعب، إلغاء حصة، تذكير الكابتن بالحصة، التقرير الشهري.	ولي الأمر اللاعب كلاهما

8. بطاقات الـ QR، نظام الاشتراكات ورابط التجديد التلقائي

بطاقات QR الذكية ومسح الحضور

يتولد كود QR فريد يتضمن كود المشترك BGM-XXXXX. يمكن للإداري أو الكابتن فتح كاميرا الموبايل من لوحة الفروع لمسح الـ QR وتسجيل الحضور فوراً، مع حاسبة تعارض الاشتراكات متعددة الحصص (Subscription Picker).

رابط التجديد التلقائي الذكي (`renew_url`)

عند استعلام المشترك عبر الواتساب أو الذكاء الاصطناعي، يولد النظام رابط تجديد آمن. بنقرة واحدة، يتم **تسجيل الدخول التلقائي (Auto-Login)**، إفراغ السلة وتجهيزها بعناصر اشتراكه السابقة مع الخصم وتوجيهه مباشرة لصفحة الدفع Checkout!

9. الخزينة وقفل المصروفات والولاء

قفل المصروفات التلقائي

قفل سجل المصروفات لليوميات السابقة آلياً عند منتصف الليل لمنع التعديل أو الحذف من قِبل مدراء الفروع بعد اعتماد الخزينة، مع إمكانية فك القفل من مدير الفروع العام فقط.

نظام نقاط الولاء والمكافآت

منح نقاط مكافآت آلية للاعبين الملتزمين بالحضور وتوليد كوبونات خصم تلقائية تشجيعاً على استمرار الاشتراكات والتجديد.

10. بوابة الذكاء الاصطناعي المباشرة (6 REST API Endpoints)

توفر الإضافة 6 Endpoints مخصصة لربط n8n و ChatGPT مع حظر هجمات التخمين آلياً ونظام عزل الحسابات Zero-Trust Identity Isolation:

GET /wp-json/bgm/v1/ai/health

فحص استجابة وسلامة بوابة REST API والتأكد من توافق المفتاح.

cURL Request

curl -X GET "https://YOUR-SITE.com/wp-json/bgm/v1/ai/health" \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY"

GET /wp-json/bgm/v1/ai/me/profile

استرجاع بيانات بروفايل المشترك، كود اللاعب BGM-XXXXX، ورابط صورة الـ QR بناءً على رقم الهاتف.

cURL Request

curl -X GET "https://YOUR-SITE.com/wp-json/bgm/v1/ai/me/profile" \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
  -H "X-Player-Phone: 0500000000"

GET /wp-json/bgm/v1/ai/me/memberships

استرجاع الاشتراكات الفعالة، رصيد الحصص المتبقي، تاريخ الانتهاء، ورابط التجديد التلقائي renew_url.

cURL Request

curl -X GET "https://YOUR-SITE.com/wp-json/bgm/v1/ai/me/memberships" \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
  -H "X-Player-Phone: 0500000000"

GET /wp-json/bgm/v1/ai/me/schedule

استرجاع جدول الحصص الأسبوعي، الأيام، الأوقات، أسماء الملاعب والمدربين المسندين.

cURL Request

curl -X GET "https://YOUR-SITE.com/wp-json/bgm/v1/ai/me/schedule" \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
  -H "X-Player-Phone: 0500000000"

GET /wp-json/bgm/v1/ai/me/attendance

استرجاع سجل الحضور والغياب التاريخي لـ 12 حصة، مع فحص الحضور اللحظي لليوم وحظر هلوسة الذكاء الاصطناعي بنظام yesterday_inspection.

cURL Request

curl -X GET "https://YOUR-SITE.com/wp-json/bgm/v1/ai/me/attendance" \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
  -H "X-Player-Phone: 0500000000"

GET /wp-json/bgm/v1/ai/products

استعلام دليل منتجات ووكمرس، أسعار الاشتراكات، الرياضات والمجموعات المتاحة للرد على المشتركين الجدد.

cURL Request

curl -X GET "https://YOUR-SITE.com/wp-json/bgm/v1/ai/products" \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY"

11. المهام المجدولة (BGM Cron Jobs Manager)

يعمل الكلاس BGM_Cron_Manager على إدارة 4 مهام خفية أوتوماتيكية للتعامل مع الاشتراكات والواتساب والخزينة:

اسم المهمة المجدولة (Cron Action)	التكرار الزمني	الوظيفة والأثر التشغيلي
`bgm_cron_daily_expiry_check`	يومياً (منتصف الليل)	فحص العضويات والاشتراكات وتغيير حالتها إلى منتهية وإطلاق إشعارات التجديد.
`bgm_cron_process_whatsapp_queue`	كل 1 دقيقة	معالجة إرسال طابور الواتساب التسلسلي ومراعاة مهلة الأرقام المكررة.
`bgm_cron_lock_yesterday_expenses`	يومياً (12:05 ص)	قفل تعديل أو حذف مصروفات اليوم السابق لحماية النزاهة المالية.
`bgm_cron_send_session_reminders`	كل 15 دقيقة	إرسال تذكيرات الحصص المجدولة قبيل الموعد المحدد للاعبين وأولياء الأمور.

12. خطافات المطورين (Actions & Filters Hooks)

أهم الخطافات البرمجية المتاحة لتوسعة الإضافة:

اسم الخطاف (Hook Name)	النوع	الوصف والدور البرمجي
`bgm_send_attendance_notification`	Action	ينطلق فور تسجيل حضور المشترك بالـ QR لبدء معالجة الإشعار.
`bgm_check_absences`	Action	مهمة فحص التأخير والغياب التجميعي كل 5 دقائق.
`bgm_loyalty_coupon_issued`	Action	ينطلق فور تحقيق المشترك لنسبة حضور وتوليد كوبون خصم الولاء.
`bgm_whatsapp_template_placeholders`	Filter	تخصيص وإضافة متغيرات ديناميكية جديدة لقوالب الواتساب.
`bgm_ai_api_profile_response`	Filter	تعديل استجابة بروفايل المشترك المرسلة لبوت الذكاء الاصطناعي n8n.

13. التوافقية مع WooCommerce HPOS وسجلات الأنشطة

WooCommerce HPOS Ready

الإضافة متوافقة بنسبة 100% مع High-Performance Order Storage (HPOS) في ووكومرس، مما يزيد سرعة استرجاع الطلبات والاشتراكات بنسبة 500% في المتاجر الضخمة.

سجلات مراجعة الحركات (Activity Log)

تسجيل كامل لكافة الإجراءات التحريرية (من قام بتحضير المشترك، إضافة مصروف، تعديل اشتراك) مع حفظ اسم المستخدم وعنوان الـ IP والتاريخ والوقت.

14. الأسئلة الشائعة وتفسير الأخطاء

كيف يعمل طابور الواتساب التسلسلي (Sequential Queue) وما فائدته؟

يقوم طابور الرسائل في Branch Games Manager بتخزين كافة الإشعارات في قاعدة البيانات وإرسالها بتتابع زمني محدد (مهلة 5-15 ثانية عشوائية بين الرسائل) لمحاكاة العنصر البشري وتفادي حظر رقم الواتساب الخاص بالأكاديمية.

كيف يمكن إيقاف نوع رسائل معين أو تخصيص المستلم من بين الـ 44 قالباً؟

من لوحة تحكم ووردبريس > BGM > إعدادات الواتساب، يوجد زر تفعيل/تعطيل مستقل لكل قالب من الـ 44 قالباً، بالإضافة لإمكانية تحديد وجهة الإرسال لكل قالب (ولي الأمر / اللاعب / كلاهما).

ما الفرق بين لوحة تحكم ووردبريس ولوحة التحكم الميدانية للفروع؟

لوحة ووردبريس (WP-Admin) مخصصة لمدير الفروع العام لإدارة النظام والمفاتيح والماليات العامة. بينما لوحة الفروع الميدانية (Front-End Portal) تعمل بشورت كود مخصص لمدراء الفروع والإداريين والمدربين لمسح الـ QR ومتابعة الحضور والمصروفات دون دخول لوحة الأدمن.

ما هو رابط التجديد التلقائي الذكي renew_url وكيف يعمل؟

هو رابط آمن يتم توليده آلياً للاشتراك، بمجرد ضغط المشترك عليه يقوم النظام بتسجيل دخوله تلقائياً، إفراغ السلة وتجهيزها بنظرائه من الاشتراك السابق وتطبيق الخصومات ونقله مباشرة لصفحة الدفع Checkout.

ماذا يعني خطأ HTTP 429 وكيف يمكن فك الحظر؟

يعني حظر عنوان الـ IP المعتدي لمدة 15 دقيقة بنظام Brute-Force Protection بعد 5 محاولات خاطئة لمفتاح API الأمان، ويمكن للأدمن فك الحظر فوراً بالضغط على زر 🔓 فك حظر كافة الأجهزة في لوحة BGM.