Salla App Functions: اختر حدّ التنفيذ الصحيح

تضع Salla App Functions الكود المخصص داخل دورة أنشطة التاجر والعميل من دون أن يدير المطور بنية استضافة الدالة. يصف الدليل الحالي Context تضم Event Payload ومعلومات التاجر وإعدادات التطبيق الخاصة بكل متجر، مع Authentication تلقائية عند استدعاء Salla APIs. لكن القرار المعماري الأهم ليس Serverless مقابل Server، بل هل تنتمي القاعدة إلى المسار الذي ينتظر فيه المستخدم أمإلى ما بعد اكتمال العملية التجارية.

توثق سلة عقدين مختلفين. يحجب Synchronous Action التاجر ويستطيع تعديل العملية أو رفضها. يستهدف الدليل التفصيلي أقل من 500ms، ويعد أقل من ثانية مقبولًا، ويضع حدًا أقصى 5 ثوانٍ ينتج تجربة سيئة أصلًا. أما Asynchronous Event فيدخل Queue من دون حجب المستخدم، وقد يعمل حتى 30 ثانية، ولا تستطيع قيمته المعادة تغيير العملية الأصلية.

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

ابدأ بالقرار لا باسم الحدث

اسأل سؤالًا واحدًا لكل متطلب: هل يجب أن تغير هذه النتيجة قبول العملية الحالية أو رفضها أوتعديلها؟ إذا كانت الإجابة نعم، فقد تنتمي إلى Synchronous Action، ولكن فقط إذا أمكن إنتاج القرار داخل Latency Budget صارمة. أما إرسال الإشعار وتحديث Analytics ومزامنة ERP وإثراء البيانات وبدء Fulfillment بعد قبول العملية فتنتمي إلى الجانب غير المتزامن.

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

لا تفترض أن كل Event Family يملك Synchronous Hook. ابنِ القرار من جدول الأحداث المدعومة وSchema كل حدث. إذا لم تعرض المنصة إلا Async Signal، فلا يستطيع التطبيق محاكاة Pre-commit Rejection بأمان عبر محاولة إلغاء العملية بعد وقوعها. استخدم Compensation فقط عندما يقبل العمل تصحيحًا لاحقًا وتوضح تجربة المستخدم ذلك.

اجعل المسار المتزامن بسيطًا جدًا

يجب أن تشبه الدالة المتزامنة Decision Table صغيرة: تحقق من Context المطلوبة، واقرأ Settings مختصرة، واحسب نتيجة حتمية، ثم أعدها. تجنب سلسلة External HTTP Calls وDatabase Queries ثقيلة وAI Inference وMulti-service Workflow. يحذر دليل سلة نفسه من APIs الخارجية البطيئة والحسابات المعقدة في هذا المسار.

context validation
  -> normalized inputs
  -> local rule / compact lookup
  -> accept, reject or modify

في إجراء شحن، قد تختار القاعدة Service Level معدة مسبقًا، أوتتحقق من Address Field، أوتعيد Rate معروفة. إذا احتاج السعر إلى Carrier API، ضع Hard Timeout أقل بكثير من حد المنصة، وحدد Failure Policy قبل كتابة الكود. يحمي Fail-closed من شحنة غير صالحة لكنه يعطل التاجر، بينما يحافظ Fail-open على التدفق وقد يؤجل المشكلة. هذا قرار Product وRisk، وليس خيار Retry عامًا.

قس المسار كله لاوقت JavaScript فقط: Cold Start وSerialization واتصال الشبكة واستجابة الطرف الآخر وبناء Response كلها تستهلك الوقت الذي يشعر به المستخدم. راقب p50 وp95 وp99 ونسبة Timeout والإجراءات المرفوضة حسب السبب. حد المنصة 5 ثوانٍ ليس Performance Target.

توضح وثيقة Responses الأثر: يسمح `success: true` باستمرار العملية وقد يطبق Data المعادة، بينما يوقف `success: false` الإجراء المتزامن ويعرض الخطأ للتاجر. اجعل الرسائل عملية وآمنة، ولا تسرب Stack Trace أوCredentials أوProvider Responses.

عامل الدالة غير المتزامنة كبوابة دخول لا كمحرك 30 ثانية

لا تؤخر Asynchronous Function العملية الأصلية، لكن 30 ثانية تظل Execution Window محدودة. تناسب API Update صغيرًا أوNotification إذا كان التنفيذ آمنًا داخل المدة. أما ERP Export طويل أوAI Enrichment أوBatch Inventory Reconciliation أومسار شركة شحن فيحتاج Durable State خارج الدالة.

استخدم App Function كـIngress Adapter: تحقق من Context، واشتق هوية ثابتة للعملية، وأرسل Job مختصرة إلى Durable Queue أوInbox، ثم أعد الاستجابة. يملك Worker الخارجي Retries وBackoff وDead-letter Handling وObservability وReconciliation. أرسل فقط الحقول اللازمة لتحديد Source Entity، واجلب التفاصيل الحالية لاحقًا عندما يحتاجها المسار.

