وعود توصيل موثوقة في سلة: المواعيد والتقويم والمناطق

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

هذا دليل هندسي عملي مبني على وثائق سلة الرسمية التي راجعتها في ٥ أكتوبر ٢٠٢٦، وليس إعلانًا عن إصدار جديد. النسخ وSnapshot والمراقبة والإطلاق المقترحة هنا أنماط معمارية داخل التطبيق، بينما تحدد وثائق سلة حقول API والصلاحيات.

ابدأ من عقد المنصة

تعيد واجهة List Delivery Promises الوعود المهيأة مع حالة التفعيل والنوع والموقع ونطاق مدة التوصيل. تعرض الأمثلة الموثقة أنماطًا مثل السريع ونفس اليوم واليوم التالي والعادي والدولي. تستخدم القراءة صلاحية `shipping.read`، لكنها لا تمثل السياسة الكاملة.

تعيد واجهة Delivery Promise Details الإعداد الأشمل: الدولة والمنطقة والمدن، ونطاق التوصيل والتجهيز، وساعات الظهور، وأيام العمل، والعطل، والترجمات. ويمكن للعطلة الموثقة حمل التاريخ وخيار التكرار السنوي والعنوان. هذه هي الصورة التي يجب أن يلتقطها Control Plane قبل الحساب أو التعديل.

تستخدم واجهة Update Delivery Promise صلاحية `shipping.read_write`. ويتضمن مثالها `visible.adjust_by_preparation` وأيام العمل والعطل والحالة والموقع. عامل التحديث كإطلاق سياسة يخضع للتحقق والتدقيق، لا كتغيير عابر في الإعدادات.

افصل السياسة عن قرار Checkout وحقيقة الشحنة

احتفظ بثلاثة سجلات. السياسة هي إعداد سلة الحالي مع Timezone المطبع وبيانات التحقق. وقرار Checkout هو الوعد المحسوب لسلة شراء وعنوان ولحظة محددة. أما حقيقة الشحنة فهي أحداث التجهيز والتسليم للناقل والحركة والوصول. كل واحد يجيب عن سؤال مختلف.

النطاق «٢–٤ ساعات» إعداد، وليس دليلًا على قبول الناقل للطرد ولا ETA حية. كما أن تأخر مسح الناقل لا ينبغي أن يغير التاريخ الذي عرض سابقًا. يمكن للواجهة عرض تقدير تشغيلي جديد لاحقًا، لكن يجب تسميته Tracking أو تقديرًا محدثًا مع إبقاء الوعد الأصلي للتدقيق.

صمم Snapshot القرار بحقول promise_id وpolicy_version وevaluated_at وstore_timezone وlocation_key وpreparation_range وdelivery_range وwindow_start وwindow_end وdisplay_locale والنص المعروض أو نسخة Template حتمية. اربطها بقرار السلة ثم احفظها مع الطلب المنشأ.

احسب الوقت بتقويم أعمال

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

لا تضف ٤٨ ساعة إلى عصر الخميس وتسمها يومي عمل. تقدم عبر أيام العمل المهيأة، وتجاوز العطل، وعرّف سلوك تجاوز الموعد. يكشف عقد التحديث تعديل الظهور بحسب التجهيز؛ طبّق معناه كما هو موثق ومتحقق للمتجر بدل إضافة Offset مخفي.

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

type PromiseInput = {
  now: Date;
  storeTimeZone: string;
  countryId: number;
  regionId?: number;
  cityId?: number;
  policyVersion: string;
};

const decision = resolveDeliveryPromise(input, policySnapshot);
await saveCheckoutPromise({
  cartId,
  promiseId: decision.promiseId,
  policyVersion: input.policyVersion,
  evaluatedAt: input.now.toISOString(),
  windowStart: decision.windowStart,
  windowEnd: decision.windowEnd,
  locale,
  renderedLabel: decision.label
});

هذا Sketch معماري وليس SDK جاهزًا. اقرأ استجابة سلة الفعلية وتحقق من الوحدات والمعرفات، ولا تنسخ أرقام الأمثلة إلى الإنتاج.

اجعل مطابقة الموقع صريحة

يمكن لوعد سلة الموثق استهداف الدولة والمنطقة والمدن، بينما تدير Shipping Zones API مناطق شحن مخصصة. طبع العنوان بعد أن تحل المنصة Location IDs مستقرة. أسماء المدن الحرة واختلافات الكتابة العربية والترجمة بيانات عرض، وليست مفاتيح مطابقة دائمة.

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

