demo store

المتجر التجريبي لطبقة التجارة

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

يتكون مشروع Demo Store من مستودعين، أحدهما هو قالب GitHub.

ما هي طبقة التجارة؟

Commerce Layer عبارة عن واجهة برمجة تطبيقات للتجارة متعددة الأسواق ونظام لإدارة الطلبات يتيح لك إضافة إمكانات التسوق العالمية إلى أي موقع ويب أو تطبيق جوال أو chatbot أو جهاز يمكن ارتداؤه أو صوت أو جهاز IoT بسهولة. قم بتكوين مجموعتك باستخدام أفضل الأدوات التي أتقنتها وتحبها بالفعل. اجعل أي تجربة قابلة للتسوق، في أي مكان، من خلال واجهة برمجة تطبيقات سريعة وآمنة على مستوى المؤسسات.

جدول المحتويات

• سمات
• كيف يعمل
• ابدء
• التخصيص
• نشر
• بحاجة الى مساعدة؟
• استكشاف الأخطاء وإصلاحها
• رخصة

سمات

قررنا إنشاء متجر تجريبي مع إزالة جميع خدمات الجهات الخارجية التي تُستخدم عادةً لإنشاء تجربة شاملة لموقع التجارة الإلكترونية (CMS، البحث، PIM، وما إلى ذلك).

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

يأتي المتجر التجريبي مع:

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

يتم تحقيق التكامل مع Commerce Layer من خلال الاستفادة من بعض أدوات التطوير مفتوحة المصدر لدينا، وتحديدًا:

• مكتبة مصادقة JS
• جافا سكريبت SDK
• مكونات الرد
• العربة المستضافة
• الخروج المستضاف

كيف يعمل

يتكون مشروع المتجر التجريبي من مستودعين يمكنك الاستفادة منهما لبناء متجرك الخاص، بناءً على مقدار التخصيص الذي تحتاج إلى إضافته:

• demo-store

  هذا هو قالب GitHub الذي يستخدم demo-store-core المذكورة أدناه كوحدة فرعية لـ git. إذا كنت راضيًا عن الميزات والشكل والمظهر للمتجر التجريبي لطبقة التجارة، فنقترح عليك اتباع هذا المسار. لن تضطر إلى الاهتمام بكود المصدر بالكامل وسيكون لديك الحرية في التركيز فقط على البيانات والمحتوى الخاص بك. علاوة على ذلك، ستحصل على تحديثات مجانية دون أي مخاطر تقريبًا بمجرد تشغيل:

  git submodule update --remote
  npm install

• demo-store-core

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

  ️ يرجى ملاحظة أنه إذا اتبعت هذا المسار وبدأت في الابتعاد كثيرًا عن كود المصدر الأصلي، فمن المحتمل أن تفقد جميع التحديثات المستقبلية أو لن تتمكن من تكرارها.

ابدء

إذا لم تكن لديك خبرة في استخدام Commerce Layer، فيمكنك البدء بإنشاء حساب (إنه مجاني!) واتباع البرنامج التعليمي الخاص بالإعداد.

مهم

يرجى ملاحظة أنه لإعداد متجر تجريبي، فإنك تحتاج إلى مؤسسة تم تكوينها بشكل صحيح مع عدد قليل من المنتجات وسوق واحد على الأقل.

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

إعداد مؤسستك

بمجرد إنشاء المؤسسة، تحتاج إلى إنشاء عميلين لواجهة برمجة التطبيقات: قناة مبيعات وتكامل .

إذا لم تكن قد قمت بذلك بعد، فقم بتثبيت Commerce Layer CLI واثنين من مكوناتها الإضافية: المكون الإضافي للبذور والمكون الإضافي للاستيراد:

npm install -g @commercelayer/cli

commercelayer plugins:install seeder
commercelayer plugins:install imports

يمكنك الآن تسجيل الدخول إلى عميل واجهة برمجة تطبيقات التكامل الخاص بك من واجهة سطر الأوامر:

commercelayer applications:login 
  --clientId Oy5F2TbPYhOZsxy1tQd9ZVZ... 
  --clientSecret 1ZHNJUgn_1lh1mel06gGDqa... 
  --organization my-awesome-organization 
  --alias cli-admin

بناء متجرك

بمجرد إعداد مؤسستك، لإنشاء متجرك، يتعين عليك اتباع بعض الخطوات البسيطة... فلنبدأ!

1. قم بإنشاء مستودع جديد

أيًا كان المسار الذي تختاره، فأنت بحاجة أولاً إلى إنشاء مستودع جديد لمتجرك:

