تتبّع المناديب المباشر على الخريطة

الغرض#

تعرض خريطة «تتبّع المناديب» مواقع مناديب الشركة الآن، والطرود التي مع كل مندوب، ومساره خلال الساعات الماضية، ويُحفظ 30 يوماً.

من يستطيع استخدامها؟#

تتاح الخريطة لحسابات موظفي الشركة (أدمن الشركة والمسؤول والهب) وللتاجر الذي يملك شركة توصيل خاصة، إذا كانت في الباقة ميزة live_tracking:

• للشركة: يفعّلها السوبر أدمن في نموذج الباقة، ضمن «ميزات وحدود الباقة» ثم «الميزات المتاحة». وهي غير مفعّلة في الباقات الجديدة، أما الباقة القديمة التي لم تُضبط ميزاتها فتسمح بكل شيء.
• للتاجر صاحب الشركة الخاصة: تُقرأ الميزة من باقة التاجر، ولا يُقيَّد شيء إذا لم توجد في المنصة باقة تجار فعّالة.
• شركة التوصيل الملزَمة بالاشتراك إذا لم يكن لها اشتراك فعّال تُرفض برسالة تطلب التجديد، أما شركة المنصة نفسها والشركات المعفاة من الاشتراك فلا ينطبق عليها هذا الشرط.

ما الذي تحتاجه؟#

• مناديب يسجّلون الدخول من تطبيق المندوب ويسمحون له بالوصول إلى الموقع (يغطي هذا الدليل واجهة الـ API التي يستعملها فقط).
• أن تكون جداول التتبع مجهّزة في قاعدة البيانات (السوبر أدمن ← «صيانة النظام»)، وإلا تعرض الصفحة «الميزة لسا مو جاهزة على السيرفر».
• أن يصل متصفحك إلى unpkg.com (مكتبة الخريطة) وإلى خرائط OpenStreetMap.

استعمال الخريطة#

1. افتح «تتبّع المناديب»

   تجدها في قائمة الشركة (وفي قسم «شركتي للتوصيل» عند التاجر) وعنوانها بالعربية في الواجهة الإنجليزية أيضاً. إن لم تكن الميزة في باقتك ظهرت رسالة «تتبّع المناديب مو ضمن باقتك» مع زر «شوف الباقات».

2. اختر المندوب

   عدّادات أعلى الصفحة تعمل كفلاتر: «الكل» و«متصل» و«عم يتحرّك» و«خامل» و«غير متصل»، إضافة إلى مجموع «طرد معهم». ابحث بالاسم أو الهاتف أو رقم التتبع، ثم اضغط مندوباً. تُحدَّث الخريطة كل 15 ثانية، و«عرض الكل» يضبط الإطار على جميع المناديب.

3. راجع تفاصيله وطروده

   تعرض اللوحة السرعة (كم/س) والبطارية وعدد الطرود وزر اتصال وقائمة مرقّمة بطرود المندوب (توصيل أو استلام، رقم التتبع، الحالة، العنوان، مبلغ التحصيل). الطرد الذي بلا إحداثيات يحمل وسم «بدون موقع على الخريطة». وخانة «لاحق المندوب المختار» تُبقي الخريطة على المندوب.

4. اعرض المسار

   اختر «بدون» أو 2 أو 8 أو 24 ساعة، فيُرسم المسار وتظهر مسافته بالكيلومتر.

يظهر على الخريطة كل مندوب أرسل موقعه. والحالات: متصل (آخر موقع خلال دقيقتين)، وعم يتحرّك (متصل وسرعته 3 كم/س فأكثر)، وخامل (آخر موقع خلال 15 دقيقة)، وغير متصل (أقدم من ذلك)، و«ما بعت موقعه لسا». ويظهر «خارج الدوام» لمن اختار «غير متصل» من التطبيق وليس متصلاً.

ما الذي يجب أن يرسله تطبيق المندوب؟#

تُوثَّق هذه الطلبات بالتوكن Authorization: Bearer الذي يعيده تسجيل دخول المندوب (وبتوكن موظف الشركة أو التاجر في fleet وtrail)، ولا تشترط الترويسة apiKey التي يشترطها تسجيل الدخول وطلبات الطرود.

