الصفحة دي جزء من الهب — الدخول بيحصل مرة واحدة في الشاشة الرئيسية، والهوية بتوصل هنا من sessionStorage (بتموت مع قفل التاب، ولكل تاب لوحده).

اللي اتغيّر عن الأداة المستقلة

• زراري «عطلان» و«إعادة» في جدول الطابور بقوا صفحات جوّه الهب (Order-Item-Remover.html وOrder-Printer.html) وبياخدوا رقم الأوردر معاهم. target="_blank" اتشال — التنقل في نفس التاب + زرار «↩ رجوع للطابور».
• لسه بلا أي أكشن على الأوردر ومفيش نداء للـ Worker — بيفتحوا صفحة وبس.
• الطابور بيترسم من الكاش أول ما الصفحة تفتح (مختوم بوقته)، والجلب بيحصل في الخلفية لو الكاش عدّى ١٥ دقيقة. الشاشة الفاضية أسوأ من شاشة قديمة مختومة بوقتها.
• صف الدخول في D1 بقى warehouse_ops_center، لكن فعل التغليف نفسه (packed) لسه تحت pack_checker زي ما هو — التاريخ ما اتكسرش.

الهدف: التحقق من تغليف الأوردرات قطعة قطعة قبل الشحن، وتسجيل التغليف على الأوردر (ميتافيلد + tag) وفي سجل D1.

المستخدمون المستهدفون: موظفو التغليف في المخزن — بالسكانر أو بالإدخال اليدوي.

كيف تعمل — Workflow

1. الشاشة بتفتح على طابور «جاهز للتغليف» تحت مربعات الإدخال — الأوردرات اللي حالتها Ready واتطبعت ولسه ما اتغلّفتش. الجدول للعرض بس: الضغط على صف مابيفتحش التشييك، ورقم الأوردر لينك لشوبيفاي.
2. سكان باركود الأوردر أو إدخال رقمه → الـ Worker بيجيب بيانات الأوردر من Shopify.
3. الأداة بتحدّد المرحلة (S1/S2) من تلات إشارات: وجود طلب استبدال نشط + custom.manual_status + custom.status_2_r_e.
4. لو الأوردر متغلّف قبل كده من غير تعديل: نافذة بتعرض تفاصيل التغليف السابق وبتمنع الإعادة.
5. لو متغلّف قبل كده ومع تعديل مكتشف: نافذة واحدة بتجمع التفاصيل + تأكيد رجوع المخزون، وبعد التأكيد بتكمّل.
6. سكان منتجات الأوردر واحدة واحدة بالباركود/SKU → لما تكتمل → زرار «تأكيد اكتمال التغليف».
7. الـ Worker بيكتب الميتافيلدات + tag، وبيسجّل في D1 ومعاه بصمة المنتجات للمقارنة المستقبلية.

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

⚙️ إجراءات كل حالة

FEATURE MAP

