كيف تبني متجرًا إلكترونيًا مع لوحة إدارة باستخدام Next.js

في نهاية هذا الدليل ستعرف كيف تبني متجرًا إلكترونيًا مع لوحة إدارة باستخدام Next.js وNestJS وقالب التجارة الإلكترونية من Aniq UI. ستحصل على واجهة متجر (storefront)، ولوحة طلبات لفريقك، وواجهة API تحفظ الكتالوج والعملاء والطلبات.

نتابع متجرًا تجريبيًا واحدًا من أول خطة حتى يوم الإطلاق. كل خطوة تسمّي الشاشة أو الإعداد المعني، وتستخدم الأوامر ومسارات الملفات الدقيقة من التوثيق. المسار نفسه يناسب مؤسسًا يطلق متجره أو وكالة تبني متجرًا لعميل.

متطلبات المشروع

Cedar & Cloth متجر صغير يبيع قمصان الكتان وحقائب القماش. تديره صاحبته مع شخصين يجهزان الطلبات. هذا ما يحتاجه المتجر:

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

كيف يغطي القالب هذه المتطلبات

الحاجة	أين توجد	ما تستخدمه
كتالوج ثنائي اللغة مع متغيرات	لوحة الإدارة وواجهة API	شاشتا Products وCategories، مع متغيرات المقاس واللون
الشراء كضيف وتتبع الطلب	واجهة المتجر (storefront)	صفحة الدفع وTrack Order التي تطلب رقم الطلب والبريد الإلكتروني
البطاقة أو الدفع عند الاستلام	واجهة المتجر وواجهة API	Stripe للبطاقات، والدفع عند الاستلام محدد افتراضيًا
قاعدة الشحن	واجهة المتجر وواجهة API	ملف إعدادات الشحن وخدمة الطلبات، ويجب أن يبقيا متطابقين
لوحة الطلبات والصلاحيات	لوحة الإدارة	Orders وAdmin Management وAdmin Roles
صفحة رئيسية قابلة للتعديل	لوحة الإدارة	شاشة Home Page، قسمًا بعد قسم
صور المنتجات	لوحة الإدارة	استوديو الذكاء الاصطناعي في نموذج المنتج وإزالة الخلفية
تحليلات الزوار	واجهة المتجر (storefront)	معرّفات الوسوم تُلصق في ملف البيئة الخاص بواجهة المتجر

قبل أن تبدأ: قرارات عليك اتخاذها

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

ماذا تبيع بالضبط؟

عدّ منتجاتك، وحدد لكل منتج الخيارات التي يختارها المشتري: المقاس أو اللون أو لا شيء. لكل متغير رمز SKU وتعديل سعر ومخزون خاص به، لذلك شكل كتالوجك يحدد حجم إدخال البيانات المطلوب. يبيع Cedar & Cloth قمصانًا بعدة مقاسات وألوان، وحقائب بمقاس واحد.

بأي لغات ستبيع؟

الإنجليزية والعربية جاهزتان، مع تخطيط من اليمين إلى اليسار. تحمل المنتجات والتصنيفات اسمًا ووصفًا بكلتا اللغتين. لغة ثالثة ممكنة للواجهة، لكنها تتطلب تعديلات في عدة ملفات.

كيف سيدفع المشترون؟

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

ماذا عن الشحن والضرائب؟

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

ضيوف أم حسابات أم كلاهما؟

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

من يتولى البريد الإلكتروني؟

القالب لا يرسل أي بريد: لا تأكيدات ولا إشعارات شحن ولا إعادة تعيين كلمة المرور. اختر مزود بريد مبكرًا، لأن العملاء يتوقعون على الأقل تأكيدًا للطلب.

أي أدوات ذكاء اصطناعي، إن وُجدت؟

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

خطوة بخطوة

الخطوة 1: اختر الحزمة

للقالب أربع حزم: Full Stack (واجهة المتجر والإدارة وواجهة API)، وStorefront وحدها، وAdmin Dashboard وحدها، وBackend API وحدها. يمكن لكل من الواجهتين الأماميتين أن تعمل بمفردها على متجر تجريبي مدمج داخل المتصفح. هذا مفيد لمراجعة التصميم، لكن الطلبات الحقيقية والمدفوعات وميزات الذكاء الاصطناعي تحتاج إلى واجهة NestJS API.

