المتجر

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

لحزمة الحزمة الكاملة

الصفحات

كل صفحة موجودة بالإنجليزية تحت /en وبالعربية تحت /ar. المسار الذي لا يتضمن لغة يذهب إلى /en.

المسار	ما تعرضه
`/en`	الصفحة الرئيسية: الواجهة الرئيسية، والفئات، والمنتجات الجديدة، ولافتة عرض، والأكثر مبيعًا، وأقسام تحريرية.
`/en/shop`	كل المنتجات، مع البحث وفلاتر الفئة والسعر والتمييز، والترتيب والصفحات. الفلاتر محفوظة في العنوان، فيمكن مشاركة كل عرض.
`/en/categories`	الفئات، مع البحث والترتيب.
`/en/products/<slug>`	منتج: معرض الصور، والخيارات، والسعر، والتقييم، والمراجعات، والمنتجات ذات الصلة، وزرّا المفضلة وغرفة القياس.
`/en/cart`	السلة وملخصها.
`/en/checkout`	بيانات الشحن والدفع في صفحة واحدة، بجوار ملخص الطلب. متاحة للضيوف.
`/en/order-confirmation/<number>`	رقم الطلب الذي تحتفظ به للتتبّع، مع روابط لمتابعة التسوّق ولتتبّع الطلب.
`/en/track-order`	تتبّع الطلب برقم الطلب والبريد الإلكتروني، دون حساب.
`/en/about`, `/en/contact`, `/en/faq`	صفحات الدعم.
`/en/auth/login`, `/en/auth/register`, `/en/auth/forgot-password`, `/en/auth/reset-password`	تسجيل الدخول وإنشاء الحساب. يُعاد توجيه العميل المسجَّل دخوله بعيدًا عنهما.
`/en/account`	المنطقة الخاصة بالعميل المسجَّل: نظرة عامة، والطلبات وتفاصيلها، والعناوين، والملف الشخصي، وتتبّع الطلب، والمفضلة. الزائر غير المسجَّل دخوله يُوجَّه إلى صفحة تسجيل الدخول.

يُعيد /en/wishlist التوجيه إلى /en/account/wishlist.

اربط هذه قبل الإطلاق

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

السلة والمفضلة

تُحفظ السلة والمفضلة في متصفح المتسوّق، للضيوف والعملاء المسجّلين على حد سواء، فتبقيان بعد إعادة تحميل الصفحة وعند العودة لاحقًا على الجهاز نفسه.
يستطيع أي شخص الإضافة إلى المفضلة من بطاقة المنتج أو صفحته. أما صفحة المفضلة نفسها فموجودة في منطقة الحساب، لذا يحتاج عرضها إلى تسجيل الدخول.
تعرض السلة المجموع الفرعي، والشحن (مجاني ابتداءً من 75 دولارًا، وإلا 9.99 دولار)، والإجمالي. تعيد واجهة API تسعير كل طلب من الكتالوج الخاص بها عند إنشائه، بقاعدة الشحن نفسها، ولا تنتقل السلة مع المتسوّق إلى جهاز آخر.

إتمام الشراء

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

الدفع عند الاستلام هو الخيار المحدد افتراضيًا، ويؤكد الطلب فورًا.
البطاقة تعمل عبر Stripe، داخل الصفحة. تحتاج إلى المفتاح القابل للنشر في المتجر، والمفتاح السري والـ webhook في واجهة API.
يعرض الملخص رسوم الشحن التي تحصّلها واجهة API، مجانًا ابتداءً من 75 دولارًا وإلا 9.99 دولار، دون ضريبة.
لا يوجد حقل لرمز الخصم.
يملأ NEXT_PUBLIC_DEMO_CHECKOUT=true الصفحة مسبقًا ببيانات مشترٍ مولَّد، ويضيف زرًا بجوار عنوان الشحن يولّد مشتريًا جديدًا. أبقِه false لمتجر حقيقي.

المدفوعات

حسابات العملاء

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

البريد الإلكتروني يحتاج إلى خدمة الإرسال الخاصة بك

لا يرسل القالب أي بريد إلكتروني: لا تأكيد للطلب، ولا إشعار بالشحن، ولا رسالة لإعادة تعيين كلمة المرور. خارج بيئة الإنتاج تكتب واجهة API رمز إعادة التعيين في سجلها، وتُفتح صفحة إعادة التعيين على /en/auth/reset-password?token= متبوعًا بذلك الرمز. ومع NODE_ENV=production لا يذهب الرمز إلى أي مكان حتى تربط مزوّد بريد في forgotPassword، داخل back-end/src/modules/customer-auth/customer-auth.controller.ts.

التقييمات

تعرض كل صفحة منتج تقييماته وملخصًا للتقييم. التقييم الصادر من عميل اشترى المنتج يحمل شارة «شراء موثّق».
لا يستطيع المتسوّقون كتابة تقييم: لا يوجد نموذج لذلك في المتجر ولا في لوحة الإدارة، لذا فالتقييمات التجريبية هي ما يعرضه المتجر.
تقبل واجهة API التقييمات من العملاء المسجّلين على POST /api/reviews، تقييمًا واحدًا لكل عميل لكل منتج: الإرسال مرة أخرى يحدّث التقييم الأول.

تتبّع الطلبات