• §AUTH (Worker) — بلوك الدخول المشترك · §AUTH-JS (HTML) — شاشة الدخول والخروج
• §PACK::analyzeStage (Worker) — تحديد المرحلة من التلات إشارات
• §PACK::classifyOrderItems (Worker) — تصنيف المنتجات على fulfillableQuantity
• §PACK::buildFingerprint + readStoredFingerprint (Worker) — كشف التغيير
• §PACK::fetchOrderForPack (Worker) — تصفيح lineItems و returns + علم truncated
• §DIAG (Worker) — diag وget_config
• §SCAN (HTML) — سكانر الأوردر وسكانر الباركود · §SCAN::entryMode — المربع النشط والفوكس بيرجع له · ::scannerBinding — نفس سلوك السكانة للمربعين
• §BOSTA (Worker) — bostaSearch · cleanOrderName · resolveTrackingToOrderName — تحويل تراكينج بوسطة لرقم أوردر (قراءة بحتة)
• §TOOL-JS (HTML) — شاشة الفحص · النوافذ · نتيجة التغليف بـ ٣ حالات
• §LOG-JS (HTML) — جدول السجل · الفلاتر · الترتيب · الصفحات · تصدير XLSX
• §READY (Worker) — طابور «جاهز للتغليف»: get_ready_orders · isPrintedNotPacked · classifyS2Subtype · classifyS2Batch · shapeReadyOrder
• §TOOL::readyQueue (HTML) — الطابور تحت مربعات الإدخال · §READY-JS — الفلاتر · الترتيب · الجدول · تصدير XLSX
• §READY-JS::elapsed (HTML) — rdySincePrint · rdyOrderAgeText · rdyDayDiff — الأعمدة المحسوبة بالوقت (بتوقيت القاهرة، بفرق الأيام التقويمية)
• §READY-JS::ticker + ::freshness (HTML) — نبضة كل ٣٠ ثانية بتحدّث الأرقام النسبية في مكانها بدون أي نداء شبكة
• §READY-JS::autoRefresh (HTML) — rdyArmAutoRefresh · rdyAutoRefreshTick · rdyQueueVisible — التحديث التلقائي كل ١٥ دقيقة (النداء الدوري الوحيد في الأداة)
• §READY-JS::courier (HTML) — عرض المندوب بلونه (بوسطة أحمر · شو روم أخضر · غيرهم أزرق · فاضي رمادي)
• §READY-JS::courierChips (HTML) — مربعا «بوسطة/مناديب» فوق الجدول (v2.6.2، بدّلوا مربعات المنطقة اللي اتشالت): عدّ من الطابور كله وفلترة بضغطة، نفس حالة فلتر «المندوب»
• §LABEL-MACHINE (HTML · CSS + JS) — ماكينة الليبل المطبوع ٢×١ إنش: bcBuildLabel · bcFitLabelText · bcRenderLabels · bcFirePrint. 🔴 نسخة مكرّرة عن قصد — التوأم في Order-SKU-Barcode-Printer.html، والكتلتان متطابقتان بايت ببايت. الانحراف بيتمسك بـbash docs/label-twin-check.sh
• §PACK-LABELS (HTML) — packPrintLabels: زرار «🏷️ باركود المنتجات» في شاشة التشييك. بيطبع بنود المرحلة الجارية (currentItems) بصفر نداء للـ Worker

KEY VARIABLES

