الهدف: مسح أرقام تتبع بوسطة اللي رجعت فعليًا للمخزن، والتحقق من نوع الشحنة عند بوسطة وحالة الأوردر الحالية على شوبيفاي (S1/S2 + returnStatus) قبل السماح بتحديث الحالة إلى Returned — من غير أي انتظار لتحديث حالة بوسطة نفسها، لأن فعل المسح هو التأكيد الفعلي للاستلام بالمخزن.

المستخدمون المستهدفون: موظفو المخزن المسؤولون عن استلام الشحنات الراجعة (RTO ومرتجعات ما بعد التسليم).

كيف تعمل — Workflow

1. الموظف يمسح أرقام تتبع بوسطة (سكانر أو يدوي)
2. الأداة تستعلم بوسطة، وتجيب S1/S2/returnStatus من شوبيفاي لكل أوردر
3. تتحقق من جدول القرار (تحت) وتعرض النتيجة — متوافق أو مرفوض مع السبب
4. الموظف يراجع ويحدد الأوردرات المتوافقة، ثم يضغط "تحديث شوبيفاي"
5. الأداة تعيد التحقق دفاعيًا لحظة الكتابة، ثم تنفذ لكل أوردر لوحده

منطق القرار (Decision Table)

• orderType = Send → رفض فوري (النوع ده شحن أصلي، مش من اختصاص أداة المرتجعات)
• مسار RTO: S1 ∈ {Shipped, In-Return} + S2 فاضي + returnStatus = NO_RETURN → يلغي الأوردر على شوبيفاي (orderCancel، استرجاع للمخزون) ثم يكتب custom.manual_status = Returned
• مسار مرتجع بعد التسليم: S1 = Delivered + S2 ∈ {Shipped, In-Return} + returnStatus = IN_PROGRESS → يكتب custom.status_2_r_e = Returned ثم يسترجع كل قطعة راجعة فعليًا للمخزون (reverseFulfillmentOrderDispose) — بالكمية المتبقية فقط
• returnStatus = RETURN_REQUESTED → مرفوض (من v3.2.0): المرتجع لسه محتاج approve من CS، وقبله شوبيفاي ما بتنشئش أي reverseFulfillmentOrder — يعني الحالة كانت هتتكتب والمخزون ما يرجعش
• غير كده → رفض هذا الأوردر فقط مع سبب مفصّل، وباقي الأوردرات المحددة تتحدث عادي

⚙️ نتيجة كل صف — أربع حالات

التحقق بعد التنفيذ (v3.2.0)

• الاسترجاع: العدّ بيتم من رد شوبيفاي نفسه، وبعدها قراءة تحقق بتأكد إن الـ dispositions اتسجّلت على اللوكيشن الصح
• الإلغاء: orderCancel بيرجّع job (غير متزامن) — الأداة بتتأكد بعد الدفعة إن cancelledAt اتسجّل فعلاً وإن فيه دليل استرجاع مخزون
• أي عملية ما اتأكدتش بتظهر صفراء (تم جزئيًا) مع سبب واضح — مش خضراء

مفيش أي تاج بيتكتب على شوبيفاي — التحديث بيروح مباشرة على الميتافيلد، بالإضافة لأكشن شوبيفاي واحد إضافي حسب المسار (إلغاء الأوردر لمسار RTO، أو استرجاع المخزون لمسار المرتجع بعد التسليم) — نفس الأكشنز المستخدمة في أداة Order Status Updater.

الـ Endpoints الرئيسية

FEATURE MAP

• §STYLES — توكنز :root (الثيم الأحمر = override للـ accent بس) + كل CSS
• §TOOL-JS::refreshRow / mergeLookupResults — إعادة الاستعلام بتستبدل الصف مش بتتخطّاه
• §TOOL-JS::recheckBeforeUpdate — إعادة استعلام إجبارية قبل أي تنفيذ + بانر "اتغيّر إيه"
• §TOOL-JS::confirmDanger (askConfirm) — نافذة تأكيد بتسمّي الأثر (كام إلغاء نهائي · كام استرجاع مخزون)
• §TOOL-JS::chunkedUpdate — تقسيم الدفعة على مجموعات ١٠ + تقدّم حقيقي + نزع سلاح الصف (doneInSession)
• §TOOL-JS::resultModal — نافذة ملخّص ما بعد التنفيذ (خمس حالات + تفاصيل المرفوض و"خلاص متعمل" في قايمتين منفصلتين)
• §TOOL-JS::pendingRejected — المرفوض اللي لسه ما اتسجلش بالسبب ده (حارس التكرار في السجل)
• §UPDATE::logRejectedItems (Worker) — إعادة تحقق من المرفوض وقت التسجيل + صف D1 بنوع rejected
• §CONFIG::esc — تهريب أي نص جاي من بوسطة/شوبيفاي قبل ما يتحط في innerHTML
• shared/shell.js — الهوية (requireSession) والهيدر الموحّد والإعدادات والتوست وحارس النسخة والفحص الذاتي 🩺، نسخة واحدة مضمّنة للهب كله
• §SHELL-JS::freezeOnScroll — الهيدر وشريط التابات جوّه .sticky-header-wrap بعتبة مقيسة (measureSticky) + chip التاب
• §LOGIN / §AUTH-JS — اتشالوا: الدخول بيحصل مرة واحدة في الشاشة الرئيسية للهب
• PAGE_DIAG_LABELS — أسماء عربية لفحوصات ?action=diag (الـ Worker ده بيرجّع checks ككائن بمفاتيح إنجليزية)
• §SCAN — سكانر جن + إضافة يدوية لأرقام التتبع
• §TOOL-JS — lookup · جدول النتائج · startUpdate (٣ حالات) · تصدير النتائج
• §LOG-JS — تاب السجل: القسم الموحّد (فلاتر multi-select + مدى تاريخ + ترتيب ٣ حالات + صف النتائج) و pagination وتصدير XLSX ببانر التقصّ