• إذا قررت الاحتفاظ بقالب demo-store فأنت تحتاج فقط إلى النقر فوق "استخدام هذا القالب" من الصفحة الرئيسية للمستودع على GitHub ثم تشغيل:

  git clone < your-repository-url > my-new-project
  cd my-new-project
  git submodule update --init
  npm install
  
  cp ./demo-store-core/packages/website/.env.sample.submodule .env.local
  
  cp -r ./demo-store-core/packages/website/data/json ./data/json

• إذا قررت إنشاء فرع demo-store-core فيمكنك تشغيل هذا بدلاً من ذلك:

  git clone < your-repository-url > my-new-project
  cd my-new-project
  npm install
  
  cp ./packages/website/.env.sample ./packages/website/.env.local

2. قم بتعيين متغيرات البيئة

قم بتحرير .env.local واملأ جميع المعلومات المفقودة:

 # this is the 'sales channel' client id
NEXT_PUBLIC_CL_CLIENT_ID =er34TWFcd24RFI8KJ52Ws6q...

3. قم ببذر البيانات

هذه الخطوة اختيارية. إذا كان لديك بالفعل مؤسسة تم تكوينها بشكل صحيح على حساب Commerce Layer الخاص بك، فيمكنك تخطيها.

سيقوم البرنامج النصي التالي بملء مؤسستك بجميع الموارد التي تحتاجها لإنشاء تجارة إلكترونية متعددة الأسواق باستخدام Commerce Layer (تلك التي نستخدمها في متجرنا التجريبي).

npm run seeder:seed -ws --if-present

إذا تم تنفيذ الأمر أعلاه دون أي أخطاء، فيرجى الانتقال إلى الخطوة 4. وإلا، فلا يزال بإمكانك تزويد مؤسستك بعينة بيانات باستخدام واجهة سطر الأوامر (CLI) عن طريق تشغيل ما يلي:

commercelayer seeder:seed -b custom -n demo_store_full -u ./demo-store-core/packages/setup/

4. اختر البلدان التي ستبيع فيها

يحتوي ملف json/countries.json على قائمة بالبلدان المتاحة للتجارة الإلكترونية الخاصة بك. يمكنك تغييره باستخدام المحرر المفضل لديك. فقط تأكد من استبدال كافة نتائج "market": xxx بالأسواق ذات الصلة بمؤسستك. يمكنك الحصول على قائمة الأسواق الخاصة بك من لوحة تحكم مسؤول Commerce Layer أو عن طريق تشغيل هذا الأمر:

npm run markets -ws --if-present

5. شاهده على أرض الواقع

npm run dev

# http://localhost:3000/ 

إدارة التحديثات

يمكنك دائمًا العثور على أحدث كود demo-store-core في فرعه main .

لتحديث متجرك التجريبي إلى آخر التغييرات، يمكنك ببساطة تشغيل:

git submodule update --remote
npm install

في بعض الأحيان قد يحدث أن يحتوي الإصدار الرئيسي الجديد على تغييرات جذرية. في هذه الحالة، من خلال التحديث إلى الأحدث، قد يتوقف متجرك التجريبي عن العمل وستحتاج إلى حل جميع المشكلات يدويًا باتباع ملاحظات الإصدار.

إذا أردت، يمكنك تلقي إشعار GitHub بمجرد إصدار إصدار جديد.

التخصيص

عندما تستخدم قالب المتجر التجريبي الخاص بنا، يمكنك تخصيص ثلاثة عناصر رئيسية: بيانات المحتوى، والإعدادات المحلية، وملفات التكوين.

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

ملفات بيانات JSON

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

توجد ملفات JSON في data/json/ ، ولكن يمكنك اختيار موضع مختلف عن طريق تغيير متغير البيئة NEXT_PUBLIC_JSON_DATA_FOLDER .

توجد ملفات تعريف النوع في packages/types/src/json/ . نحن نستخدم zod للتحقق من صحة المخطط. قم بإلقاء نظرة على هذه الملفات لفهم البنية التي يجب عليك اتباعها.

عند الانتهاء من جميع التغييرات، يمكنك التحقق مما إذا كان كل شيء صحيحًا عن طريق تشغيل:

 npm run test:data

ملفات البيانات المحلية

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

توجد ملفات Locale JSON في data/locales/ ، ولكن يمكنك اختيار موضع مختلف عن طريق تغيير متغير البيئة NEXT_PUBLIC_LOCALES_DATA_FOLDER .

قم بما يلي لبدء تخصيص اللغات:

cp -r ./demo-store-core/packages/website/data/locales ./data/locales

 # .env.local