يختار Cedar & Cloth حزمة Full Stack. الرخصة التجارية تغطي عددًا غير محدود من المشاريع، بما فيها المتاجر التي تبنيها وتسلّمها لعميل.

تعرض صفحة My templates ملف ZIP لكل حزمة، فاختر الحزمة التي اشتريتها.

ما يجب التحقق منه: يُستخرج ملف Full Stack ZIP إلى المجلد e-commerce-1، وهو يحتوي على admin-dashboard وback-end وstorefront وdocker-compose.yml. أما الحزم ذات التطبيق الواحد فتُستخرج إلى مجلدها الخاص مع Dockerfile وpackage.json و.env.example.

الخطوة 2: شغّله محليًا باستخدام Docker

نزّل ملف ZIP من My templates، وفك ضغطه، وافتح الطرفية داخل المجلد e-commerce-1. شغّل Docker ثم نفّذ:

docker compose up --build

يبني Docker ثلاث صور في أول تشغيل ويحمّل متجرًا تجريبيًا في قاعدة البيانات، لذلك توقع أن يستغرق ذلك بضع دقائق. تفتح واجهة المتجر على localhost:3030، ولوحة الإدارة على localhost:3031، وواجهة API على localhost:8000. يمكن نقل منفذ مشغول عبر SITE_PORT أو ADMIN_PORT أو API_PORT في ملف .env بجانب docker-compose.yml.

سجّل الدخول إلى لوحة الإدارة بصفتك Super Admin (admin@example.com، وكلمة المرور Admin@123)، وإلى واجهة المتجر بصفتك عميلًا تجريبيًا (john.doe@example.com، وكلمة المرور password123). حساب موظف للقراءة فقط، john.smith@admin.com مع admin123، يريك ما يراه دور Viewer. أنشئ طلب اختبار بصفتك العميل، ثم ابحث عنه في لوحة الإدارة.

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

تُظهر هذه اللقطة طرفية مفتوحة داخل المجلد المستخرج، وهو المكان الذي يجب تنفيذ كل أمر فيه.

انتظر أن تجتاز واجهة API فحص الجاهزية، لأن الواجهتين الأماميتين لا تبدآن إلا بعدها.

يبدأ مسار Node.js بواجهة API، بعد أن ينشئ الـ seed قاعدة البيانات والمتجر التجريبي.

تعمل لوحة الإدارة في طرفية خاصة بها على المنفذ 3031، بجانب واجهة المتجر على 3030.

اللقطة أعلاه هي نظرة لوحة الإدارة العامة التي يجب أن تراها بعد تسجيل الدخول بصفتك Super Admin.

ما يجب التحقق منه: افتح localhost:8000/api/health، ويجب أن يرد بحالة ok. ثم أضف منتجًا إلى السلة بصفتك العميل التجريبي، وأتمم الشراء كضيف، وابحث عن الطلب في لوحة الإدارة.

ما الذي يسوء عادة:

• Docker لا يعمل، أو أن المنفذ 3030 أو 3031 أو 8000 مشغول. حرّره، أو اضبط SITE_PORT أو ADMIN_PORT أو API_PORT على رقم فارغ.
• يبدو أن التشغيل الأول متوقف. إنه يحمّل بيانات المتجر التجريبي، ولا تبدأ الواجهتان الأماميتان إلا عندما تصبح واجهة API سليمة.
• يظهر تنبيه "Sample data". بُنيت الواجهة الأمامية دون عنوان API وتعمل على متجرها التجريبي الخاص.
• يعرض Yarn الإصدار 1.22. نفّذ corepack enable ثم ثبّت من جديد.

الخطوة 3: حوّله إلى Cedar & Cloth

الهوية التجارية موجودة في ملفات، وتحتفظ واجهة المتجر ولوحة الإدارة كل منهما بنسختها. في واجهة المتجر، يحتوي src/config/brand.config.ts على اسم المتجر (يأتي كشعار نصي)، واسم تبويب المتصفح، وبيانات الاتصال، وروابط التواصل الاجتماعي، لكل منها قيم بالإنجليزية والعربية. اضبط NEXT_PUBLIC_SITE_URL على نطاقك الحقيقي، لأن الروابط الأساسية (canonical) وخريطة الموقع وبطاقات المشاركة تستخدمه.