KEY VARIABLES

• currentEmployee — { username, displayName } جاي من sessionStorage عبر requireSession()، أبدًا في localStorage
• الدخول/الخروج بقوا تحت warehouse_ops_center (الهب) بدل bosta_return — أفعال الأداة ما اتغيّرتش
• extra.sourceTool = 'bosta_orders_returned_scanner' — يفلتر سجل هذه الأداة داخل tool = 'metafields_change' المشترك
• TOOL_VERSION (shell) — نسخة الهب كله، مصدر واحد لكل الصفحات عبر renderVersionUI()
• doneInSession — علامة على الصف اللي اتنفّذ في الجلسة دي؛ بتمنع إعادة إرساله وبتتحافظ عليها عبر إعادة الاستعلام
• extra.result — success / warning / error / rejected / already
• extra.stage — للصف المرفوض: lookup أو write (كان متوافق واتوقف وقت التنفيذ — سباق بين موظفين)
• TN_MIN_LEN / TN_MAX_LEN — حدود طول رقم التتبع (٨–١٣)
• WOC_API_TIMEOUT_MS (shell) — مهلة ٩٠ ثانية على كل نداء (AbortController)
• WOC_WORKERS.returned.min (shell) — أقل نسخة Worker الواجهة بتشتغل معاها. مالهاش أي علاقة بـ TOOL_VERSION
• WOC_WORKERS.returned.url (shell) — ثابت في الكود، مش حقل إعدادات ولا localStorage
• LS_SECRET = 'warehouse_ops_worker_secret' (shell) — مفتاح مجموعة warehouse_ops، قيمة واحدة للست Workers

الـ Workers اللي الصفحة دي بتناديهم

NOTES

• D1 logging: العمليات الجديدة تحت tool = metafields_change. أحداث الدخول/الخروج تفضل تحت tool = bosta_return بدون تغيير.
• أي أوردر توصّل لمرحلة التنفيذ الفعلي (نجح أو فشل) بيتسجل في D1 دايمًا — عشان الإلغاء (orderCancel) إجراء لا رجعة فيه، والفشل الجزئي لازم يبان في السجل.
• v3.2.0 — قاعدة "مفيش نجاح من غير دليل": shopifyGQL() في الـ Worker بترمي خطأ على كل أنواع الفشل (HTTP status، رد مش JSON، أخطاء GraphQL عليا بـ data:null). قبل كده أخطاء الصلاحيات كانت بتعدّي كنجاح لأن userErrors بتبقى فاضية لما data ترجع null.
• الاسترجاع بيتم بالكمية المتبقية (totalQuantity − Σ dispositions) — الـ reverseFulfillmentOrder بيفضل OPEN حتى بعد الاسترجاع الكامل، فشرط OPEN لوحده مش بيمنع الاسترجاع المزدوج.
• الصلاحيات المطلوبة على تطبيق شوبيفاي: read_orders · write_orders · read_returns · write_returns · read_inventory · write_inventory · read_locations. شغّل diag من الإعدادات بعد أي تغيير في التطبيق.
• v3.3.0 — التحقق من الإلغاء بيستنى، مايقراش فورًا: orderCancel بترجّع Job، والقراءة الفورية بعدها بتفشل دايمًا تقريبًا فكل إلغاء ناجح كان بيطلع أصفر. دلوقتي backoff متصاعد + فحص job(id){ done } نفسه ووقوف على أول تأكيد، و{ jobDone, attempts, waitedMs } بترجع في الرد وفي D1.
• v3.3.0 — رقمين تتبع لنفس الأوردر: الـ Worker بيتخطى التكرار في نفس الدفعة بدل ما يلغي الأوردر مرتين على لقطة حالة قديمة.
• الأداة بتقبل أي نوع شحنة من بوسطة غير Send (قرار مقصود) — حراسات S1/S2/returnStatus هي اللي بترفض اللي مالوش مسار صحيح، لأن قايمة أنواع بوسطة بتتوسّع من غير إشعار.
• فشل الكتابة في D1 بيرجع في الرد كـ logged:false وبيظهر تنبيه — مش بيتبلع.