NEXT_PUBLIC_LOCALES_DATA_FOLDER =../../../data/locales/

ملفات التكوين

توجد ملفات التكوين في config/ ، ولكن يمكنك اختيار موضع مختلف عن طريق تغيير متغير البيئة NEXT_PUBLIC_CONFIG_FOLDER .

هناك ثلاثة ملفات تكوين يمكنك إدارتها:

• general.config.js
  يحتوي هذا الملف على التكوين العام.

• facets.config.js
  هذا هو ملف تكوين الجوانب. يمكنك اختيار الترتيب الذي يتم عرضها به في لوحة التصفية، ومظهرها، وقواعد فرز قيمها.
  

• variants.config.js
  هذا هو ملف تكوين المتغيرات. يمكنك اختيار الترتيب الذي يتم عرضها به في صفحة تفاصيل المنتج ومظهرها.
  

قم بما يلي لبدء تخصيص التكوين:

cp -r ./demo-store-core/packages/website/config ./config

 # .env.local
NEXT_PUBLIC_CONFIG_FOLDER =../../../config/

متغيرات البيئة الإضافية

هناك بعض متغيرات البيئة التي يمكنك استخدامها لتخصيص متجرك. للحصول على قائمة ووصف شاملين، يمكنك إلقاء نظرة على ملف env.d.ts الإضافي.

نشر

يمكنك نشر المتجر التجريبي في أي مكان تفضله. تحتاج فقط إلى:

1. قم بتعيين كافة متغيرات البيئة في النظام التي ستستخدمها لتشغيل البناء، وفقًا لاحتياجاتك.
2. قرر ما إذا كنت تريد إنشاء موقع ثابت أو العرض من جانب الخادم.

تم تصميم المتجر التجريبي ليكون SSG أولاً وقبل كل شيء، ولكن يمكنك التبديل إلى SSR في لمح البصر. لقد اختبرنا بعض الطرق لنشره (على سبيل المثال باستخدام GitHub Workflow، وNetlify، وVercel، وما إلى ذلك) ويمكنك العثور على مزيد من المعلومات حول هذا الموضوع هنا. إذا قمت بذلك بشكل مختلف أو استخدمت خدمات أخرى وترغب في مشاركة الخطوات مع المجتمع، فيرجى الانضمام إلى المناقشة، وشكرًا مقدمًا!

توليد موقع ثابت

لإنشاء المتجر التجريبي ونشره:

1. قم بتعيين متغير البيئة التالي وفقًا لذلك:

    NEXT_PUBLIC_DATA_FETCHING =ssg

2. قم بتشغيل npm run build لإنشاء بنية إنتاجية مُحسَّنة بشكل ثابت لتطبيقك.

3. انسخ المجلد demo-store-core/packages/website/out إلى الاستضافة الثابتة المفضلة لديك.

التقديم من جانب الخادم

يمكن نشر المتجر التجريبي على أي مزود استضافة يدعم Node.js. للقيام بذلك:

1. قم بتعيين متغير البيئة التالي وفقًا لذلك:

    NEXT_PUBLIC_DATA_FETCHING =ssr

2. قم بتشغيل npm run build لإنشاء نسخة إنتاجية مُحسّنة لتطبيقك.

3. قم بتشغيل npm start لبدء تشغيل خادم Node.js في وضع الإنتاج.

بحاجة الى مساعدة؟

• انضم إلى مجتمع Discord الخاص بطبقة التجارة.
• افتح مناقشة أسئلة وأجوبة جديدة
• اتصل بنا على Bluesky أو ​​X (Twitter سابقًا) أو LinkedIn.
• هل هناك خلل؟ قم بإنشاء مشكلة في هذا المستودع.

استكشاف الأخطاء وإصلاحها

1. س. حتى لو قمت بتغيير NEXT_PUBLIC_JSON_DATA_FOLDER أو NEXT_PUBLIC_LOCALE_DATA_FOLDER أو NEXT_PUBLIC_CONFIG_FOLDER ، فإن موقع الويب لا يزال يشير إلى الملفات السابقة.

   A. يتم استخدام متغيرات البيئة هذه alias في Webpack. بدءًا من Webpack 5، تم تقديم التخزين المؤقت للإصدارات الأسرع. لن يؤدي تغيير متغيرات البيئة هذه إلى إبطال ذاكرة التخزين المؤقت لـ Webpack. يجب عليك إزالة المجلد .next يدويًا أو عن طريق تشغيل:

    # update the path if needed
   rm -rf demo-store-core/packages/website/.next/

رخصة

تم نشر هذا المستودع بموجب ترخيص MIT.