النصوص المرفقة تصف متجر أزياء رجالية. ثلاثة أماكن تحمل هذه النصوص: كتل النص في brand.config.ts، والمجلد messages/home/ للصفحة الرئيسية، وmessages/seo/ لعناوين الصفحات. يبيع Cedar & Cloth أزياء رجالية أيضًا، لذلك يعدّل أقل مما تعدّله معظم المتاجر.

يحتفظ كل تطبيق بألوانه في src/styles/theme-variables.css كمتغيرات CSS، مع كتلة للسمة الفاتحة وأخرى للداكنة. لون التمييز هو --primaryColor. تحمّل واجهة المتجر خط Plus Jakarta Sans للنص اللاتيني وخطين عربيين. أما لوحة الإدارة فلها ملف هوية خاص بها وتستخدم خطوط النظام.

ما يجب التحقق منه: أعد البناء، ثم ابحث عن الاسم القديم في تبويب المتصفح وتذييل الصفحة ومعاينة المشاركة والصفحات العربية. استبدل بيانات الاتصال المؤقتة، لأنها تأتي كبيانات نموذجية.

ما الذي يسوء عادة: لا يعرض التذييل أيقونات التواصل الاجتماعي، لأن الروابط تأتي فارغة ولا تظهر إلا المعبّأة. وحالة أخرى هي صورة مشاركة ما زالت تعرض صورة القالب الرئيسية. وجّه meta.ogImage إلى صورتك الخاصة.

الخطوة 4: أضف التصنيفات والمنتجات

ابدأ بالتصنيفات: اسم ووصف بكلتا اللغتين، مع صورة وslug وموضع ترتيب ومفتاح تشغيل وإيقاف. وهي بمستوى واحد مسطح. ثم أضف المنتجات. يتضمن المنتج:

• اسمًا وأوصافًا بكلتا اللغتين (الاسم الإنجليزي وحده إلزامي)، وslug ورمز SKU وتصنيفًا.
• سعرًا، وسعر مقارنة اختياريًا، وسعر التكلفة، وكمية المخزون.
• حتى 12 صورة وفيديو بأي ترتيب، أحدها محدد كأساسي، ولكل منها نص بديل.
• متغيرات مثل Size مع M، أو Colour مع رمزه السداسي. لكل متغير رمز SKU وتعديل سعر ومخزون خاص به.
• علامات للمنتج النشط والمميز والأكثر مبيعًا، ووسوم حرة.

تذهب الملفات المرفوعة إلى حاوية Cloudflare R2، أو إلى تخزين آخر متوافق مع S3، وتفشل برمز 503 إلى أن تملأ متغيرات R2_* الخمسة في back-end/.env. أما الكتالوج التجريبي فيُعرض من ملفات مضمّنة، لذلك يمكنك بناء المسار كله قبل أن تضبط الحاوية.

اعمل بهذا الترتيب حتى لا يشير شيء إلى ما لم يُنشأ بعد:

1. أنشئ التصنيفات أولًا، لأن كل منتج يحتاج إلى تصنيف.
2. أضف منتجًا واحدًا كاملًا، بصوره ومتغيراته وبكلتا اللغتين، قبل أن تضيف الباقي.
3. افتحه في واجهة المتجر بالإنجليزية والعربية وتحقق من المعرض ومحدد المتغيرات والسعر.
4. بعد ذلك فقط كرر العملية مع بقية المنتجات.

انظر إلى القائمة المسطحة للتصنيفات مع ترتيبها ومفتاح التفعيل: الترتيب هنا يحدد صف التصنيفات في الصفحة الرئيسية.

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

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

ما الذي يسوء عادة: تفشل عمليات الرفع برمز 503 لأن متغيرات الحاوية غير مضبوطة. أو تُحمّل الصور بحجمها الكامل لأن الواجهتين الأماميتين لم تعرفا المضيف العام لحاويتك. اضبط NEXT_PUBLIC_MEDIA_HOSTNAME على ذلك المضيف دون https://، وأعد البناء.

الخطوة 5: رتّب الصفحة الرئيسية