احفظ Location IDs المطابقة في Snapshot. هكذا تستطيع خدمة الدعم تفسير الحالة حتى بعد نقل مدينة بين المناطق أو تعديل قاعدة «كل المدن»، ويمكن للتحليلات فصل خطأ التقويم عن تصنيف عنوان خاطئ.

اجعل Shipping Routes مجاورة لا بديلة

توثق واجهة Shipping Routes List نوع المسار وحالته وأولويته واستراتيجية الدمج وقابلية الجمع. وتذكر أن المسارات تتحكم في ظهور خيارات الشحن في Checkout. لذلك يؤثر المسار في الإتاحة والعرض، لكنه لا ينبغي أن يصبح بديلًا غير موثق عن سياسة الوعد.

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

لا تستنتج SLA للناقل من أولوية المسار؛ الأولوية واستراتيجية الدمج تصفان سلوك الاختيار، أما الدقة فتحتاج بيانات الشحن. خزّن قراءات الإعداد مؤقتًا لفترة قصيرة ومحدودة، وأبطل Cache بعد تعديل الوعد أو المسار.

انشر الإعداد كتغيير ذي نسخة

اقرأ التفاصيل الحالية وطبعها واحسب Digest حتميًا. تحقق من مراجع الموقع، وترتيب النطاق، ووحدة الوقت، وتغطية أيام العمل، وتواريخ العطل، والترجمات، والعلاقة بين التجهيز والظهور. اعرض Diff دلاليًا: «تعطيل نفس اليوم في جدة بعد ١٥:٠٠؛ إضافة عطلة سنوية؛ التوصيل العادي لم يتغير».

اكتب بأقل صلاحية لازمة، وسجل المنفذ وDigest السابق والجديد والسبب والاستجابة. اقرأ التفاصيل مجددًا بعد التحديث وقارن الحالة المرصودة بالمطلوبة. استجابة HTTP ناجحة ليست سياسة متحققة. وإذا غيّر مشغل آخر الوعد بين المراجعة والكتابة، توقف وأعد بناء Diff.

لا تحدث كل المتاجر في Loop غير محدود. استخدم Queue لكل Tenant، واحترم عقد Rate Limit الحالي في سلة، واحتفظ بآخر Snapshot متحقق. فشل متجر لا يعطل البقية، وRetry يجب أن يقرأ الحالة الحالية قبل إعادة الكتابة.

احفظ الوعد عبر إنشاء الطلب

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

احفظ الحقول الآلية والدليل الذي رآه العميل. تدعم الحقول الحتمية التحليل والإعادة، ويثبت النص المعروض ما ظهر بلغته. إذا لم يملك طلب المنصة حقلًا مخصصًا للSnapshot، فاحفظها في Order Projection داخل تطبيقك بمفتاح المتجر ومعرف الطلب. لا تضع Metadata داخلية في ملاحظات يراها العميل.

تستطيع Webhooks الإشارة إلى تغيرات الطلب والشحنة، لكنها لا تعيد حساب وعد Checkout الأصلي. استخدمها لتحديث حقيقة التنفيذ وتشغيل Reconciliation. يشرح دليل آلة حالات الشحن في سلة التعامل القابل للتكرار مع الانتقالات، ويشرح دليل تعافي Webhooks في سلة وزد الفجوات والتكرار.

قس دقة الوعد لا سرعة التوصيل فقط

المقياس الأساسي ليس متوسط المدة. قس نسبة الطلبات المؤهلة التي وصلت داخل النافذة أو مبكرًا أو متأخرة أو ما زالت بلا نتيجة. قسمها بحسب نوع الوعد والمدينة والمسار أو الناقل والمستودع واليوم ونسخة السياسة. استبعد الإلغاء أو تأجيل العميل عبر Reason Codes صريحة بدل حذفها من البيانات.

راقب فشل القرار أيضًا: لا وعد مطابق، موقع ملتبس، إعداد غير فعال، Cache قديمة، تقويم غير صالح، أو غياب دليل شحن. نبه عند ارتفاع التأخير أو عمر الحالات غير المحسومة، لكن لا تستخدم Merchant ID غير المحدودة كLabels. استخدم Trace أو Audit Query بصلاحيات للتحقيق في طلب واحد.

أغلق الحلقة بحذر. قد تبرر الدقة التاريخية توسيع نافذة مستقبلية، لكن لا تجعل Batch صاخبة تعيد كتابة سياسة التاجر تلقائيًا. أنتج توصية بحجم العينة والثقة والجزء المتأثر، واطلب المراجعة، وانشر نسخة، ثم قارن Cohort الجديدة.

اعرف متى لا تعرض وعدًا دقيقًا

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

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

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

إعداد: Noor Yasser