عقد طلبات سلة الخفيف: رحّل التكامل دون فقد بيانات التنفيذ

لم تعد واجهة طلبات سلة تدعم الاستجابة الموسعة القديمة. توضح وثائق List Orders وOrder Details الحالية أن عقد `expanded=true` انتهى في 1 سبتمبر 2026، وأن واجهة التفاصيل تعيد الآن Light Format افتراضيًا. ولا تتضمن هذه الاستجابة الخفيفة Shipments أوItems أوPickup Branch أوCustomer Groups.

بالنسبة إلى موصل ERP أوWMS أوAccounting أوتطبيق Fulfillment، ليست المسألة إعادة تسمية حقول. لقد تغير مصدر البيانات وتوقيت تحميلها وطريقة التعافي من الجلب الجزئي. كان الموصل يتعامل سابقًا مع Payload موسعة واحدة كأنها Order Aggregate كاملًا، أما الآن فيحتاج سجلًا أساسيًا مختصرًا وخطوات Enrichment صريحة.

التصميم الأفضل ليس إعادة بناء الحمولة العملاقة القديمة مع كل طلب. عامل Light Order كـProjection ثابت للتوجيه وتغييرات الحالة، ثم اجلب Items أوShipment أوCustomer Context فقط للمسارات التي تحتاجها. يقلل ذلك النقل غير الضروري، لكنه يتطلب Jobs دائمة وFreshness مستقلة لكل Resource ومطابقة دورية.

ابدأ بجرد الحقول ومالك كل معلومة

قبل تعديل الكود، سجل كل Field يستهلكه التكامل والقرار الذي يخدمه. افصل حقول Order Core مثل الهوية والمرجع والتواريخ والحالة والدفع والإجماليات وURLs العليا عن الموارد التي لم تعد داخل العقد الخفيف. وحدد هل يحتاج كل مستهلك القيمة بشكل متزامن أمEventually أمفقط للتدقيق.

قد يحتاج ERP Sales Order Header إلى Order ID والمرجع والعملة والإجماليات فورًا. وتحتاج Picking List إلى Items. ويحتاج Shipping Label إلى Shipment وAddress Context. وقد يحتاج Customer Segmentation إلى Groups، بينما لا تحتاجها Invoicing غالبًا. إذا بقيت المتطلبات مختلطة في DTO واحد، ستعيد عملية الترحيل Expanded Mode عبر موجة Calls غير ضرورية.

أنشئ Models داخلية منفصلة مثل `OrderCore` و`OrderItem` و`FulfillmentContext` و`CustomerContext`. احتفظ بـRemote Order ID كهوية رئيسية، وبـ`reference_id` كمرجع أعمال قابل للبحث. تسمح وثيقة التفاصيل بجلب الطلب عبر `reference_id`، لكن لا تستخدم Display Value قابلًا للتغيير كمفتاح أساسي في قاعدة البيانات.

احفظ Raw Light Response إلى جانب Normalized Projection لمدة تدقيق محدودة. يجعل ذلك خطأ Schema قابلًا للتشخيص من دون ربط الخدمات اللاحقة مباشرة بشكل JSON الخاص بالمزود.

حوّل الجلب إلى State Machine صريحة

عندما يكتشف Webhook أومسح المطابقة طلبًا، نفذ Upsert للـLight Core أولًا. ثم أرسل إلى Queue فقط Enrichments المطلوبة للModules المفعلة. توثق سلة واجهة مستقلة هي List Order Items عند `GET /orders/items?order_id=...` بصلاحية `orders.read`. كما تنبه الصفحة الحالية إلى Deprecation للحقلين `codes` و`files` لمصلحة `data.urls.digital_content`، لذلك لا تنسخ Arrays القديمة إلى عقد جديد.

اكتشاف الطلب
  -> core_saved
  -> items_pending?
  -> fulfillment_pending?
  -> customer_pending?
  -> ready_for_export

امنح كل Enrichment حالة مستقلة وعدد محاولات وآخر خطأ وSource Update Time وVerified Time. يجب ألا يمحو فشل جلب العناصر Order Core محفوظًا بنجاح، وألا يمنع غياب Customer Context اختياري مسار المستودع الذي يحتاج Items وShipment فقط. وفي المقابل، لا تجعل ERP Export مكتملًا بينما Resource مطلوب ما زال Pending.

استخدم Idempotency Key مثل `store_id + order_id + resource + source_version`. يمكن بناء Version على Update Timestamp موثق أوLocal Discovery Sequence متزايد إذا لم يمنح الحدث Upstream إصدارًا آمنًا. نفذ Serialization للكتابات حسب الطلب حتى لا يمحو Enrichment متأخر من Event قديم حالة أحدث.

استخدم Webhooks كمحفزات لا كلقطات كاملة

توثق سلة عشرة Order Webhook Events تشترك في Order Model، إضافة إلى نماذج مستقلة لأحداث Shipments. هذه الأحداث مفيدة للاكتشاف السريع، لكن لا تفترض أن كل Event هو Aggregate كامل ونهائي. احفظ الحدث أولًا، وأعد الاستجابة بسرعة، ثم اجلب Light Details والموارد المطلوبة في Background Workers.

نفذ Deduplication حسب التاجر ونوع الحدث وهوية Event أوPayload ثابتة متاحة للمستقبل. احتفظ بـRaw Body ووقت الاستلام، ثم اربطه بـOrder ID. يجب أن يتقارب الحدث المكرر إلى الحالة نفسها، لا أن ينشئ ERP Order ثانيًا.