تحدد شاشة Home Page في لوحة الإدارة، قسمًا بعد قسم، ما يراه المتسوقون في الصفحة الأولى لواجهة المتجر. تحتاج التصنيفات إلى ترتيب فقط. أما بقية الأقسام فتقبل عددًا محدودًا من المنتجات أو النصوص: حتى 3 ركائز أسلوب، و2 من اللوحات التحريرية، و6 إصدارات جديدة، و8 من الأكثر مبيعًا، و6 عناصر مميزة، و5 شرائح في السلايدر الختامي. إذا كان قسم New drops فارغًا فإنه يعرض أحدث المنتجات. وتعديل أي قسم يتطلب صلاحية products.edit.

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

ما الذي يسوء عادة: لا يظهر التغيير لأنك لا تملك صلاحية products.edit، أو لأن واجهة المتجر تعمل على متجرها التجريبي ولا تقرأ من واجهة API.

الخطوة 6: اضبط الشحن والمدفوعات ودورة الطلب

تقدم صفحة الدفع البطاقة عبر Stripe والدفع عند الاستلام. الدفع عند الاستلام محدد افتراضيًا، وتحسب واجهة API سعر الطلب دائمًا من كتالوجها الخاص، ولا تعتمد أبدًا على أرقام يرسلها المتصفح. لا يوجد خيار PayPal.

تأتي قاعدة الشحن هكذا: مجاني من $75، و$9.99 دون ذلك، دون ضريبة. وهي مكتوبة في موضعين، storefront/src/config/shipping.ts وback-end/src/modules/orders/orders.service.ts. عدّل الاثنين في تغيير واحد، وإلا اختلف مبلغ السلة عن المبلغ المحصّل.

لقبول البطاقات، استخدم مفاتيح الاختبار من Stripe أولًا:

1. أضف STRIPE_SECRET_KEY وSTRIPE_WEBHOOK_SECRET معًا إلى back-end/.env.
2. ضع NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY في ملف .env الخاص بواجهة المتجر وأعد البناء.
3. في لوحة Stripe، أنشئ نقطة webhook تشير إلى عنوان واجهة API متبوعًا بـ /api/payments/webhook، واجعلها تستمع إلى حدثين: payment_intent.succeeded وpayment_intent.payment_failed.

يبقى الطلب المدفوع بالبطاقة قيد الانتظار إلى أن تستدعي Stripe هذه الـ webhook، ثم يصبح مدفوعًا ومؤكدًا. وللاختبار المحلي، يمكن لأداة Stripe CLI تمرير الأحداث إلى http://localhost:8000/api/payments/webhook. في لوحة الإدارة ينتقل الطلب خطوة واحدة كل مرة: pending ثم confirmed ثم processing ثم shipped ثم delivered، أو cancelled قبل إغلاقه. أضف رقم التتبع عند الشحن، ونزّل أي طلب كملف CSV.

ما يجب التحقق منه: أنشئ طلبًا بالدفع عند الاستلام وطلبًا بالبطاقة بمفاتيح اختبار Stripe. يجب أن يكون الأول مؤكدًا وغير مدفوع. ويجب أن يبقى الثاني قيد الانتظار حتى تصل الـ webhook، ثم يصبح مدفوعًا ومؤكدًا. اجعل بطاقة تفشل عمدًا وتأكد أن الطلب يُعلَّم كفاشل.

ما الذي يسوء عادة:

• خيار البطاقة غير موجود في صفحة الدفع. المفتاح العام فارغ أو ليس مفتاح اختبار أو إنتاج حقيقيًا، فيبقى الدفع عند الاستلام الخيار الوحيد.
• تبقى طلبات البطاقة قيد الانتظار. نقطة الـ webhook أو سرّ التوقيع الخاص بها خاطئ.
• ما زالت واجهة المتجر تعرض المفتاح العام القديم. هو مضمّن وقت البناء، فأعد البناء بعد تغييره.

الخطوة 7: أضف الموظفين واضبط صلاحياتهم

حسابات الموظفين في Admin Management، وصلاحياتهم في Admin Roles. يعطيك الـ seed دور Super Admin بكل الصلاحيات، ودور Viewer بكل صلاحيات العرض ما عدا مساعد الذكاء الاصطناعي. أدوار Admin وManager وEditor موجودة لكنها تبدأ بلا صلاحيات، لذلك فعّل صلاحياتها قبل أن تمنحها لأي شخص.

يُبقي Cedar & Cloth صاحبة المتجر بدور Super Admin. وللشخصين اللذين يجهزان الطلبات يمنح صلاحية عرض الطلبات، إضافة إلى صلاحية التعديل اللازمة لنقل الطلب خطوة إلى الأمام. وكل شيء آخر يبقى مخفيًا عنهما، لأن الشريط الجانبي وواجهة API يتحققان من أسماء الصلاحيات نفسها.

