حزمة Shopify الموثوقة ليست عدة وحدات SKU تظهر في بطاقة واحدة فحسب. إنها عقد تجارة يحدد هوية المكونات وكميتها وتوزيع السعر وأهلية المخزون وعرض السلة وتمثيل الطلب وسلوك الفشل. استخدم نموذج الحزمة الثابتة عندما تكون التركيبة معروفة قبل السلة. واستخدم حزمة مخصصة مع Cart Transform Function عندما يجمع المشتري المكونات وقت التشغيل. لا تختَر التنفيذ من شكل واجهة المتجر وحده.
يعتمد هذا الدليل على وثائق Shopify الرسمية التي جرى التحقق منها في 5 أكتوبر 2026. توثق Shopify سلوك المنصة وحدودها؛ أما أنماط الإصدار والتراجع والاختبار والمراقبة أدناه فهي توصيات هندسية. هذا شرح عملي وليس إعلانًا عن ميزة جديدة.
اختر الثابتة أوالمخصصة انطلاقًا من الحقيقة التجارية
يفصل دليل Shopify للحزم بين الحزم الثابتة والمخصصة. تمثل الحزمة الثابتة منتجًا أوVariant بعلاقات مكونات محددة مسبقًا، وتناسب المجموعات وMultipacks التي تبقى ضمن نموذج Variants. أما الحزمة المخصصة فتستخدم مسار Cart Transform لحالات مثل mix-and-match حيث يختار العميل التركيب وقت التشغيل.
السؤال الحاسم: متى تصبح التركيبة المعروضة للبيع حقيقة؟ إذا نشر التاجر مجموعة مستقرة—كاميرا وبطارية وحقيبة—فالعلاقة تنتمي إلى نموذج المنتج. وإذا اختار المشتري أي ثلاث نكهات من مجموعة أكبر، تصبح التركيبة حقيقة داخل السلة وتحتاج Transform وتجربة اختيار في الواجهة.
لا تستخدم Function مخصصة لمجرد أنها تبدو أكثر مرونة؛ سيملك التطبيق عندها الـpicker والإعداد وعرض المخزون وruntime الدالة والترحيل ومسار الفشل. وفي المقابل لا تنشئ مئات Variants ثابتة لتمثيل Builder تركيبي، لأن ذلك ينقل التعقيد إلى الكتالوج والعمليات قبل Checkout.
عرّف عقد حزمة واحدًا ومُصدَرًا
خزّن تعريف الحزمة بمعرف مستقر وإصدار Schema صريح. ضمّن Parent Variant والمكونات المسموحة والكميات المطلوبة وقواعد الخيارات وسياسة التسعير والسوق أوالعملة وفترة النفاذ وحالة النشر. عامل إعدادات التاجر كمدخل غير موثوق: تحقق من المراجع والملكية والتكرار والحد الأقصى للمكونات والكميات المستحيلة قبل التفعيل.
توضح مقارنة Shopify اختلاف التسعير والمخزون. يأتي سعر الحزمة الثابتة من Parent وتوزعه Shopify على المكونات. وفي الحزم المخصصة يستمد expand السعر من Parent، بينما يستمد merge السعر من المكونات مع تعديل تعيده الدالة. تحافظ Shopify على الكمية القابلة للبيع للحزم الثابتة من المكونات؛ أما واجهة الحزمة المخصصة فتعرض التوفر بنفسها، مع إعادة فحص المكونات في السلة وCheckout.
اجعل التعريف المنشور غير قابل للتعديل. ينشئ تعديل التاجر الإصدار 8، بينما تحتفظ السلال التي تضم الإصدار 7 بدليل الاختيار. إذا قرأت الدالة أحدث Metafield متغير فقط فقد يتغير السعر أوالمكوّن تحت سلة مفتوحة. مرر مفتاح إعداد محدودًا أوإصدارًا في خصائص السلة، ولا تحل إلا التعريفات الفعالة والمتوافقة.
اجعل مدخل الدالة صغيرًا وحتميًا
تعمل Cart Transform Function API داخل السلة وCheckout. اطلب الحقول اللازمة فقط: line ID وvariant ID والكمية ومرجع الإعداد الأدنى وربما سياق السوق. تجنب الحقيقة المعتمدة على الشبكة أوRules Engine بعيد على هذا المسار. يجب أن ينتج المدخل والتعريف الموثقان نفسيهما قائمة العمليات المرتبة نفسها.
ابنِ Maps في مرور واحد بدل مقارنة كل Cart Line بكل Line أخرى. ارفض الإعداد غير الصحيح مبكرًا وأعد عمليات فارغة عندما لا يوجد مرشح. تقول إرشادات Shopify لعدد التعليمات إن الدالة تستطيع تنفيذ حتى 11 مليون تعليمة للسلال التي لا تتجاوز 200 سطر، ثم يتدرج الحد للسلال الأكبر. وتؤكد أن البقاء دون السقف ليس الهدف، لأن كل تعليمة تزيد زمن مسار شراء حرج.
يعطي Rust هامشًا أكبر للمنطق المعقد أوالسلال الكبيرة. ويمكن أن يناسب JavaScript عقدًا محدودًا إذا قسته بFixtures تشبه الإنتاج. سجل instruction count وحجم المدخل والمخرج وعدد الحزم لكل Fixture Regression. إثبات Demo من سطر واحد يثبت الصياغة لا قدرة Checkout.
عامل العمليات كخطة مرتبة
تعيد الدالة عمليات مرتبة. استخدم merge عندما ينبغي أن تظهر المكونات المنفصلة كـParent مجمع، وexpand عندما يجب أن يتحول سطر Parent إلى مكونات. استخدم update فقط لتغييرات العرض المدعومة مثل العنوان أوالصورة أوالسعر، وتحقق من أهلية المتجر قبل الاعتماد على عملية. لا تستهدف السطر نفسه مرتين بالخطأ.
type Plan = {
definitionVersion: string;
consumedLineIds: string[];
operation: 'linesMerge' | 'lineExpand';
parentVariantId: string;
componentFingerprint: string;
};
const plan = validateAndPlan(cart, activeDefinitions);
if (!plan.ok) return { operations: [] };
return { operations: renderOrderedOperations(plan.value) };مرحلة التخطيط معمارية تطبيق وليست مثال SDK من Shopify. تفصل التحقق والاختيار والرسم. أعط كل Input Line مالكًا واحدًا، ورتب المرشحين بمفتاح مستقر، واحسب بصمة المكونات من variant IDs والكميات بعد توحيدها. يجب ألا يعتمد الناتج على ترتيب Map أووقت الساعة.
عند تثبيت Cart Transforms من عدة تطبيقات تشغلها Shopify وتحل تعارض العمليات وفق القواعد الموثقة. لا يفترض تطبيقك أنه المعدل الوحيد. اختبر التعايش مع الخصومات وسياسات البيع والتحويلات الأخرى، واجعل بقاء السلة دون تعديل نتيجة آمنة.
صرّح بوعود السعر والمخزون
توفر الكمية القابلة للبيع للحزمة الثابتة نقطة قوية، لكن الأنظمة اللاحقة ما زالت تحتاج حقيقة التنفيذ على مستوى المكونات. وفي الحزمة المخصصة تكون إشارة التوفر في الـselector مساعدة سريعة وليست حجزًا. يبقى تحقق السلة وCheckout مرجعيًا. أخبر المشتري عندما ينفد مكوّن واحتفظ بالاختيار كي لا يعيد بناء الحزمة.
حدد مالك التسعير. سعر Parent الثابت والسعر المشتق من المكونات في الحزمة المخصصة نموذجان محاسبيان مختلفان. عرّف توزيع الخصم والتقريب لكل عملة وحد التعديل وما يحدث إذا تغير سعر مكوّن في سلة مفتوحة. أعد الحساب من مدخلات السلة الموثوقة، ولا تثق بإجمالي أرسله المتصفح.
تحسب Shopify الضرائب على المكونات وتمثلها في الطلبات. لذلك يجب أن تستوعب Adapters للـERP والمستودع والتحليلات علاقة المكونات بدل إعادة بنائها من عنوان. احتفظ بهوية Parent للتسويق وهوية المكونات للمخزون والضرائب والتنفيذ والمرتجعات.
صمّم سياسة الفشل قبل الإطلاق
اختر هل يستمر Checkout بخطوط غير محولة أم يتوقف عند فشل التحويل. تعتمد الإجابة على وعد المنتج. إذا كانت المكونات صالحة منفردة بأسعارها العادية فقد يكون Cart غير مجمع مقبولًا. وإذا كان Parent غير قابل للشراء بلا مكونات، استخدم requiresComponents الموثقة وأغلق المسار عند تركيب ناقص.
لا تواصل بصمت بعد تفسير جزئي. يجب أن ينتج التعريف غير الصالح مخرجًا آمنًا وTelemetry وخطأ إعداد ظاهرًا للتاجر. يختلف runtime exception عن no-op صحيح؛ راقبهما منفصلين. يعرض دليل أخطاء الإنتاج أخطاء runtime والتعليمات والذاكرة والمخرجات. انقل المدخلات الممثلة إلى Test Corpus ملتزم بالخصوصية بدل الاعتماد على Logs محدودة عمدًا.
اجعل وحدة التراجع تضم Function binary وinput query وconfiguration schema وstorefront block وorder parser. إعادة WebAssembly قديم مع Metafield Schema جديد ليست Rollback.
احفظ حقيقة المكونات بعد Checkout
الطلب هو الدليل الدائم لما اشتراه العميل. خزّن Order Line ومراجع المكونات وهوية Parent وإصدار التعريف والكميات والقيم الموزعة وحالة التنفيذ. لا تعتمد على الكتالوج الحالي لشرح طلب قديم؛ المنتجات والعناوين والتركيبات تتغير.
تحتاج المرتجعات سياسة صريحة: هل يعود مكوّن وحده؟ هل ينعكس خصم الحزمة نسبيًا؟ هل يبقى Warranty Parent صالحًا بعد Refund؟ مثلها كقرارات سياسة وقيود Ledger بدل تعديل الحزمة التاريخية. تقارن المصالحة مكونات الطلب بسجلات ERP أوالمستودع وتكشف خطوط التنفيذ المفقودة أوالمكررة.
لتسليم الأحداث والتعافي اربط التصميم مع معمارية Shopify Webhooks الدائمة. وإذا امتد التكامل عبر تجار فمرر سياق العميل كما في معمارية SaaS لعزل العملاء، واستخدم مسارات استعادة Checkout للفشل الظاهر للمشتري.
اختبر العقد لاالمسار السعيد فقط
أنشئ Fixtures لحزمة ثابتة صحيحة وأخرى مخصصة، ومكونات ناقصة وخطوط مكررة وتقسيم كمية ومكوّن حذف بعد الاختيار وإعداد قديم وعملات متعددة وتفاعل الخصم وسلة ضخمة وتحويل آخر يستهدف السطر نفسه. افحص العمليات المرتبة حرفيًا ومسار fallback دون تعديل.
أعد تشغيل مدخلات تشبه الإنتاج محليًا وضع Baselines لعدد التعليمات. أطلق إصدار تعريف جديدًا تدريجيًا إلى متاجر تطوير أوداخلية قبل التوسع. راقب أخطاء التنفيذ ونسبة no-op حسب السبب وتوزيع التعليمات والتحول من السلة إلى Checkout واستعادة نفاد المكوّن واختلاف السعر ومصالحة الطلب والمكونات وفشل إعداد التاجر. Conversion وحده لا يميز Flow أسرع من حزمة رخيصة بالخطأ.
استخدم Synthetic Checkout لحزمة معروفة وافحص عرض السلة وبنية المكونات في الطلب. نبه على Semantic Drift لا HTTP availability فقط؛ فقد تنجح الدالة بينما يجعل تعديل كتالوج كل حزمة مقصودة no-op.
متى تكون Shopify Bundles الأداة الخاطئة؟
لا تستخدم الحزمة لتمثيل Subscription أوPreorder؛ تذكر وثائق Shopify أن الحزم لا تباع مع selling plans. ولا تستخدم حزمًا متداخلة؛ لا يمكن أن تحتوي الحزمة مكونات وتكون مكوّنًا لحزمة أخرى. ولا تضغط Configurator خارجيًا بآلاف الخيارات في Metafield واحدة وحلقة عملاقة.
استخدم Variants عادية عندما يكون الاختيار Option واحدًا، وDiscount عندما تبقى المنتجات مستقلة ويتغير السعر فقط، أوCart Lines منفصلة عندما لا يضيف التجميع قيمة للمشتري أوالتنفيذ. أما القواعد التي تحتاج ائتمانًا أوامتثالًا أوحقيقة مخزون بعيدة، فنفذ تحققها المرجعي في Validation أوBackend مخصص بدل افتراض أن Presentation Transform يملك النظام الخارجي.
قرار الإنتاج
اختر الحزم الثابتة للتركيبات المستقرة التي تستفيد من علاقات المنتج والكمية القابلة للبيع التي تديرها Shopify. واختر حزمة Cart Transform مخصصة للتركيب وقت التشغيل عندما يستطيع التطبيق امتلاك selector وتجربة التوفر وخطة العمليات الحتمية ومسار التعافي.
في الحالتين أصدر تعريف الحزمة، وقلص مدخل الدالة، وقس التعليمات، وصرح بملكية السعر والمخزون، واحفظ حقيقة المكونات في الطلب، وحدد no-op آمنًا أوfail-closed. بطاقة الحزمة المرئية هي الخطوة الأخيرة؛ المنتج الحقيقي هو العقد الذي يبقى صحيحًا من الاختيار حتى التنفيذ والمرتجع.
المراجع الرسمية
تدعم هذه المراجع سلوك الأدوات المذكورة. الأمثلة وقرارات التصميم توضيحية، ويجب تكييفها مع متطلبات المشروع وإصداراته.
إعداد: Noor Yasser
تعمل على تحدٍ تقني مشابه؟
أساعد الفرق على تحويل القرار المعماري إلى نطاق واضح وتنفيذ يمكن تشغيله ومراجعته بثقة.