• TOOL_VERSION — مصدر واحد لرقم نسخة الواجهة (الهيدر + الـ Changelog + شاشة الدخول)
• MIN_WORKER_VERSION — أقل نسخة Worker الواجهة دي بتشتغل معاها (مالهاش علاقة بـ TOOL_VERSION)
• روابط الـ Workers — ثوابت في shared/shell.js § CONFIG، مش في الإعدادات ولا في التخزين المحلي (Standards #28)
• LS_SECRET = 'pack_checker_worker_secret' — المفتاح الوحيد في localStorage
• currentEmployee — { username, displayName } في الذاكرة فقط
• lastEntryMode — آخر مربع إدخال اتشتغل منه (shopify · bosta · manual). في الذاكرة فقط، وبيتصفّر عند الخروج.
• msState — حالة فلاتر الاختيار المتعدد في تاب السجل (فلترة server-side)
• rdyMsState · rdyAllOrders · rdySortState — حالة فلاتر وترتيب الطابور (فلترة client-side). منفصلة عن اللي فوقها بالكامل — الاتنين شغّالين في نفس الصفحة.
• rdyDirty — «حصل تغليف والطابور بقى قديم». التحديث بيحصل عند الرجوع لشاشة الطابور، والفلاج مابيتصفّرش غير بعد جلب ناجح.
• rdyLastLoadedAt — ختم آخر جلب ناجح؛ منه بيتحسب «منذ كام» ولون الزرار.
• TOOL_NAME = 'pack_checker' — قيمة tool في جدول logs

NOTES / QUIRKS

• كشف التغيير بيقرا extra.fingerprint المخزّن؛ الصفوف القديمة بترجع لتحليل نص items — ولو التحليل فشل، النتيجة «فيه تغيير» (الافتراضي الآمن).
• صيغة items (SKU ×qty) مرتبطة بين complete_pack وget_order — الاتنين بيتغيّروا مع بعض.
• fulfillableQuantity هو مصدر الحقيقة الوحيد للتصنيف — ممنوع فلترة يدوية على الـ refunds.
• v2.1.0 — complete_pack بقى بيتحقق من شوبيفاي قبل أي كتابة: بيقرا الأوردر، بيحسب المرحلة بنفسه (أي stage جاي من الواجهة بيتجاهل)، وبيرجّع 409 + conflict لو الأوردر اتغلّف بالفعل. تاب مفتوح من ساعة أو ضغطة مزدوجة ماعادش يعدّي.
• v2.1.0 — الحارس اتفصل في §PACK::evaluatePackGuard: دالة واحدة بينادها get_order وcomplete_pack، فمستحيل يفترقوا في المنطق.
• v2.1.0 — البصمة والملخّص المخزّنين في السجل بقوا من بنود السيرفر مش بنود الواجهة. لو الاتنين اختلفوا، العملية بتكمل ببنود السيرفر مع تحذير «الأوردر اتعدّل بين ما فتحته وما ضغطت تم».
• dateFrom/dateTo بيتقارنوا بـ timestamp المخزّن (UTC) والعرض بتوقيت القاهرة (UTC+3) — فرق ٣ ساعات ممكن يحط عملية متأخرة في يوم UTC اللي بعده.
• edit_count لسه في schema الـ D1 للتوافق بس — مابيتكتبش من v1.3.0+.
• v2.2.0 — أداة «أوردرات جاهزة للتغليف» اتدمجت هنا. الطابور بيظهر تحت مربعات الإدخال في نفس تاب التغليف — مش تاب منفصلة — والضغط على صف مابيفتحش شاشة التشييك (قرار أحمد 05-09-2026). الدخول للتغليف من السكانر أو الإدخال اليدوي زي ما هو.
• v2.3.0 — الطابور بيتحدّث لوحده في تلات لحظات: بعد الدخول · بالضغط على «تحديث» · عند الرجوع لشاشة الطابور بعد أي تغليف ناجح أو جزئي (تحديث صامت). التحديث بقى عند الرجوع مش في لحظة الحفظ — استعلام واحد بدل اتنين، والقايمة بتتجاب بعد ما الكتابة على شوبيفاي خلصت. مفيش polling.
• v2.3.0 — «الوقت منذ الطباعة» و«عمر الأوردر» بيتحسبوا بـفرق الأيام التقويمية بتوقيت القاهرة مش بـ(الآن − الوقت)/٢٤ ساعة. أوردر اتطبع ١١ مساءً بيبقى «متأخر يوم» الساعة ١ صباحًا — وده الصح للمخزن. الحساب من toCairo، لأن iso.slice(0,10) كان هيقفل اليوم الساعة ٣ صباحًا بتوقيتنا.
• v2.3.0 — الأرقام النسبية بتتحدّث في مكانها (data-rdy-since · data-rdy-age) مش بإعادة رسم الجدول — إعادة الرسم بتصفّر تمرير الجدول تحت إيد الموظف. النبضة بتقف عند الخروج (rdyStopTicker).
• v2.3.0 — الترتيب الافتراضي للطابور بقى تاريخ الأوردر تصاعديًا في الواجهة (rdyDefaultSort). الـ Worker لسه بيرجّع الأحدث أولاً — الترتيب الافتراضي قرار واجهة عشان يتغيّر من غير deploy للـ Worker.
• v2.4.0 — تحديث تلقائي كل ١٥ دقيقة — النداء الدوري الوحيد في الأداة، وقرار مقصود. مابيستعلمش والطابور مش معروض: بيعلّم rdyDirty والجلب بيحصل أول ما الموظف يرجع، فمافيش استعلام على قايمة محدش شايفها ولا إعادة رسم تحت إيد موظف بيغلّف. العدّاد بيتسلّح من جديد بعد كل جلب ناجح — «١٥ دقيقة من آخر تحديث» مش من الدخول.
• v2.4.0 — المندوب بيتعرض زي ما هو. لحد v2.3.0 كانت أي قيمة غير Bosta بتتعرض «قاهرة» — يعني مندوب باسمه كان بيتقري غلط. دلوقتي النص من الميتافيلد كما هو، واللون هو اللي بيصنّف (بوسطة أحمر · شو روم أخضر · غيرهم أزرق)، والفاضي نصّه صريح «لا يوجد مندوب مسجل».
• v2.4.0 — custom.zone بيتجاب من Worker v2.3.0. القيمة الغايبة وBLANK الاتنين بيتعرضوا تحذير برتقالي مش خانة فاضية — منطقة ناقصة قرار شحن ناقص. وأي قيمة مش في الـ choice list بتتعرض زي ما هي ببادج محايد: ما بنترجمش قيمة معرفناهاش وما بنخبّيهاش.
• v2.4.0 — الترجمة بتحصل مرة واحدة وقت بناء الصف (zone + zoneCls)، مش وقت الرسم. لو الرسم ترجم تاني، هيترجم نص عربي مترجم أصلاً والبادج هيفقد لونه.
• v2.4.0 — صندوق الأعداد مابيختفيش في أي حالة، لأنه بقى شايل زرار التحديث ولوحة «آخر تحديث». وقبل أول جلب ناجح الأعداد «—» مش «0»: «ما اتحدّثش» مش «مفيش شغل».
• v2.4.0 — زراير عمود «خيارات» لينكات خارجية بس (target="_blank") — مفيش أي أكشن على الأوردر ومفيش نداء للـ Worker. لو حد ضاف أكشن هناك بعدين، لازم يعدّي على حارس التغليف زي أي كتابة تانية.
• v2.2.0 — منطق الطابور والتغليف بيقروا نفس الميتافيلدات، وclassifyS2Subtype بقت نسخة واحدة في الـ Worker. قبل الدمج كانت في ملفين، وده اللي خلّى إصلاح refundedIds يتعمل في أداة ويفضل مكسور في التانية لشهور.
• v2.5.0 — مدخل تالت: ماسح باركود بوسطة. رقم التتبع بيتبعت للـ Worker (get_order?tracking=)، والـ Worker بينادي بوسطة قراءة بحتة، بيطلّع businessReference، بينضّفه من الـ # وبيكمّل بنفس مسار الاسم بالحرف — نفس التصنيف ونفس حارس «اتغلّف قبل كده». مفيش مسار تغليف تاني: مسار موازي كان معناه حارسين يفترقوا، وده اللي أنتج R3.
• v2.5.0 — BOSTA_API_KEY سر جديد مطلوب على الـ Worker. من غيره مدخل بوسطة بس هو اللي بيفشل، وبرسالة باسم المتغيّر مش بـ«الشحنة غير موجودة» — و🩺 فحص النظام بيعرض وجوده.
• v2.5.0 — التلات مداخل جنب بعض بالتساوي، وكل واحد بلونه: شوبيفاي أزرق · بوسطة أحمر · اليدوي محايد. اللون هو التمييز — الموظف بيختار المربع من لون الملصق اللي في إيده.
• v2.5.0 — الفوكس بيرجع لآخر مربع اتشتغل منه (lastEntryMode): موظف شغّال دفعة ملصقات بوسطة مايرجعش بإيده للمربع بعد كل أوردر. في ذاكرة الصفحة بس — مش في التخزين المحلي — فموظف جديد بيبدأ من الافتراضي.
• v2.5.0 — مربعات المناطق في نص صندوق الأعداد = فلتر بضغطة. العدد جوّه المربع من الطابور كله مش من المفلتر: لو اتحسب على المفلتر، أول ضغطة كانت هتصفّر باقي المربعات فمحدش يقدر يرجّع. والضغط بينادي نفس rdyMsToggleItem('zone', …) — حالة واحدة مع فلتر «المنطقة»، مش حالة موازية.
• v2.5.0 — قسم الفلاتر مقفول افتراضيًا، و«المنطقة» بقت أول فلتر. قيمة الفلتر هي النص المترجم المعروض في العمود، مش قيمة الميتافيلد.
• v2.5.0 — نوع الأوردر بقى نص عادي بنفس الألوان بدل بادج، والمندوب الفاضي بقى «غير محدد»، وزرار «طباعة» بقى «إعادة» (نفس الرابط — لسه لينك خارجي بلا أكشن).
• v2.6.0 — رقم الأوردر في شاشة التغليف بقى لينك لشوبيفاي (قاعدة #20) — نفس orderLink() اللي في الجدول وتاب السجل. ولو الأوردر جه من غير id، بيتعرض نص عادي (.no-link) مش لينك مكسور.
• v2.6.0 — عمود المحاولة بقى نص عادي بنفس الألوان بدل بادج — زي نوع الأوردر.
• v2.6.0 — أيقونة زرار «إعادة» بقت SVG (RDY_PRINT_ICON) بترث لون الزرار. الإيموجي 🖨 (U+1F5A8) مش مدعوم على أجهزة كتير وكان بيطلع مربع فاضي — ممنوع الرجوع لإيموجي هنا.
• v2.6.2 — عمود «المنطقة» (custom.zone) اتشال نهائيًا من الجدول والفلاتر (قرار أحمد 05-09-2026) — مش موقوف مؤقتًا، محذوف. الـ Worker لسه بيرجّع zone في get_ready_orders، بس الواجهة بقت متجاهلاه تمامًا.
• v2.6.2 — مربعات المنطقة فوق الجدول اتبدّلت بمربعين على عمود المندوب: «بوسطة» (أحمر، نفس .courier-bosta) لو المندوب Bosta، و«مناديب» (أزرق، نفس .courier-other) لأي مندوب تاني حتى لو مفيش مندوب مسجل خالص. الشو روم بقى داخل «مناديب» هنا رغم إنه أخضر في عمود المندوب — التقسيم في المربعات ثنائي بس (بوسطة/غير بوسطة).
• v2.6.2 — نفس مبدأ v2.5.0: المربعان **حالة واحدة** مع فلتر «المندوب» التفصيلي (بقى أول فلتر بدل المنطقة) — الضغط بيحدد/يلغي كل قيم المندوب الحقيقية اللي بتقع في المجموعة دي جوّه rdyMsState.courier.selected، مش حالة موازية.
• فخّ v2.5.0: §BOSTA اتنقل حرفيًا من ريبو Bosta-Orders-Shipped-Scanner، فالكود ده بقى في مكانين. أي إصلاح على شكل رد بوسطة أو على cleanOrderName لازم يتعمل في الاتنين — نفس عيلة خطر classifyS2Subtype.
• فخّ: منطق الـ multi-select والترتيب متكرر بين §LOG-JS و§READY-JS (الأول server-side والتاني client-side). أي تعديل على سلوك القوايم أو الترتيب لازم يتعمل في الاتنين.
• فخّ v1.27.0: §LABEL-MACHINE مكرّرة عن قصد بين Orders-Packing-Checker.html وOrder-SKU-Barcode-Printer.html (قرار أحمد 16-09-2026). الفشل لو افترقوا مالوش صوت: الليبل بيتقص من تحت في صمت وبياكل من خطوط الباركود، والسكانر بيبطّل يقرا. أي تعديل يتعمل في الاتنين في نفس التمريرة، والتحقق بـbash docs/label-twin-check.sh.
• v1.27.0: الطباعة من هنا مابتكتبش أي صف في D1 (قرار أحمد) — الصفحة مابتناديش log_print ولا Worker الباركود خالص، وPAGE_WORKERS فضلت ['pack'].
• isPrintedNotPacked بتسأل «اتطبع بعد آخر تغليف؟» مش «متملّي ولا فاضي» — ميتافيلدات التغليف مبتتصفّرش بين دورات الإرجاع، والمقارنة بـ new Date() مش نصوص (printing_time بتيجي بصيغتين).