ما يجب التحقق منه: سجّل الدخول بحساب Viewer وتأكد أنه يرى القوائم ولا يغيّرها. ثم سجّل الدخول بدور مجهّز الطلبات الذي أنشأته وتأكد أن نقل الطلب إلى الأمام يعمل.

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

الخطوة 8: أضف أدوات الذكاء الاصطناعي التي تريدها

تعمل كل ميزة ذكاء اصطناعي فقط عندما يوجد مفتاحها في back-end/.env، ويُعدّ المفتاح الذي ما زال يحمل قيمته النموذجية غير مضبوط.

• مساعد الإدارة: يحتاج إلى مفتاح Google Gemini. يجيب عن أسئلة حول المتجر، ويبحث عن الطلبات، ويعدّل المنتجات والمخزون، ويرسم مخططات المبيعات، وكل ذلك ضمن صلاحيات المسؤول المسجّل.
• استوديو المنتجات بالذكاء الاصطناعي: داخل نموذج المنتج. يحتاج وضع المساعد فيه إلى مفتاح Gemini وحاوية الوسائط. ويحتاج وضع Animate إلى مفتاح وسرّ من Higgsfield.
• غرفة القياس: تتيح للمتسوقين رؤية المنتج على عارضة أو على صورتهم الخاصة. تحتاج إلى مفتاح Gemini والحاوية.
• إزالة الخلفية: تحتاج إلى ملف نموذج على خادمك الخاص وإلى الحاوية، لكن دون مفتاح، ولا تكلف شيئًا عن كل صورة.

يفعّل Cedar & Cloth إزالة الخلفية فقط، لتتحول صور الهاتف إلى صور كتالوج نظيفة. صورة Docker تترك النموذج خارجها ما لم تطلبه عند البناء. ورسوم المزودين على الميزات ذات المفاتيح تقع عليك.

ما يجب التحقق منه: افتح صفحة AI Assistant واطلب ملخصًا للمبيعات. تأكد أن الإجابة تأتي مع مخطط مرسوم من بياناتك. وبالنسبة لإزالة الخلفية، افتح صورة منتج وتأكد من ظهور زر Remove background.

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

الخطوة 9: اربط التحليلات

ست شبكات إعلانات وتحليلات مدمجة في واجهة المتجر. الصق المعرّف في storefront/.env وأعد البناء. المعرّف الفارغ لا يحمّل أي سكربت. المتغيرات هي NEXT_PUBLIC_GTM_ID وNEXT_PUBLIC_GA4_MEASUREMENT_ID وNEXT_PUBLIC_META_PIXEL_ID وNEXT_PUBLIC_TIKTOK_PIXEL_ID وNEXT_PUBLIC_SNAPCHAT_PIXEL_ID وNEXT_PUBLIC_PINTEREST_TAG_ID.

إذا ضبطت واحدًا فقط، فليكن Google Tag Manager، لأنه يستطيع تحميل البقية بنفسه. وإذا كان GA4 يعمل أصلًا داخل حاوية Tag Manager لديك، فاترك متغير GA4 فارغًا، وإلا حُسبت كل جلسة مرتين. تسجّل واجهة المتجر مشاهدات الصفحات ومشاهدات المنتجات والإضافة إلى السلة وبدء الدفع والشراء والبحث والتسجيل. اضبط NEXT_PUBLIC_ANALYTICS_DEBUG=true لتسجيل كل حدث في وحدة تحكم المتصفح أثناء الاختبار.

تُحمَّل الوسوم بمجرد تحميل الصفحة. إذا كنت تبيع في الاتحاد الأوروبي أو المملكة المتحدة، فأظهر شريط موافقة قبل تشغيلها.

ما يجب التحقق منه: شغّل تسجيل التصحيح، وأتمم عملية شراء، وراقب الأحداث وهي تظهر في وحدة تحكم المتصفح بالترتيب: مشاهدة المنتج، الإضافة إلى السلة، بدء الدفع، الشراء. ثم تأكد من الأحداث نفسها في معاينة Tag Manager أو في أداة التحليلات لديك.

