الإسناد التلقائي لطلبات Salla: توجيه موثوق للموظفين

تتيح Salla Order Assignment API حفظ قواعد للإسناد التلقائي للطلبات إلى الموظفين وفق الدولة والمدينة وحالة الطلب والفرع. هذه قدرة مفيدة، لكن نجاح كتابة Rule لا يثبت أن كل طلب مؤهل وصل إلى الشخص المقصود. في التكامل الإنتاجي، أدر القواعد كـDesired State لها Version، واقرأها بعد كل تغيير، وراقب الموظفين المسندين فعليًا إلى الطلبات، وطابق الطلبات غير المسندة أوالملتبسة قبل أن تتحول إلى Orphan Orders.

هذا شرح هندسي عملي وليس إعلان منتج. الـEndpoints والـScopes المذكورة أدناه حقائق من وثائق Salla Merchant API الرسمية، وتم التحقق منها في 27 أكتوبر 2026. أما Control Plane وفحوص التداخل وخطة النشر والـMetrics فهي توصيات تطبيقية. الصفحات العامة التي راجعتها لهذا الدليل لا تحدد أولوية القواعد عند مطابقة أكثر من موظف، لذلك لا يفترض المقال أولوية غير موثقة.

الخلاصة أولًا

احتفظ بسياسة Assignment تصريحية واحدة لكل متجر. حل كل معرف Salla قبل النشر، وطبّع القواعد بترتيب ثابت، وقارن Desired Policy بالقواعد التي تعيدها Salla، وطبّق Create أوUpdate المطلوبة فقط. بعد ذلك افحص طلبات مختارة عبر Assigned Employees Endpoint وشغّل استعلامًا مستمرًا لاكتشاف Orphan Orders.

الفرق المهم بين Configured Rules وObserved Assignments. الأولى تعبر عن النية؛ والثانية تعرض حالة المنصة التي يمكن للتشغيل الاعتماد عليها.

ابدأ من العقد الموثق

توثق Salla أربع عمليات تحت Order Assignment. تستخدم List Auto Assignment Rules المسار GET /orders/assignment/rules وتتطلب Scope باسم orders.read. وتستخدم Create Auto Assignment Rules المسار POST /orders/assignment/rules مع orders.read_write. أما Update Auto Assignment Rule فتستخدم PUT /orders/assignment/rules/{rule_id} مع Scope نفسها. وتستخدم Order Assigned Employees Details المسار GET /orders/assignment/{order_id} لإرجاع الموظفين المرتبطين بطلب محدد.

يربط مثال Create بين user_id وArray باسم rules. وتشمل Rule Entities الموثقة country وcity وstatus وbranch، ولكل منها Value Identifier. ويستبدل مثال Update مجموعة Entity/Value في Rule ID معروفة. تتيح هذه الحقائق Workflow من نوع Read-Compare-Write.

لا تنص الوثائق التي تمت مراجعتها لهذا الدليل على:

• هل للقواعد المتداخلة ترتيب تقييم محدد؛
• هل تتوقف المعالجة عند أول Match أويمكن إسناد أكثر من موظف؛
• هل نشر Rule يعيد إسناد الطلبات القديمة بأثر رجعي؛
• هل تغيير Branch Rule يغير ملكية المخزون أوFulfilment Allocation أوCourier Selection.

عامل هذه النقاط كمجهولة حتى تقدم الوثائق إجابة أويثبت Controlled Store Test السلوك. اجعل القواعد Mutually Exclusive قدر الإمكان، ولا تعد باختيار Deterministic مبني على Precedence غير موثقة.

افصل Employee Routing عن Fulfilment Routing

يجيب Employee Assignment عن: «أي موظف مسؤول عن هذا الطلب؟» ولا يجيب عن: «أي فرع يملك المخزون؟» أو«أي ناقل يستلم الشحنة؟». تعرض Salla بيانات الفروع وقدرات منفصلة لـBranch Allocation. افصل المجالات:

يمنع هذا الفصل تحويل تغيير Support Routing إلى تغيير Fulfilment بصمت. كما يمنح كل Integration أقل Permission لازمة لمهمتها.

مثّل Assignment كـDesired State