App Function -> durable inbox -> worker -> external system
                    |              |
                 dedupe         retry + receipt

تقول نظرة سلة العامة إن App Functions تشمل Built-in Retry Logic وError Handling، لكن الصفحة المذكورة لا تعرف Exactly-once Guarantee أوRetry Schedule كاملًا. لذلك صمم المستقبل بشكل Idempotent. ابن مفتاحًا من حقول ثابتة موثقة ومتاحة للحدث، مثل Merchant ونوع الحدث وEntity ID وقيمة تحديث المصدر، بدل افتراض وجود Event ID غير موثق. يجب أن يتقارب التكرار إلى Inbox Row والنتيجة الخارجية نفسيهما.

وفق دليل Response، يُسجل فشل Async Response لكن عملية المتجر الأصلية تبقى ناجحة. لهذا لا يمثل `success: false` Recovery Mechanism لمزامنة ERP. سجل Job خارجيًا، واعرض Operational Status، وطابق من Salla APIs عند فقد حدث أوHandoff.

افصل الإعدادات والأسرار وسياسة التشغيل

تستقبل كل دالة App Settings مخصصة للتاجر. عاملها Typed Configuration لاكمدخل اعتباطي موثوق. تحقق من URLs وModes وIdentifiers المطلوبة عند الحد. لا تكتب Tokens أوCustomer Personal Data أوPayment Information في Console Logs؛ يحذر دليل الاختبار الرسمي صراحة من تسجيل هذه الفئات.

استخدم مراجع للأسرار عندما تسمح المنصة والتكامل، ودوّر External Credentials، وقيّد Destination Hosts متى أمكن، وامنح كل تاجر Namespace معزولة في Durable Inbox. وجود Merchant ID في Payload معلومة Routing وليس Authorization بحد ذاته. يجب أن يتحقق External Service المستدعى من الدالة أوGateway ويفرض Tenant التي تستطيع تعديلها.

أصدر Runtime Policy. إذا تغيرت قاعدة شحن متزامنة، احفظ Rule Version مع القرار. وإذا أُرسلت Async Job تحت Mapping وعولجت بعد Deployment، يجب أن يعرف Worker أي Schema وTransformation أنشأها. ارفض أوهاجر Payload Versions غير المتوافقة بدل التخمين الصامت.

اختبر الحد تحت الفشل لا نجاح Preview فقط

توثق سلة Preview في Partner Portal تشغل الدوال على Demo Store Data وتعرض Execution Status وResponse Data والمدة وConsole Output والأخطاء. استخدمها لفحص Context الفعلية وتأكيد Scopes. ثم أضف Contract Fixtures وIntegration Tests؛ فنجاح Preview لا يختبر Queue Duplication أوDownstream Outage أوConcurrency.

للدوال المتزامنة، اختبر الحقول المفقودة وأقصى Input Size وCold Execution وبطء الطرف الآخر وSettings غير الصالحة ورسالة الرفض الدقيقة للتاجر. نفذ Latency Test مع تدهور التبعية الخارجية، وتأكد أن الدالة تخرج عند Internal Deadline بدل استهلاك حد 5 ثوانٍ.

للدوال غير المتزامنة، أرسل Logical Event نفسها مرات عدة، وأفشل المستقبل بعد Commit وقبل Response، وأخر الأحداث بترتيب مختلف، ودوّر Credentials أثناء التشغيل. تحقق أن Durable Inbox تنفذ Deduplication، وأن Version أقدم لا يمحو حالة أحدث، وأن Unknown Outcomes تخضع للمطابقة، وأن Dead-letter Work مرئي للمشغل.

اعتمد App Functions مع مخرج واضح

تصف صفحة Welcome الحالية App Functions بأنها Beta ومجانية، مع تسعير مستقبلي قائم على عدد الاستدعاءات وExecution Time واستخدام الموارد. عامل ذلك كوثائق حالية لاكوعد تجاري دائم. قس عدد الدوال ومدتها الآن، واحتفظ بالمسارات الحساسة قابلة للنقل خلف Domain Interface صغيرة.

قد تزيل App Functions البنية من حافة Trigger، لكنها لا تلغي Architecture. التصميم الدائم بسيط: تتخذ الدوال المتزامنة قرارات فورية ومحدودة فقط؛ وتسجل الدوال غير المتزامنة العمل اللاحق أوتسلمه؛ ويملك Workers الخارجيون Reliability للمسارات الطويلة. عندما يكون لكل متطلب أحد هؤلاء المالكين، يبقى التطبيق سريعًا للتاجر وقابلًا للتعافي للمهندس.

إعداد: Noor Yasser