ما الذي يسوء عادة: تغيير المعرّف لا يؤثر، لأن المعرّفات مضمّنة وقت البناء وتحتاج إلى إعادة بناء. أو يُرسل حدث الشراء دون العملة الصحيحة. اضبط NEXT_PUBLIC_ANALYTICS_CURRENCY إذا كنت لا تبيع بالدولار الأمريكي.

الخطوة 10: انطلق للإنتاج

سدّ الثغرات التي يتركها القالب مفتوحة، ثم انشر:

• لا يرسل أي بريد إلكتروني: لا تأكيد طلب ولا إشعار شحن ولا إعادة تعيين كلمة المرور. اربط مزود بريد في الدالة forgotPassword داخل back-end/src/modules/customer-auth/customer-auth.controller.ts وللطلبات.
• نموذج الاتصال والاشتراك في النشرة يؤكدان للزائر لكنهما لا يسلّمان شيئًا، ولا تأتي مع القالب صفحات للشروط أو الخصوصية. اربط النماذج واكتب الصفحات.

ثم اضبط واجهة API في back-end/.env: قيمة جديدة لـ JWT_SECRET (تُنشأ بالأمر node -e "console.log(require('crypto').randomBytes(48).toString('hex'))")، وNODE_ENV=production، وCORS_ORIGIN يضم عنواني واجهة المتجر ولوحة الإدارة، وFRONTEND_URL بعنوان لوحة الإدارة. ابنِ واجهة API، ونفّذ yarn db:sync:prod مرة واحدة لإنشاء الجداول، ثم شغّلها. في كل واجهة أمامية اضبط NEXT_PUBLIC_API_BASE_URL مع /api في آخره وأعد البناء. واضبط NEXT_PUBLIC_STOREFRONT_URL في لوحة الإدارة ليعمل رابط Go to storefront فيها.

لا تستخدم yarn railway:setup لمتجر حقيقي: فهو يحذف كل الجداول في كل مرة يعمل فيها. غيّر كلمات المرور التجريبية المنشورة، أو ابدأ بجداول فارغة.

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

ما الذي يسوء عادة:

• واجهة API تحجب المتصفحات. يجب أن يضم CORS_ORIGIN الواجهتين الأماميتين تمامًا كما يعرضهما المتصفح.
• يحصل الجميع على "Too many attempts" خلف وكيل (proxy). كل مسار من هذه المسارات (تسجيل الدخول والتسجيل وإعادة تعيين كلمة المرور وتتبع الضيف) يقبل عشرة طلبات في الدقيقة من عنوان واحد. اضبط TRUST_PROXY على عدد الوكلاء الموجودين أمامه.
• إعادة تعيين كلمة المرور لا تصل إلى أي مكان. في الإنتاج لا يُسلَّم رمز إعادة التعيين حتى تربط مزود بريد.

التشغيل اليومي

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

بدء اليوم من النظرة العامة

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

انظر إلى آخر الطلبات وإلى الجرس في الشريط العلوي، فهناك يظهر النشاط الجديد أولًا.

تحريك الطلبات إلى الأمام

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

يُظهر تقدم التجهيز في كل صف إلى أي مدى وصل الطلب، حتى يتمكن المجهزون من تمييز ما ما زال ينتظر.

مساعدة عميل

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

استخدم هذه القائمة للعثور على عميل من حسابه وفتح سجله عندما يراسلك.

إبقاء واجهة المتجر متجددة

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

الإعدادات قيم محفوظة

يحتوي تبويب App settings على أزواج مفتاح وقيمة، منها إعدادات الدفع والبريد والإعدادات العامة. واجهة المتجر وواجهة API المرفقتان لا تقرآنها بعد، لذلك لا يغيّر تعديل أي منها شيئًا حتى يقرأه كودك الخاص.

مثال على خطة إطلاق أسبوعًا بعد أسبوع

هذا الجدول مثال لـ Cedar & Cloth وليس وعدًا بالمدة التي سيستغرقها إطلاقك.

