المتاجر المخصصة وواجهات Headless

الهدف

اختيار الطريقة الصحيحة لتمييز متجرك العام — الهوية (Brand)، التركيب (Composition)، الإضافات الموثوقة، أو تطبيق Headless — دون إضافة حزم سمات قديمة داخل BlueMatrix.

لمن

مسؤولو المنشأة ومديرو المتاجر الذين يعملون مع وكالات، والمطوّرون الذين يبنون واجهة متجر مخصصة. يتطلب وحدة commerce_platform. تغييرات السمة/التخطيط في لوحة التاجر تحتاج commerce.themes.manage عند الاقتضاء.

المتطلبات المسبقة

• المتجر متاح في لوحة التاجر ومضبوط للمتسوّقين على منشور — متجر مباشر.
• الوكالات تحتاج معرّف المتجر (slug) وأصل واجهة Commerce (أو Worker BFF بنفس الأصل في الإنتاج).
• لا تضف مجلدات تحت themes/{customer}/ — هذا المسار مجمّد.

مستويات التخصيص (بهذا الترتيب)

المستوى	من يضبطه	متى تستخدمه
1. الهوية (Brand)	إعدادات السمة في لوحة التاجر	الشعار، الألوان، الخطوط، CSS مخصص
2. التركيب (Composition)	الصفحات / القوالب / الكتل	المتاجر القياسية — إعادة ترتيب الصفحة الرئيسية والتخطيطات
3. إضافات موثوقة	ناشر معتمد + تعيين فتحة في المتجر	إضافات صغيرة في فتحات Composition
4. Headless	الوكالة / الهندسة	واجهة كاملة مخصصة على Cloudflare Workers (أو ما يعادلها)

الخطوات — متجر قياسي (Brand / Composition)

1. افتح لوحة التاجر → المتجر الإلكتروني → السمة والصفحات.
2. اضبط الهوية والتخطيط عبر قوالب Composition — معاينة ثم نشر.
3. حافظ على صحة الكتالوج والشحن والمدفوعات كما في مهام تشغيل المتجر.

الخطوات — إضافة موثوقة (وكالة)

1. أنشئ الهيكل: npx create-bluemtx-extension my-extension.
2. انشر entry.js على عنوان ثابت وسجّله لدى BlueMTX (ناشرون معتمدون فقط).
3. عيّن الإضافة لفتحة في المتجر من أدوات التاجر / التشغيل.

الخطوات — متجر Headless (وكالة)

1. أنشئ المشروع: npx create-bluemtx-storefront my-store.
2. ثبّت العميل: npm install @bluemtx/storefront-sdk.
3. اضبط NUXT_PUBLIC_STORE_SLUG وأصل Commerce (اترك الأصل فارغًا عند العمل خلف Worker BFF بنفس الأصل).
4. استدعِ فقط المسارات العامة /api/v1/stores/{slug}/* — لا تستخدم واجهات BlueMatrix أو لوحة التاجر من تطبيق المتسوّق.
5. انشر على Cloudflare Workers + Static Assets. اطلب من BlueMTX ضبط storefront_runtime=headless وتسجيل عنوان الإنتاج.

الحزمة العامة (المصدر والوثائق والإصدارات): github.com/bluemtx/storefront-kit.

النتيجة

يرى المتسوّقون هويتك أو تطبيقك المخصص؛ يبقى Commerce مصدر الحقيقة للكتالوج والسلة والدفع والطلبات. تواصل المنشآت المتصلة مزامنة البيانات الأساسية عبر BlueMatrix.

توقفات صارمة

العرض	السبب	ماذا تفعل
تريد مجلد «حزمة سمة» في المستودع	مسار قديم	استخدم Brand → Composition → إضافة → Headless
أخطاء CORS من الواجهة إلى Commerce	أصل مختلف بلا قائمة سماح / بلا BFF	فضّل Worker BFF بنفس الأصل؛ أو اسمح بالأصول في Commerce
دفع / مخزون خاطئ في التطبيق المخصص	التطبيق يخترع قواعد الخادم	أبقِ قرارات الدفع والمخزون على واجهات Commerce
متجر مسودة	غير منشور	اضبط منشور — متجر مباشر تحت عام

ذات صلة

• مهام تشغيل المتجر
• لوحة التاجر
• فهرس Commerce
• للتطوير (للتكامل)