تطلب صفحة /en/track-order رقم الطلب والبريد الإلكتروني الذي أُنشئ به الطلب، فلا يكشف الرقم المخمَّن شيئًا. الرابط الذي يتضمن ?order= يملأ الرقم تلقائيًا. ويتتبّع العملاء المسجّلون طلباتهم من حساباتهم برقم الطلب وحده.

يسمح البحث بـ 10 محاولات في الدقيقة من العنوان الواحد.

غرفة القياس

عندما تكون غرفة القياس مفعّلة في واجهة API، يستطيع المتسوّقون رؤية المنتج ملبوسًا قبل شرائه. ومن دونها، لا يظهر شيء من هذا.

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

ميزات الذكاء الاصطناعي

التحليلات وبكسلات التتبّع

ست شبكات مدمجة. الصق المعرّف في storefront/.env (ومع Docker Compose، في ملف .env بجوار docker-compose.yml) وأعد البناء. المعرّف المتروك فارغًا لا يحمّل أي سكربت.

المتغير	الشبكة
`NEXT_PUBLIC_GTM_ID`	Google Tag Manager
`NEXT_PUBLIC_GA4_MEASUREMENT_ID`	Google Analytics 4
`NEXT_PUBLIC_META_PIXEL_ID`	Facebook و Instagram
`NEXT_PUBLIC_TIKTOK_PIXEL_ID`	TikTok
`NEXT_PUBLIC_SNAPCHAT_PIXEL_ID`	Snapchat
`NEXT_PUBLIC_PINTEREST_TAG_ID`	Pinterest

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

الحدث	يُطلق عندما
`page_view`	كل انتقال بين الصفحات، بما في ذلك الأول
`view_item`	تنتهي صفحة المنتج من التحميل
`add_to_cart`	الإضافة إلى السلة، أو الشراء الآن، أو زيادة الكمية في السلة
`remove_from_cart`	يُحذف سطر، أو تُنقص كميته
`add_to_wishlist`	يُضاف منتج إلى المفضلة
`view_cart`	تُفتح صفحة السلة وفيها شيء
`begin_checkout`	تُفتح صفحة إتمام الشراء
`purchase`	يُنشأ الطلب ويُسوّى الدفع
`search`	يستقر مصطلح بحث في لوحة البحث
`sign_up`	يُنشأ حساب
`login`	يسجّل متسوّق الدخول

الموافقة

تُحمَّل الوسوم بمجرد تحميل الصفحة. إذا كنت تبيع في الاتحاد الأوروبي أو المملكة المتحدة، فضع لافتة موافقة أمامها قبل الإطلاق: تُركَّب الوسوم بواسطة <AnalyticsScripts /> في src/app/layout.tsx.

محركات البحث والمشاركة

لكل صفحة عامة عنوانها ووصفها الخاصان، من messages/seo/، مع رابط canonical وبدائل باللغة الإنجليزية والعربية واللغة الافتراضية.
يُبقي /robots.txt صفحات الحساب وتسجيل الدخول والسلة وإتمام الشراء وتأكيد الطلب خارج محركات البحث، ويشير إلى خريطة الموقع.
يعرض /sitemap.xml الصفحات العامة باللغتين، إضافة إلى كل منتج عندما يستطيع الخادم الوصول إلى واجهة API.
تحمل كل صفحة بيانات المؤسسة والموقع الخاصة بالمتجر لمحركات البحث، بما في ذلك البحث داخل الموقع.
كل هذه تُبنى من NEXT_PUBLIC_SITE_URL: اضبطه على عنوانك الحقيقي قبل الإطلاق، وأعد البناء.

الهوية البصرية

المتجر النموذجي

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

أي بريد إلكتروني وكلمة مرور يسجّلان دخولك كمتسوّق نموذجي. التصفح، والتصفية، والسلة، والمفضلة، والعناوين، وسجل الطلبات كلها تعمل، وتُحفظ التغييرات في المتصفح.
تحتسب صفحة إتمام الشراء الشحن كما تفعل واجهة API، وتكتمل دون الاتصال بـ Stripe.
بعد ربط واجهة API الخاصة بك، يحذف yarn remove:mock المتجر النموذجي وتنبيهه. ويُبقي public/mock-media/، الذي ما زال الخادم الخلفي المملوء بالبيانات من دون مخزن يشير إليه.

الطرفيةفي storefront

yarn remove:mock

أين تغيّر الأشياء

العنصر	المكان، داخل `storefront/`
الاسم، والشعار، وبيانات التواصل، وروابط التواصل الاجتماعي، وصور المشاركة	`src/config/brand.config.ts`
الألوان	`src/styles/theme-variables.css`
كل كلمة ظاهرة	`messages/<namespace>/en.json` و`ar.json`
عناوين الصفحات في نتائج البحث	`messages/seo/`
تخطيط الصفحة	`src/app/[locale]/` للمسار، و`src/features/` لأجزائه
وسوم التسويق	`src/config/analytics.config.ts`، وتُفعَّل من `.env`

كيف تترابط أجزاء كود المتجر

مُضمَّن مع مشترياتك. سجّل الدخول لقراءته، أو افتحه في ملف التنزيل.

بنية الكود واصطلاحاته، وكيف تضيف شبكة تتبّع.

سجّل الدخول للقراءة عرض القالب

ما تفعله واجهة API للمتجر

تقدّم واجهة API عبر مساراتها العامة ومسارات العملاء كتالوج المتجر، والحسابات، والعناوين، والطلبات، والتتبّع، والتقييمات، وغرفة القياس.

مرجع واجهة API