احفظ Policy بصيغة لا تعتمد على Provider، ثم Compile إلى Payload من Entity/Value في Salla. مثال افتراضي:

policy_version: 17
store_key: merchant-42
routes:
  - route_key: riyadh-ready
    employee_ref: ops-riyadh-a
    match:
      country: SA
      city: riyadh
      status: ready
      branch: riyadh-main
  - route_key: jeddah-ready
    employee_ref: ops-jeddah-a
    match:
      country: SA
      city: jeddah
      status: ready
      branch: jeddah-main

المراجع المقروءة أعلاه Application Aliases وليست قيمًا تُرسل إلى Salla. حلها إلى Platform IDs الحالية، واحفظ Mapping مع Policy Version، وأوقف النشر عند فقد Alias أوإشارته إلى Object غير نشطة. لا تستخدم اسم الموظف كهوية ثابتة.

طبّع أسماء Entities وقيمها قبل Hashing. رتب Rule Elements، واحذف التكرار، واحسب Digest من Employee ID مع Normalized Rule Set. عندها تتساوى Configurations المتكافئة حتى إن اختلف ترتيب الإدخال.

اكتشف التداخل قبل النشر

التداخل Policy Problem قبل أن يكون API Problem. تتداخل Route عندما يستطيع طلب واحد تحقيق مجموعتي الشروط. شغل Static Check على كل تغيير:

1. حوّل كل Route إلى Tuple مطبعة من Country وCity وStatus وBranch.
2. قارن كل Route Pair نشطة للمتجر نفسه.
3. علّم القيم المتباينة كحالة آمنة.
4. ارفع Missing Constraints والقيم المتطابقة أوالمتقاطعة للمراجعة.
5. اطلب Exception Record صريحة إن كان العمل يريد أكثر من موظف مؤهل فعلًا.

يمكن أن تتداخل Rule عامة مثل country=SA مع كل City Rule سعودية. كما يمكن لـCity Rule بلا Branch أن تتداخل مع عدة Branch Routes. ولأن Precedence غير موثقة في الصفحات التي تمت مراجعتها، فلا تعامل ترتيب القواعد كحل. ضيق Policy أوتعامل مع التداخل كقرار عمل قابل للرصد والاختبار.

انشر مع Read-back لاBlind Writes

استخدم خطة مرحلية:

load desired policy
  -> resolve platform IDs
  -> reject invalid or overlapping routes
  -> GET current rules
  -> calculate create/update/no-op actions
  -> snapshot current state
  -> apply one bounded change set
  -> GET rules again
  -> compare normalized state
  -> sample real order assignments

استخدم orders.read في Inventory وAudit Jobs التي تقرأ Configuration أوتفحص Assignments فقط. خصص orders.read_write للـPublisher. لا تنسخ Merchant Access Tokens داخل Configuration أوLogs أوMetrics أوDead-letter Payloads.

إذا انتهت مهلة Write فنتيجتها Uncertain. اقرأ القواعد الحالية قبل Retry. تمنع Local Idempotency Key تكرار Jobs داخل نظامك، لكنها لا تثبت أن Upstream Write لم تنجح بالفعل. احفظ Request Digest ووقت البدء وHTTP Outcome وRead-back Result تحت Change ID واحدة.

يجب أن يعيد Rollback تشغيل Previous Known-good Desired-state Snapshot. لا تولد “Inverse” Request عمياء من الذاكرة؛ ربما تغيرت Remote State بين الفشل والتعافي.

راقب Assignment في الطلبات

يثبت Configuration Read-back أن القواعد موجودة فقط. وتتيح Assigned-employees Endpoint فحص الموظفين المرتبطين بطلب محدد. ابن ثلاث درجات للتحقق:

• Canary: بعد Policy Change افحص مجموعة صغيرة من Test Orders غير الحساسة أوالطلبات الجديدة المؤهلة.
• Sample: افحص دوريًا عينة محدودة من كل Route نشطة.
• Exception: افحص كل طلب تجاوز عمره Service Target للطلبات غير المسندة.

احفظ Employee IDs وأقل Display Data مطلوبة للمهمة التشغيلية. لا تضع بيانات العميل والطلب في Assignment Logs. والـAssignment Workflow Metadata وليست Authorization Boundary؛ يجب أن يفرض التطبيق Access Controls الخاصة به.

