توثيق تطبيق البائع لووكومرس متعدد البائعين

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

تكتشف الإضافة إضافة السوق لديك تلقائيًا:

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

App Config

Branding

اللون الأساسي والبريد الإلكتروني للدعم ورقم WhatsApp للدعم. يستطيع التطبيق قراءتها من /app-config.

SMS & WhatsApp

فعّل Enable Automated Alerts، واختر المزوّد، والصق المفتاح (والسر) واسم المرسل، وعدّل نص الرسالة. يمكنك استخدام {order_id} و{total} و{store_name} و{customer_name} و{payment_method} و{order_date}. يتلقى البائع هذا النص عند تقديم طلب يحتوي على منتجاته. يؤخذ رقم هاتف البائع من هاتف الفوترة في ملفه الشخصي على ووردبريس.

Push Notifications

Test Notifications

ابحث عن مستخدم، واكتب رسالة، ثم انقر Send Test Push أو Send Test SMS. يظهر في الصفحة الرد القادم من Firebase أو من مزوّد الرسائل النصية، ما يسهّل اكتشاف المشكلات. يجب أن يكون المستخدم قد سجّل الدخول إلى التطبيق مرة واحدة ليتلقى الإشعار.

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

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

ب. ملف التطبيق: google-services.json (Android)

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

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

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

د. لأجهزة iPhone فقط

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

جرّبه

سجّل الدخول إلى التطبيق على هاتف، ثم افتح Test Notifications واختر ذلك المستخدم وانقر Send Test Push. يجب أن يرنّ الهاتف خلال ثوانٍ.

تسجيل الدخول

1. افتح التطبيق واكتب اسم المستخدم وكلمة المرور الخاصين بحساب ووردبريس. يستخدم مديرو المتجر حساب المدير.
2. اسمح بـالإشعارات عندما يطلب الهاتف ذلك.
3. تبقى مسجّل الدخول على هذا الهاتف حتى تنقر Sign Out (أو تنقضي 90 يومًا، أو يُزال الدور). تسجيل الدخول على هاتف ثانٍ لا يُخرجك من الأول.

لوحة التحكم

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

الطلبات

• ابحث برقم الطلب (ويبحث المديرون أيضًا باسم العميل أو بريده الإلكتروني) وصفِّ حسب الحالة.
• افتح طلبًا لترى العميل وطريقة الدفع والمنتجات مع صورها والإجمالي.
• غيّر الحالة من الحقل Order Status في الأعلى (وهو قائمة منسدلة)، مثلًا من Processing إلى Completed. يستطيع البائعون استخدام Processing وOn hold وCompleted وCancelled. أما الحالات الأخرى مثل Refunded فلمديري المتجر فقط.

Inventory (المنتجات)

• ابحث، وصفِّ حسب الحالة، واستخدم Out of stock من لوحة التحكم.
• المس الزر الدائري + في أعلى اليمين لإضافة منتج: الاسم والأسعار وسعر التخفيض والوصف والتصنيفات وكمية المخزون أو حالته وصورة رئيسية وصور المعرض من الكاميرا أو من معرض الصور.
• افتح منتجًا واستخدم القلم لتعديله أو سلة المهملات لحذفه. تذهب المنتجات المحذوفة إلى سلة المهملات.
• يرى البائعون ويعدّلون منتجاتهم الخاصة فقط؛ ويرى مديرو المتجر جميع المنتجات.

الملف الشخصي وإعدادات المتجر

عدّل اسم المتجر والهاتف والعنوان والشعار والبانر، وساعات العمل، وسياسات الشحن والاسترجاع والإلغاء.

