توثيق تطبيق سائق التوصيل لووكومرس

ما الذي اشتريته: ثلاثة أجزاء تعمل معًا

خيارات إضافية يمكنك تشغيلها أو إيقافها: يستطيع السائقون الاستحواذ على الطلبات التي لم يأخذها أحد («المجموعة المفتوحة»)، ويستطيعون رفض الطلب، ويمكن جعل صورة التسليم إلزامية.

1. فك ضغط الحزمة التي نزّلتها. ستجد بداخلها الملفين delivery-driver-app-for-woocommerce-plugin.zip وflutter-app-source.zip. لا تفك ضغط هذين الملفين.
2. في WordPress افتح Plugins → Add New → Upload Plugin، واختر delivery-driver-app-for-woocommerce-plugin.zip، ثم انقر Install Now ثم Activate.
3. افتح Settings → Delivery App. إذا ظهرت الصفحة بخمسة تبويبات (Operations وMobile App وSMS & WhatsApp وPush Notifications وApp Builder) فالإضافة جاهزة.
4. تحقق من Settings → Permalinks: أي خيار عدا «Plain» مناسب. انقر Save Changes مرة واحدة إذا تعذّر على التطبيق الوصول إلى متجرك.

1. افتح Users → Add New.
2. املأ اسم المستخدم (مثل maria) والبريد الإلكتروني والاسم وكلمة مرور قوية.
3. اضبط Role على Delivery Boy وانقر Add User.
4. سلّم اسم المستخدم وكلمة المرور إلى السائق. هذا كل شيء.

Operations: قواعد عملك في التوصيل

Mobile App

SMS & WhatsApp

فعّل Enable Automated Texts، واختر المزوّد، والصق المفتاح (والسر إن كان لدى مزوّدك سر)، واكتب اسم المرسِل أو رقمه، وعدّل الرسالتين. يمكنك استخدام {order_id} و{customer_name} و{total} في الرسائل. تُرسل رسالة «في الطريق» عندما ينقر السائق Mark as Picked Up، وتُرسل رسالة «تم التسليم» عند اكتمال الطلب.

Push Notifications

هنا يوضع مفتاح Firebase الخاص بك (الفصل 7).

أ. أنشئ مشروع Firebase

1. انتقل إلى console.firebase.google.com وسجّل الدخول بحساب Google.
2. انقر Add project، واكتب اسمًا (مثل «Acme Drivers»)، وأكمل المعالج. يمكنك إيقاف Google Analytics.

ب. ملف التطبيق: google-services.json (أندرويد)

1. في مشروعك انقر أيقونة Android («Add app»).
2. Android package name: اكتب الاسم الفريد لتطبيقك، مثل com.acme.drivers. دوّنه: يجب أن تستخدم الاسم نفسه تمامًا في App Builder (الفصل 12).
3. انقر Register app ثم Download google-services.json. احتفظ بهذا الملف للفصل 12 أو 13. يمكنك تخطي شاشات Firebase المتبقية.

ج. ملف المتجر: مفتاح حساب الخدمة

1. في Firebase انقر أيقونة الترس ← Project settings ← تبويب Service accounts.
2. انقر Generate new private key وأكّد. سيُنزَّل ملف .json.
3. افتح هذا الملف في محرر نصوص، وحدّد كل محتواه وانسخه.
4. في WordPress افتح Settings → Delivery App → Push Notifications، والصق المحتوى في الحقل، وانقر Save Settings.

د. للآيفون فقط

للآيفون أضف أيضًا تطبيق iOS في Firebase (باستخدام معرّف الحزمة bundle ID)، ونزّل GoogleService-Info.plist، وارفع مفتاح APNs من Apple ضمن Project settings → Cloud Messaging. التفاصيل في الفصل 13.

جرّبه

سجّل الدخول إلى التطبيق على هاتف (الفصل 9)، ثم أسند إلى ذلك السائق طلبًا (الفصل 8). يجب أن يرنّ الهاتف خلال ثوانٍ. تقول ملاحظات الطلب في شاشة الطلب «Push notification sent to driver…» أو تعرض الخطأ الدقيق الصادر من Google إذا حدث خلل.

1. افتح WooCommerce → Orders وانقر طلبًا حالته Processing.
2. في Assign Delivery Boy افتح القائمة واختر السائق.
3. يعرض سطر الحالة «Assigned» ويصل السائق إشعار فوري.