• الأسبوع 1، الفهم. شغّل المنظومة، وأنشئ طلب اختبار، واحسم قائمة القرارات.
• الأسبوع 2، الهوية والكتالوج. غيّر هوية التطبيقين، وأعد كتابة النصوص المرفقة، وأضف التصنيفات ومنتجًا واحدًا كاملًا.
• الأسبوع 3، بقية المتجر. أضف بقية المنتجات، ورتّب الصفحة الرئيسية، وجهّز تخزين الحاوية والصور.
• الأسبوع 4، المال والموظفون. اضبط قاعدة الشحن، واربط Stripe في وضع الاختبار، وأنشئ أدوار المجهزين، ومرّر الطلبات عبر كل الحالات.
• الأسبوع 5، الإنتاج. جهّز الاستضافة وملفات البيئة والجداول. اربط مزود بريد، وأضف وسوم التتبع، واكتب صفحات الشروط والخصوصية الناقصة.
• الأسبوع 6، إطلاق تجريبي. ابدأ بجمهور صغير، ثم انتقل إلى مفاتيح Stripe الحية عندما تكون متأكدًا.

قائمة التحقق قبل الإطلاق

• استبدال اسم المتجر والشعارات والأيقونات والألوان والخطوط في التطبيقين.
• إعادة كتابة نصوص الأزياء الرجالية المرفقة في ملف الهوية ورسائل الصفحة الرئيسية ورسائل SEO.
• استبدال بيانات الاتصال وروابط التواصل الاجتماعي وصور المشاركة.
• تصنيفات ومنتجات مكتملة بكلتا اللغتين، مع المتغيرات والصور.
• تغيير قاعدة الشحن في الملفين، إذا غيّرتها أصلًا.
• مفاتيح Stripe الحية والـ webhook الحية في مكانها، بعد تجربة كاملة في وضع الاختبار.
• تفعيل أدوار كل موظف، وتغيير كلمات المرور التجريبية.
• ضبط JWT_SECRET وCORS_ORIGIN وFRONTEND_URL وعنواني API في الواجهتين الأماميتين للإنتاج.
• ضبط NEXT_PUBLIC_SITE_URL على النطاق الحقيقي.
• ربط مزود بريد، وربط نموذج الاتصال ونموذج النشرة.
• كتابة صفحات الشروط والخصوصية.
• لصق معرّفات التتبع، وإضافة شريط موافقة إذا كنت تبيع في الاتحاد الأوروبي أو المملكة المتحدة.
• ترك التعبئة التلقائية لصفحة الدفع التجريبية متوقفة.
• جدولة نسخ احتياطية لقاعدة البيانات ولحاوية الوسائط.

قالب جاهز، أم بناء من الصفر، أم منشئ متاجر مستضاف

منشئ متاجر مستضاف

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

البناء من الصفر

تحصل على ما تصممه بالضبط. لكن عليك أيضًا أن تبني كتالوجًا بمتغيرات، وسلالًا، والشراء كضيف، وتتبع الطلبات، والمدفوعات والـ webhooks، وحسابات للعملاء والموظفين، وصلاحيات، ولوحة إدارة، ولغتين، وواجهة API قبل أول طلب. وتتولى صيانة كل ذلك.

البدء من قالب

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

كم تكلف التشغيل

تبدأ حزم القالب من $79، وحزمة Full Stack التي يستخدمها Cedar & Cloth بسعر $179. وهي تشمل رخصة تجارية ودعمًا مدى الحياة. وبعد ذلك تدفع مقابل ما تفعّله:

• استضافة واجهة المتجر ولوحة الإدارة وواجهة API، وقاعدة بيانات إذا تجاوزت SQLite.
• رسوم معالجة Stripe، المذكورة في صفحة أسعار Stripe. الدفع عند الاستلام لا يحتاج إلى معالج دفع.
• حاوية مثل Cloudflare R2 لصور المنتجات.
• مفتاح Google Gemini للمساعد أو الاستوديو أو غرفة القياس، تحاسبك عليه Google، وحساب Higgsfield للفيديو.
• مزود بريد إلكتروني ونطاق.

الأجزاء المجانية: SQLite للعمل المحلي، والمتجر التجريبي، والدفع عند الاستلام، وإزالة الخلفية على خادمك الخاص.

ما الذي تخصصه بعد ذلك

• النصوص والصور. استبدل رسائل الصفحة الرئيسية وعناوين الصفحات بكلتا اللغتين.
• قواعد الشحن. غيّر حد الشحن المجاني أو الرسوم في الملفين معًا.
• شبكة تتبع أخرى. تُضبط الوسوم التسويقية في src/config/analytics.config.ts، ويصف القالب إضافة وسم آخر كمهمة في ملف واحد.
• بطاقات نظرة لوحة الإدارة. اربط بطاقتي الإيرادات والتحويل التجريبيتين بأرقامك الخاصة.
• الأدوار. أنشئ دورًا لكل شخص في الفريق.
• لغة ثالثة. أضفها إلى الواجهتين الأماميتين وواجهة API. تحمل المنتجات لغتين، الإنجليزية والعربية.