يوجه دليل Troubleshooting الرسمي الشركاء إلى Webhook Log والتحقق من قبول Receiver لطلب POST. يساعد ذلك في فصل مشكلة التسليم عن عطل التطبيق، لكنه ليس Recovery System. احتفظ بـDead-letter Queue للJobs المستنفدة وبمسح Reconciliation يستطيع إعادة اكتشاف الطلبات حتى عند فقد Webhook أو رفضه.

احترم عقد Pagination المتسلسل

تضع وثيقة List Orders الحالية قواعد Pagination غير معتادة: اطلب الصفحات بالتسلسل، ولا تقفز من الصفحة 1 إلى 10، واستخدم `per_page=30` كحد أقصى، وأكمل التسلسل داخل Cache Window مدتها 15 دقيقة، واستخدم `from_date` و`to_date` عندما يكون ذلك ممكنًا. وقد تعيد الصفحة المطلوبة خارج التسلسل نتيجة فارغة.

هذا يعني أن Fan-out Paginator المعتاد—حيث تجلب Workers الصفحات من 2 إلى 20 بالتوازي—تنفيذ خاطئ. اجعل لكل تاجر وDate Window مالك Cursor واحدًا. اطلب الصفحة الأولى واحفظ نتائجها وCheckpoint، ثم اطلب الثانية. وإذا لم يستطع المسح الاكتمال بأمان داخل النافذة، صغّر Date Range بدل زيادة التوازي.

scan key: store + from_date + to_date
checkpoint: next_page + started_at + highest_seen_update
rule: قارئ مرتب واحد؛ وWorkers متعددة للجلب اللاحق

افصل Discovery عن Hydration. يبقى Ordered Scanner خفيفًا ويكتب Order IDs في Queue؛ ويمكن لWorkers متعددة بعدها جلب التفاصيل والعناصر لطلبات مختلفة، وفق Limits وBackoff Policy اختبرها تطبيقك. لا تنشر صفحات سلة المذكورة رقم Rate Limit موحدًا هنا، لذلك لا تثبت قيمة مخترعة. قس Responses، واحترم Server Guidance، واجعل Concurrency قابلة للضبط لكل تاجر.

استخدم Date Windows متداخلة للتعافي—مثل إعادة مسح فترة حديثة وتنفيذ Upsert Idempotent—بدل الوثوق بحد زمني دقيق مرة واحدة. التداخل توصية تصميمية وليس ضمانًا من المنصة. حدد فترة الإنتاج بحسب Clock Behavior الملحوظ وأنماط تحديث الطلبات وRecovery Delay المقبول.

تجنب N+1 بالجلب حسب الحاجة

استبدال كل Expanded Order بأربع Calls فورية قد يضاعف Latency ونقاط الفشل. عرف Enrichment Profiles. قد يحتاج Analytics Pipeline إلى Light Core فقط. وقد تحتاج Accounting إلى Totals وInvoice Context. ويحتاج Fulfillment إلى Items وShipment Data. ويمكن لـCustomer Engagement تحميل Customer Context بعد نجاح Operational Export.

رتب عمل Queue حسب التاجر والغرض، وخزن Reference Data بطيئة التغيير مثل الفروع المعروفة بشكل مستقل، وتجاوز Fetch عندما يكون المورد المخزن حديثًا بما يكفي للقرار. لا تخزن Order Items إلى الأبد؛ فقد تبطلها Refunds أوEdits أوFulfillment Changes. سجل Freshness Contract بجانب كل Resource.

راقب Requests لكل طلب مكتشف وHydration Latency وعمر Queue والموارد المطلوبة غير المكتملة وDuplicate Events الممنوعة وReconciliation Drift ونسبة الطلبات المصدرة قبل تحقق كل الحالات المطلوبة. صغر Payload ليس نجاحًا إذا كان الموصل يصدر طلبات ناقصة بصمت.

أطلق الترحيل عبر Contract Fixtures وShadow Comparison

أنشئ Fixtures من Light Responses منقحة وWebhook Payloads وكل Enrichment Endpoint. اختبر Optional Objects الغائبة وقائمة Items فارغة وتغير ترتيب العناصر وRefunded Orders وMultiple Shipments وPickup Branch مفقودًا وTimeout بعد نجاح الطرف البعيد ووصول Webhook قبل أن تعكس Details Endpoint التغيير.

لأن Expanded Mode انتهت بالفعل، لا تصمم الإطلاق حول Dual Read دائم. قارن Normalized Aggregate الجديدة مع Historical Expanded Fixtures محفوظة ومع Business Outputs موثوقة: ERP Headers والإجماليات وكميات العناصر ومهام الشحن والسجلات المحاسبية. وفي Shadow Phase شغّل Pipeline الجديدة بلا السماح بـExternal Side Effects، ثم قارن نتائجها بالموصل الإنتاجي الحالي.

أطلق حسب التاجر أوWorkflow. احتفظ بـFeature Flag يستطيع إيقاف Enrichment وExport كلًا على حدة، وReplayable Inbox وDurable Outbox. يجب أن يعيد Rollback المستهلكين إلى Internal Projection السابقة أويوقف Exports؛ ولا يستطيع إعادة عقد Upstream لم تعد سلة تقدمه.

يفرض عقد الطلب الخفيف حدًا معماريًا صحيًا. اجعل Discovery صغيرة، وكل Enrichment مقصودة، والحالة مرتبة حسب الطلب، واستخدم قواعد سلة للقائمة المتسلسلة والمحدودة بالتاريخ للتعافي. عند التنفيذ الصحيح يصبح الموصل أسهل تفسيرًا من Expanded Payload القديمة: لكل Resource مالك وFreshness Rule وحالة فشل ومسار قابل للقياس نحو Convergence.

إعداد: Noor Yasser