يمكنك تغيير السائق ما دام التوصيل لم ينتهِ. يبدأ السائق الجديد من جديد عند «Assigned». اختيار السطر الفارغ يزيل السائق.

ما تراه في الطلب بعد ذلك

التثبيت وتسجيل الدخول

1. ثبّت تطبيقك (ملف APK من رسالة App Builder الإلكترونية، أو من Google Play).
2. افتحه، واسمح بـالإشعارات والموقع عند الطلب، وسجّل الدخول باسم المستخدم وكلمة المرور اللذين أنشأتهما.
3. تفتح لوحة التحكم. يبقى السائق مسجّلًا للدخول حتى ينقر Logout أو تغيّر كلمة مروره.

لوحة التحكم

تنفيذ توصيل

1. انقر الطلب. يتصل Call بالعميل، ويفتح Navigate العنوان في تطبيق الخرائط.
2. انقر Accept Route (أو Reject this order إذا سمحت بذلك).
3. عند المتجر انقر Mark as Picked Up. يمكن الآن أن يصل العميل رسالة «في الطريق».
4. عند الباب انقر Complete Delivery. إذا لم يكن العميل قد دفع بعد (الدفع عند الاستلام) يعرض الزر Collect Cash & Complete. وإذا فعّلت إثبات الصورة تُفتح الكاميرا: التقط صورة للطرد عند الباب فيكتمل التوصيل.

الأرباح والملف الشخصي

تعرض شاشة الملف الشخصي (أيقونة الشخص أعلى اليمين) Total Earnings من TeraWallet، ورقم هاتف الإرسال (dispatch)، وسجل التوصيل، والخصوصية والشروط، وإصدار التطبيق، وLogout.

حدّد مبلغًا في Operations → Driver Commission per Delivery. عند اكتمال التوصيل تضيف الإضافة هذا المبلغ إلى رصيد TeraWallet الخاص بالسائق. يُدفع مرة واحدة لكل طلب، حتى لو عُدّل الطلب لاحقًا. تعرض ملاحظات الطلب «Credited … to driver». ويرى السائق الرصيد باسم Total Earnings في التطبيق.

ثبّت إضافة TeraWallet المجانية (محفظة WooCommerce) وفعّلها لهذا الغرض. بدونها تعمل عمليات التوصيل، لكن ملاحظة الطلب تقول «Commission not paid: TeraWallet is not active» ويعرض التطبيق 0.00. لصرف مستحقات سائقيك استخدم شاشات TeraWallet نفسها (قائمة Wallet ← تعديل الرصيد أو السحب).

فعّل Settings → Delivery App → SMS & WhatsApp → Enable Automated Texts. يُستخدم رقم هاتف الفوترة للعميل، لذا اجعله حقلًا إلزاميًا في صفحة الدفع واطلب إدخال رمز الدولة.

قبل أن تبدأ

• رمز الشراء الخاص بك.
• أيقونة التطبيق (PNG مربعة، 1024×1024)، وشعار، وصورة شاشة البداية (splash).
• ملف google-services.json من الفصل 7، المُنشأ لاسم الحزمة (package name) الذي ستكتبه أدناه.

خطوة بخطوة

1. افتح Settings → Delivery App → App Builder.
2. Step 1. تحقق من عنوان موقعك (https، دون شرطة مائلة في النهاية)، والصق رمز الشراء، وانقر Connect & load my app. تظهر علامة «Connected» الخضراء. يُخزَّن رمزك على خادمك ولا يظهر مرة أخرى.
3. Step 2. اكتب App name (يظهر تحت الأيقونة على الهاتف) وPackage name (الاسم نفسه الذي أعطيته لـ Firebase، مثل com.acme.drivers) وبريدك الإلكتروني. نرسل رابط التنزيل إلى هذا البريد.
4. Step 3. اختر صور الأيقونة والشعار وشاشة البداية (تُرفع بمجرد اختيارها)، واختر لون شاشة البداية، وارفع google-services.json.
5. Step 4. اختر APK (للتثبيت مباشرة على هاتف وتجربته) أو App Bundle (للرفع إلى Google Play). انقر Save details ثم Start Android build.
6. انتظر رسالة البريد الإلكتروني (عادةً بضع دقائق؛ تُصفّ عمليات البناء في طابور واحدة تلو الأخرى). افتح الرابط على الهاتف لتنزيل ملف APK وتثبيته.