1. GET /api/v10/deliveryman/tracking-config يعيد tracking_enabled وduty_required وon_duty وinterval (20 ثانية) وdistance_filter (15 متراً).
2. POST /api/v10/deliveryman/location (حتى 30 طلباً في الدقيقة):

curl -X POST "https://YOUR_PLATFORM_HOST/api/v10/deliveryman/location" \
  -H "Authorization: Bearer COURIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lat": 33.5138, "lng": 36.2765, "accuracy": 12, "speed": 4.2, "heading": 90, "battery": 80}'

بعد انقطاع الاتصال أرسل دفعة بصيغة {"points": [ ... ]} (200 نقطة كحد أقصى). ويبيّن الحقل saved في الرد عدد النقاط المحفوظة في المسار. وإذا كانت الميزة غير مفعّلة لشركتك، أو كان المندوب قد اختار «غير متصل» من التطبيق (on_duty تساوي false)، يردّ الـ API بنجاح مع saved بصفر ولا يُحفظ شيء. أما حالة «غير متصل» على الخريطة (لا موقع منذ أكثر من 15 دقيقة) فلا تمنع الإرسال.

3. POST /api/v10/deliveryman/duty بالحقل on_duty يبدّل حالة «متصل». وقد تستعمل التطبيقات القديمة POST /api/v10/deliveryman/parcel-location-update (lat وlong)، وهو يسجّل نقطة أيضاً إذا كانت الميزة مفعّلة ولم يختر المندوب «غير متصل» من التطبيق.

وتستعمل تطبيقات الموظفين GET /api/v10/tracking/fleet وGET /api/v10/tracking/deliverymen/{id}/trail?hours=8 (من 1 إلى 72 ساعة، والافتراضي 8)، بحد 30 طلباً في الدقيقة، وهما يخضعان لميزة الباقة نفسها.

التخزين والحذف بعد 30 يوماً#

يحفظ النظام آخر موقع لكل مندوب، ولا يضيف إلى سجل المسار نقطة إلا إذا كانت القراءة على بعد 15 متراً أو أكثر عن نقطة المقارنة، أو مرّت دقيقة أو أكثر عليها. ونقطة المقارنة في الإرسال المفرد هي آخر قراءة وصلت، وداخل الدفعة المرفوعة هي آخر نقطة حُفظت من الدفعة نفسها. فالمندوب الواقف في مكانه، والتطبيق يرسل قراءة كل 20 ثانية، لا يضيف نقاطاً؛ وتنطبق قاعدة الدقيقة غالباً بعد فجوات الإرسال، فإن رفع المندوب الواقف دفعة متراكمة حُفظت له نقطة واحدة تقريباً عن كل دقيقة من الدفعة. وكل يوم عند 03:40 يحذف tracking:prune نقاط المسار الأقدم من 30 يوماً (ويبقى آخر موقع). ويعمل الأمر عبر مجدوِل Laravel، فلا بد أن تكون مهمة الجدولة (cron) على الخادم مفعّلة.

أخطاء شائعة#

• رسالة «ما في ولا مندوب بعت موقعه لسا…» (لم يرسل أي مندوب موقعه بعد): المناديب لم يفتحوا التطبيق أو لم يسمحوا بالموقع.
• مندوب لا يتحرّك على الخريطة: تحقق من أنه ليس «غير متصل» من التطبيق، فهذا يوقف حفظ مواقعه حتى لو لم تفعّل شرط «متصل».

الحدود والصلاحيات#

• لا تعرض الخريطة إلا مناديب شركتك، وتُرفض الحسابات الأخرى.
• إذا كانت ميزة التتبع غير مفعّلة في الباقة فتعرض صفحة الخريطة شاشة «مو ضمن باقتك»، وتردّ الطلبات التي تجلبها الصفحة (بيانات المناديب ومسار المندوب) ونقطتا النهاية fleet وtrail في الـ API برمز HTTP 403، بينما يستجيب مسار إرسال الموقع من المندوب بنجاح دون حفظ شيء.
• معظم نصوص الصفحة غير مترجمة في الواجهة الإنجليزية فتظهر بالعربية (تُترجم كلمات قليلة مثل «الكل» و«عرض الكل» و«بدون» و«رجوع»).