عندما يقدّم عميل طلبًا، تحدّد الإضافة البائعين الذين يملكون منتجات فيه وترسل لكل منهم إشعارًا فوريًا («New Order Received! Order #123 total is …») ومعه رسالة نصية إذا كانت مفعّلة. يُبلَّغ مديرو المتجر بكل طلب. ويُعلَن عن كل طلب مرة واحدة فقط.

يجب تسجيل هاتف البائع: يقوم التطبيق بذلك تلقائيًا بعد تسجيل الدخول وفي كل مرة يُفتح فيها التطبيق. الهاتف الواحد يخص حسابًا واحدًا: إذا سجّل شخص آخر الدخول على الهاتف نفسه، يتوقف الحساب السابق عن تلقي التنبيهات منه. وتسجيل الخروج يوقف التنبيهات لذلك الهاتف أيضًا.

قبل أن تبدأ

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

خطوة بخطوة

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

من المفيد أن تعرف

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

المتطلبات

• Flutter 3.41 أو أحدث (flutter doctor بلا مشكلات)، وAndroid Studio لنظام Android، وXcode وCocoaPods لأجهزة iPhone.

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

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

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

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

class AppConfig {
  static const String siteUrl = String.fromEnvironment(
    'API_DOMAIN',
    defaultValue: 'https://yourmarketplace.com',   // <- your store, no slash at the end
  );
  static const String apiBaseUrl = '$siteUrl/wp-json/multivendor-seller/v1';
}

2. أضف ملفات Firebase

• Android: android/app/google-services.json (تُفعَّل إضافة Gradle تلقائيًا عند وجود الملف).
• iPhone: 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.sellers

# 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).

4. التوقيع والبناء (Android)

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

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

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

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

5. iPhone

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

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

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

العنوان الأساسي: https://yourstore.com/wp-json/multivendor-seller/v1. كل شيء عدا /login و/app-config يحتاج إلى الرمز الذي يعيده تسجيل الدخول، ويُرسل بالصيغة Authorization: Bearer … (أو في الترويسة X-Seller-Token). مدة صلاحية الرموز 90 يومًا؛ ولكل هاتف رمزه الخاص (حتى 5 رموز لكل مستخدم).

جرّبها

# log in (admin works too)
curl -s -X POST https://yourstore.com/wp-json/multivendor-seller/v1/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"your-password"}'
# -> {"success":true,"token":"MXx8…","user_id":1,"is_admin":true,...}

# list orders
curl -s 'https://yourstore.com/wp-json/multivendor-seller/v1/seller-orders?status=processing' \
  -H 'Authorization: Bearer MXx8…'

# complete an order
curl -s -X PUT https://yourstore.com/wp-json/multivendor-seller/v1/seller-orders/123 \
  -H 'Authorization: Bearer MXx8…' -H 'Content-Type: application/json' -d '{"status":"completed"}'

السماح لدور آخر باستخدام التطبيق

// functions.php or a small plugin
add_filter( 'mvs_app_roles', function ( $roles ) {
    $roles[] = 'my_custom_vendor_role';
    return $roles;
} );

• كل طلب يحتاج إلى رمز دخول (عدا تسجيل الدخول والإعدادات العامة للتطبيق). لا يستطيع البائع قراءة أو تعديل إلا منتجاته وطلباته وملفه وصوره؛ فالخادم هو من يقرّر، لا التطبيق.
• الرموز عشوائية، وتُحفظ على هيئة تجزئة أحادية الاتجاه، ومدتها 90 يومًا، وهي خاصة بكل هاتف، وتتوقف عن العمل فورًا عند تسجيل خروج المستخدم أو حذفه أو فقدانه الدور.
• محاولات تسجيل الدخول محدودة (5 كلمات مرور خاطئة، ثم 15 دقيقة انتظار).
• يجب أن تكون الملفات المرفوعة صور JPG أو PNG أو GIF أو WebP حقيقية؛ ويجري التحقق من الأسعار والحالات وقيم المخزون.
• لا يستطيع البائعون استرجاع الطلبات أو نقلها إلى سلة المهملات من التطبيق.
• يحتاج تبويب App Builder وكل إجراء إداري إلى مدير ورمز أمان؛ ولا شيء متاح للزوار.
• تبقى أسرار الرسائل النصية وFirebase على خادمك. ولا يُعاد عرض سر الرسائل النصية في صفحة الإعدادات.
• أخبر بائعيك في سياسة الخصوصية بما يتعامل معه التطبيق (الطلبات وأسماء العملاء وأرقام هواتفهم وصور المنتجات).

التحديث

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

إذا كنت تستخدم «MultiVendor Seller App for WooCommerce» 1.0.0 و«Taqnix App Builder»

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

الإزالة

عطّل الإضافة واحذفها. يبقى البائعون والمنتجات والطلبات. أما إعدادات الإضافة فتُزال.

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