معلومات مفيدة

• تبني الأداة تطبيقات أندرويد. للآيفون استخدم الشيفرة المصدرية (الفصل 13).
• يمكن لكل رمز شراء بناء تطبيق واحد. لتغيير الاسم أو الأيقونة أو الشاشات لاحقًا، احفظ النموذج مرة أخرى وانقر Build مرة أخرى.
• المُرسَل إلى خادم البناء: عنوان موقعك، ورمز الشراء، واسم التطبيق، واسم الحزمة، وبريدك الإلكتروني وهاتفك، ولون شاشة البداية، وصورك الثلاث، وملف Firebase. لا حاجة إلى كلمات مرور المتجر ولا إلى مفاتيح WooCommerce.
• لا يستطيع استخدام هذا التبويب إلا المديرون، وكل طلب محمي برمز أمان.

لتثبيت APK على هاتف: افتح الرابط في متصفح الهاتف، واسمح بـ«التثبيت من هذا المصدر» إذا طلب أندرويد ذلك، ثم افتح التطبيق. سجّل الدخول بحساب سائق من الفصل 5.

المتطلبات

• Flutter 3.41 أو أحدث (يجب أن يكون flutter doctor أخضر)، وAndroid Studio لأندرويد، وXcode وCocoaPods للآيفون.

1. افتح المشروع ووجّهه إلى متجرك

unzip flutter-app-source.zip -d driver_app && cd driver_app
flutter pub get

# run on a connected phone or emulator
flutter run --dart-define=API_DOMAIN=https://yourstore.com

أو غيّر القيمة الافتراضية بشكل دائم في lib/core/constants/app_config.dart:

class ApiConstants {
  static const String domain = String.fromEnvironment(
    'API_DOMAIN',
    defaultValue: 'https://yourstore.com',   // <- your store, no slash at the end
  );
  ...
}

2. أضف ملفات Firebase

• أندرويد: android/app/google-services.json (يعمل إضافة Gradle تلقائيًا عند وجود الملف).
• آيفون: ios/Runner/GoogleService-Info.plist، ثم افتح ios/Runner.xcworkspace في Xcode واسحبه إلى مجموعة Runner إذا ظهر باللون الأحمر.

3. الاسم والحزمة والأيقونات

# unique app id (must match Firebase)
dart run change_app_package_name:main com.acme.drivers

# replace assets/images/icon.png (1024x1024) and assets/images/splash.png, then:
dart run flutter_launcher_icons
dart run flutter_native_splash:create

اسم التطبيق الظاهر على الهاتف موجود في android/app/src/main/AndroidManifest.xml (android:label) وفي ios/Runner/Info.plist (CFBundleDisplayName). وألوان العلامة التجارية في lib/core/constants/app_colors.dart.

4. التوقيع والبناء (أندرويد)

# create a signing key once and keep it safe
keytool -genkey -v -keystore ~/acme-drivers.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

# android/key.properties
storeFile=/Users/you/acme-drivers.jks
storePassword=...
keyAlias=upload
keyPassword=...

في android/app/build.gradle.kts اقرأ هذه القيم داخل كتلة signingConfigs { create("release") { … } } واستخدمها في buildTypes.release بدلًا من مفتاح التصحيح (debug) (في الملف تعليق يوضح الموضع). ثم:

flutter build apk --release --dart-define=API_DOMAIN=https://yourstore.com          # APK to test
flutter build appbundle --release --dart-define=API_DOMAIN=https://yourstore.com     # AAB for Google Play

5. آيفون

cd ios && pod install --repo-update && cd ..
flutter build ipa --release --dart-define=API_DOMAIN=https://yourstore.com

في Xcode اختر Team الخاص بك، وعيّن Bundle Identifier فريدًا (نفسه المستخدم في Firebase)، وأبقِ إمكانية Push Notifications. وارفع مفتاح APNs في Firebase لتعمل الإشعارات الفورية.

أين توجد الأشياء

العنوان الأساسي: https://yourstore.com/wp-json/taqnix/v1. كل شيء عدا /login و/settings يحتاج إلى الرمز (token) الذي تحصل عليه من تسجيل الدخول، ويُرسل في الترويسة X-Driver-Token (ويعمل Authorization: Bearer … أيضًا). مدة صلاحية الرموز 90 يومًا، ويمكن تسجيل دخول السائق على ما يصل إلى 5 هواتف، و/logout ينهي واحدًا منها.