طابق الطلبات اليتيمة والملتبسة

أنشئ State Machine صريحة:

يجب أن تكون Reconciliation محدودة بنافذة زمنية حديثة وبالحالات المهمة للعمل. لا تمسح تاريخ المتجر كاملًا في كل Run. استخدم نمط Sequential Order Backfill للاكتشاف التاريخي وPer-store API Budget للـFair Scheduling.

من Metrics المفيدة: عمر أقدم Eligible Unassigned Order، وOrphan Rate، وعدد Ambiguous Assignments، وPolicy-to-remote Drift، وChange Verification Latency، وفشل Reconciliation. تجنب Labels غير محدودة مثل Raw Order ID أوEmployee ID داخل Shared Metrics؛ ضعها في Diagnostics محكومة الوصول.

Rollout آمن عند الفشل

1. صدّر القواعد الحالية وطبّعها.
2. حل كل Employee وStatus وCity وBranch IDs المرغوبة.
3. شغل Overlap وInactive-reference Checks.
4. نفذ Dry-run لخطة التغيير وراجع Exact Diff.
5. طبّق على متجر واحد أوRoute Group واحدة أولًا.
6. اقرأ القواعد وقارن Normalized Digest.
7. افحص Assignments الفعلية لطلبات ممثلة.
8. راقب Orphan وAmbiguous Queues لدورة تشغيل كاملة.
9. وسع تدريجيًا، وأعد Previous Snapshot إذا فشل التحقق.

لا تحول كل المتاجر مرة واحدة. قد تكون Rule صحيحة نحويًا لكنها تعبر عن Operational Boundary خاطئة.

أفضل الممارسات

• افصل Policy وPlatform Identifiers وObserved Assignments كسجلات مستقلة.
• اجعل Route Conditions متبادلة الاستبعاد عندما يتوقع العمل Owner واحدة.
• تحقق من الفروع والحالات والموظفين المشار إليهم قبل كل Publish.
• استخدم Least-privilege Tokens وPublisher واحدة لكل متجر.
• نفذ Read بعد كل Write مؤكدة أوUncertain.
• طابق Assignments من طلبات فعلية، لامن Configuration فقط.
• احتفظ بـPrevious Desired-state Snapshot وChange Trail كاملة.

Anti-patterns

• إنشاء Rule عامة لكل موظف وافتراض أن Salla ستختار بعدل.
• الاعتماد على Rule Array Order كأولوية غير موثقة.
• إعادة كتابة كل القواعد عندما تتغير Route مطبعة واحدة.
• استخدام أسماء الموظفين كمعرفات ثابتة.
• افتراض أن Rule جديدة تصلح الطلبات التاريخية بأثر رجعي.
• استخدام Assignment كدليل على Inventory أوShipping أوAuthorization State.
• إعادة Write انتهت مهلتها قبل قراءة Current State.

Checklist التنفيذ

1. عرّف Provider-neutral Routing Policy مع Version.
2. حل Salla IDs وارفض Inactive أوMissing References.
3. أضف Static Overlap Detector.
4. اجلب Current Remote Rules وطبّعها.
5. أنتج Deterministic Change Plan.
6. انشر عبر Least-privilege Worker.
7. اقرأ القواعد وتحقق من Normalized Digest.
8. افحص Assigned Employees في Canary Orders.
9. شغل Orphan وAmbiguous وDrift Reconciliation.
10. أنشئ Alerts للعمر والأثر، لاRaw Queue Length فقط.

اقرأ أيضًا: Hydration لطلبات Salla الخفيفة، وBackfills المتسلسلة لطلبات Salla، وAPI Budgets وFair Queues في Salla، ومركز هندسة التجارة الإلكترونية.

المراجع الأساسية

• Salla — Order Assignment API collection
• Salla — List Auto Assignment Rules
• Salla — Create Auto Assignment Rules
• Salla — Update Auto Assignment Rule
• Salla — Order Assigned Employees Details
• Salla — List Branches
• Wikimedia Commons — Honeywell 4600g barcode scanner
• Creative Commons Attribution-ShareAlike 4.0

إعداد: Noor Yasser