أخطاء شائعة

طلبات البطاقة التي تبقى قيد الانتظار

لا يتحول الطلب إلى مدفوع إلا بعد أن تصل webhook من Stripe إلى واجهة API لديك؛ وعودة المشتري إلى الموقع لا تفعل ذلك. تحقق من عنوان النقطة، والحدثين المشترك بهما، وسرّ التوقيع.

تغيير قاعدة الشحن في موضع واحد فقط

يجب أن تتطابق السلة وملخص الدفع وواجهة API. عدّل إعدادات واجهة المتجر وخدمة الطلبات في التغيير نفسه.

ترك الواجهتين الأماميتين على المتجر التجريبي

بدون NEXT_PUBLIC_API_BASE_URL، تجيب كل واجهة أمامية ببيانات تجريبية داخل المتصفح، وتعرض تنبيهًا، ولا تحصّل من أحد. اضبط العنوان وأعد البناء.

احتساب كل جلسة في GA4 مرتين

إذا كان GA4 يُحمَّل من Tag Manager، فاترك متغير GA4 في القالب فارغًا.

إعطاء دور فارغ

تبدأ أدوار Admin وManager وEditor بلا صلاحيات. الموظف الذي يحصل على أحدها لا يرى تقريبًا أي شيء إلى أن تفعّل ما يحتاجه.

الأسئلة الشائعة

كيف أبني متجرًا إلكترونيًا مع لوحة إدارة في Next.js؟

استخدم قالبًا يضم واجهة المتجر ولوحة الإدارة وواجهة API في مشروع واحد، ثم غيّر الهوية والكتالوج. هذا القالب يعطيك الثلاثة، مع seeder يملأ قاعدة البيانات بمتجر تجريبي بأمر واحد.

هل يمكنني استخدامه للعملاء؟

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

هل يدعم العربية وRTL؟

نعم. تأتي واجهة المتجر ولوحة الإدارة وواجهة API بالإنجليزية والعربية، مع تخطيط العربية من اليمين إلى اليسار. وتُحفظ المنتجات والتصنيفات بكلتا اللغتين.

هل أحتاج إلى backend؟

للطلبات الحقيقية، نعم. تعمل الواجهتان الأماميتان بمفردهما على متجر تجريبي، لكن الطلبات الحقيقية والمدفوعات وميزات الذكاء الاصطناعي تعتمد على واجهة NestJS API، وهي مرفقة مع حزمتي Full Stack وBackend API.

هل يدعم الشراء كضيف؟

نعم. يشتري الضيوف ببريد إلكتروني ويتتبعون الطلب برقم الطلب والبريد، دون حساب.

ما طرق الدفع المتاحة؟

تعمل مدفوعات البطاقات عبر Stripe، ويمكن للمشترين أيضًا اختيار الدفع عند الاستلام. لا يُعرض PayPal في صفحة الدفع.

ما قاعدة البيانات التي يستخدمها؟

SQLite للعمل المحلي وMySQL بالإعداد، دون تغيير في الكود.

هل يتعامل مع الضرائب؟

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

هل يمكن للعملاء الدفع بعملات أخرى؟

تُحصَّل مدفوعات البطاقات بالدولار الأمريكي. البيع بعملة أخرى يعني تغيير ذلك في الكود، وعملة التتبع إعداد منفصل.

ماذا يحدث عند رفض البطاقة؟

يُعلَّم الطلب كفاشل عندما تبلغ Stripe عن فشل الدفع. ويبقى الدفع عند الاستلام متاحًا لذلك العميل.

جرّبه بنفسك

افتح العرض التجريبي لواجهة المتجر والعرض التجريبي للوحة الإدارة. ثم اقرأ التوثيق أو زر صفحة قالب التجارة الإلكترونية. تجد خيارات أخرى في فئة قوالب التجارة الإلكترونية وفي دليل قوالب التجارة الإلكترونية Next.js.

قالب التجارة الإلكترونية هو أيضًا واحد من القوالب العشرة في Next.js Templates Bundle.