جرّبه

# 1. log in
curl -s -X POST https://yourstore.com/wp-json/taqnix/v1/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"maria","password":"your-password"}'
# -> {"success":true,"data":{"boy_id":7,"token":"7.3f9c…","display_name":"Maria Lopez",...}}

# 2. list my orders
curl -s https://yourstore.com/wp-json/taqnix/v1/orders -H 'X-Driver-Token: 7.3f9c…'

# 3. accept an order
curl -s -X POST https://yourstore.com/wp-json/taqnix/v1/orders/123/status \
  -H 'X-Driver-Token: 7.3f9c…' -H 'Content-Type: application/json' -d '{"status":"accepted"}'

إسناد طلب من شيفرتك الخاصة

// PHP, inside WordPress
$order = wc_get_order( 123 );
$result = TDB_Flow::assign( $order, $driver_user_id );   // sends the push message too
if ( is_wp_error( $result ) ) {
    error_log( $result->get_error_message() );
}

بيانات الطلب التي يمكنك قراءتها

• كل طلب يحتاج إلى رمز تسجيل دخول. بدونه ترد الواجهة بالرمز «401». يُؤخذ معرّف السائق من الرمز وليس من الطلب أبدًا، فلا يستطيع سائق قراءة طلبات سائق آخر أو محفظته أو موقعه، ولا تغييرها.
• الرموز عشوائية وتُخزَّن كتجزئة (hash) أحادية الاتجاه. تسجيل الخروج أو حذف المستخدم أو إزالة الدور ينهي الوصول فورًا.
• ترتيب الخطوات مفروض على الخادم، وتُدفع العمولة مرة واحدة لكل طلب، ويجب أن تكون الملفات المرفوعة صور JPG أو PNG أو WebP حقيقية.
• محاولات تسجيل الدخول محدودة (5 كلمات مرور خاطئة، ثم 15 دقيقة).
• يتطلب تبويب App Builder وكل إجراء إداري صلاحية مدير ورمز أمان؛ ولا شيء متاح للزوار.
• البيانات المخزَّنة: آخر 100 موقع للسائق، ورمز الإشعارات الفورية، ورموز تسجيل الدخول (بيانات المستخدم الوصفية user meta)، وصور التسليم (مكتبة الوسائط)، وملاحظات الطلب. اطلب موافقة سائقيك على مشاركة الموقع واذكر ذلك في سياسة الخصوصية الخاصة بك.

التحديث

ارفع ملف zip الجديد للإضافة مع Replace current with uploaded؛ تبقى إعداداتك وسائقوك. ابنِ إصدارًا جديدًا من التطبيق (الفصل 12 أو 13) واطلب من السائقين التحديث. ارفع Force App Update إلى رقم الإصدار الجديد عندما تريد أن يحدّث الجميع.

إذا كنت تستخدم «Delivery Boy for WooCommerce» (1.0.x) و«Taqnix App Builder»

• هذه الإضافة تحل محلهما معًا. عطّل «Taqnix App Builder» واحذفها؛ أداة البناء فيها صارت الآن تبويب App Builder هنا. أدخل رمز الشراء هناك مرة واحدة.
• ارفع هذه الإضافة فوق القديمة. يبقى سائقوك وإعداداتك وطلباتك.
• تتوقف تطبيقات السائقين القديمة عن العمل عن قصد. أغلق الإصدار 1.1 ثغرة خطيرة: كان بإمكان أي شخص يعرف معرّف السائق حتى ذلك الحين قراءة الطلبات وتغييرها. يسجّل التطبيق الجديد الدخول برمز (token). ابنِ التطبيق الجديد وثبّته، ثم ارفع Force App Update.
• كانت العمولة سابقًا مبلغًا ثابتًا قدره 15، يُدفع من جديد في كل مرة يُحفظ فيها الطلب كمكتمل. أصبحت الآن إعدادًا (القيمة الافتراضية 0) وتُدفع مرة واحدة لكل طلب.

الإزالة

عطّل الإضافة واحذفها. يبقى سائقوك (المستخدمون) وطلباتك وصورك. أما إعدادات الإضافة فتُزال.

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