متغيرات منتجات سلة: رحّل المخطط لا الصفوف

يبدو خيار المنتج حقلًا بسيطًا في لوحة التحكم، لكن التكامل الجيد يعامله كجزء من مخطط الكتالوج. إضافة لون أو مقاس قد تنشئ تركيبات جديدة قابلة للبيع، وحذف خيار قد يحذف قيمه ومتغيراته المرتبطة. أما الربط بالترتيب الذي كان يصل «أزرق / متوسط» بصف في ERP، فقد يشير بصمت إلى كيان تجاري آخر بعد تغير المخطط.

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

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

مثّل الكتالوج كرسم بياني

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

احتفظ بثلاث هويات: هوية المنصة وهي معرف المورد في سلة، وهوية العمل مثل SKU يراجعه التاجر، وهوية المزامنة التي تربط الاثنين ضمن Tenant واحد. لا تستخدم ترتيب Array أو التسمية المترجمة أو ترتيب الخيارات كمفتاح دائم. تتغير الأسماء والترتيبات، بينما تجعل المعرفات والمفاتيح التجارية المعتمدة المطابقة قابلة للتفسير.

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

عرّف الثوابت قبل تخطيط التغييرات

يحتاج الترحيل عبارات يمكن للنظام إثباتها. من الثوابت المفيدة: لكل تركيبة فعالة متغير بعيد واحد فقط، ولكل SKU تديره المنظومة Tenant ومتغير واحد، ولا يدّعي متغيران الباركود نفسه، ولا تتغير دلالة العملة والضريبة، ويوجد نظام واحد فقط يملك المخزون في كل موقع.

افصل الحقول حسب مالكها. قد يملك PIM الاسم والصور وبنية الخيارات، ويملك ERP التكلفة والمخزون، وتبقى سلة المرجع لحالة العرض وMerchandising وسعر تخفيض يعدله التاجر. من دون هذا العقد على مستوى الحقول تصبح «المزامنة الكاملة» سباق Last Writer Wins بين الأنظمة.

صنّف التغيير قبل التنفيذ. تصحيح الاسم Metadata، وتغيير السعر Value Mutation، وإضافة قيمة خيار توسّع رسم المتغيرات، وحذف الخيار يقلّصه وقد يكون مدمرًا، وتغيير SKU يغيّر مفتاحًا تجاريًا ويحتاج انتقالًا موثقًا. لكل فئة تحقق وموافقة مختلفان.

ابنِ خريطة هوية صريحة من القديم إلى الجديد

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

يجب أن تسجل خطة الترحيل عمليات `keep` و`create` و`update` و`retire` و`manual_review`. ولكل متغير سيُوقف، سجّل بديله أو سبب عدم وجود بديل. إذا اندمج متغيران قديمان في تركيبة هدف واحدة فعلى الأداة أن تتوقف؛ فلا يمكن لقاعدة عامة دمج السعر والمخزون وسجل الطلبات بأمان.

اجعل الخطة بإصدار وبصمة من لقطة المصدر. قبل الكتابة مباشرة أعد قراءة المنتج وقارن البصمة. إذا غيّر التاجر الكتالوج بعد التخطيط، أبطل الخطة بدل تطبيقها على شكل جديد. يمكن لتطبيقك فرض Optimistic Concurrency حتى إن لم يقدم Endpoint البعيد شرط Version.

تحقّق من الهدف في وضع ظلي

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

شغّل حالات شراء وتحويلات خلفية تمثيلية على الرسم الظلي. هل يحل اختيار الواجهة إلى متغير واحد؟ هل يصل تصدير ERP إلى SKU نفسه؟ هل يحتفظ فهرس البحث بوثيقة واحدة لكل كيان قابل للبيع؟ وهل تبقى الطلبات القديمة مرتبطة بمتغيراتها التاريخية حتى لو لم تعد معروضة؟

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

اكتب على مراحل واحترم عقود سلة

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

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

نفّذ دفعات صغيرة قابلة للاستئناف لكل متجر. تقول وثائق Rate Limit إن الحدود تختلف حسب باقة المتجر، وتعرض ترويسات `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`Retry-After` و`X-RateLimit-Reset`. استخدمها لضبط طابور Tenant واحد، ولا تجعل زيادة العمال تضاعف الاستدعاءات على حصة التاجر نفسها.

اجعل كل عملية Idempotent في سجلك حتى لو لم يقبل Endpoint مفتاح Idempotency: خزّن معرف الخطة والعملية والمورد وبصمة Payload والمحاولة والنتيجة المتحققة. بعد Timeout اقرأ المتغير قبل إعادة المحاولة؛ ضياع الاستجابة نتيجة مجهولة لا دليلًا على فشل الكتابة.

عامل الحذف كحد لا رجعة فيه

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

فضّل إيقاف التركيبات القديمة أو إخفاءها عندما يسمح سير العمل بذلك. قد تحتاج الطلبات السابقة والتحليلات والمرتجعات والدعم إلى الهوية القديمة حتى بعد توقف بيعها. احتفظ محليًا بـTombstone وآخر Mapping معروف بدل إعادة استخدام SKU أو حذف أثر التدقيق.

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

طابق Webhooks مع الحالة الحالية

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

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

شغّل مطابقة دورية لكل متجر مع Checkpoint. قارن معرفات المتغيرات والمفاتيح Canonical وSKU والأسعار وملكية المخزون بآخر لقطة متحققة. يجب أن ينتج الانحراف خطة إصلاح، لا Full Overwrite آليًا. وإذا كانت الهوية ملتبسة، أرسل المنتج للمراجعة وأوقف الكتابة عليه وحده.

اختبر الأعطال التي تغيّر المال

اختبر إنشاء خيار يتبعه Timeout، وعاملين متزامنين، وتعديل التاجر بعد الموافقة، وخطأ `422` أثناء تطبيق القيم، وحدود الطلبات وسط الدفعة، واندماج متغيرين قديمين في واحد، وغياب SKU، وتكرار الباركود، وطلب حذف بينما يشير طلب جديد إلى متغير قديم. وتأكد أن Retry لا ينشئ متغيرًا منطقيًا ثانيًا ولا يكتب فوق مخزون يملكه التاجر.

راقب الخطط المنشأة والملغاة والمكتملة، والمتغيرات الجديدة والباقية والموقوفة، والمطابقات الملتبسة، وفروقات القراءة بعد الكتابة، واستجابات `422`، ووقت Throttling، والمنتجات المتوقفة للمراجعة. وتابع عمر آخر مطابقة كاملة لكل متجر؛ نجاح Job وحده لا يكفي إذا كان رسم الكتالوج ينحرف.

ابدأ بوضع Report Only: التقط الكتالوج وابنِ الخطط وقارن النتيجة المتوقعة مع رؤية التاجر بلا كتابة. بعدها فعّل مجموعة صغيرة، وامنع العمليات المدمرة مبدئيًا، واحتفظ بمفتاح إيقاف لكل Tenant. التنفيذ الآمن ممل عمدًا: دليل وهوية صريحة وكتابات ضيقة وحالة متحقق منها.

القرار العملي

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

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

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

إعداد: Noor Yasser