الفصل 3 — تطبيق Bridge (جسر ربط العتاد)

يعمل صندوق البيع داخل المتصفح، والمتصفح لا يستطيع التخاطب مباشرةً مع قارئ البطاقات، والطابعة، والميزان، وشاشة عرض العميل. تطبيق Bridge هو هذا الجسر: يعمل بجانب الصندوق ويربط هذه الأجهزة بالصندوق.

له ثلاثة أشكال تؤدي جميعها المهمة نفسها (نسخة iOS تجريبية):

• تطبيق Android على الجهاز اللوحي
• تطبيق سطح المكتب على الحاسوب (Windows/Mac/Linux)
• تطبيق iOS (تجريبي)

⚠️ اللغة: واجهة تطبيق Android عمليًا بالإنجليزية. لم يُترجَم إلى الألمانية سوى بضع سلاسل قديمة؛ أما لوحة التحكم كاملةً التي يراها المشغّل (الحالات، وPower Guard، وKeep Bridge Awake، والسجلات وغيرها) فبالإنجليزية.

💡 عادةً تُعِدّ Bridge مرة واحدة ثم يعمل في الخلفية. تُدخِل عنوان Bridge في الصندوق ← الإعدادات ← Bridge (دليل الصندوق، الفصل 9). ويعمل تطبيق Android كـخدمة أمامية مستقرة: يبقى حيًّا حتى مع إغلاق التطبيق من القائمة، ويعاود العمل تلقائيًا بعد التحديث، ويقوم مراقب كل 30 ثانية بإعادة تشغيل الخادم عند الحاجة.

3-1. تطبيق Android — صفحة الحالة

صفحة بملء الشاشة (كشك) بها سطر ملخّص في الأعلى وعدة بطاقات حالة. أثناء التشغيل ترى رسالة «جارٍ تهيئة الجسر، وربط قارئ البطاقات وشاشة عرض العميل».

• الملخّص العام أعلى الصفحة، مثلًا: «الجسر جاهز للدفع»، و«قارئ البطاقات جاهز، بانتظار المتصفح»، و«اتصل المتصفح / قارئ البطاقات دون اتصال»، و«جارٍ استعادة اتصال قارئ البطاقات»، أو «معاملة قيد التنفيذ».
• بطاقات الحالة (لكلٍّ منها نقطة ملوّنة وكلمة حالة):
• WebSocket — المنفذ المحلي الذي يتصل به الصندوق.
• المتصفح (Browser) — هل اتصل الصندوق.
• قارئ البطاقات (POS Terminal) — الحالات: منقطع / جارٍ الاتصال / جارٍ إعادة الاتصال / متصل / مشغول (Busy) أثناء المعاملة.
• شاشة عرض العميل — حالة الشاشة الثانية.
• Power Guard — حماية البطارية/المعالج/الواي فاي لمنع الانقطاع أثناء الخمول.

بطاقة عنوان Bridge

• تعرض العنوان (المحلي 127.0.0.1:PORT أو عنوان الشبكة مع IP الجهاز) الذي يجب إدخاله في الصندوق.
• زر وضع الاتصال ثلاثي الحالات ويتنقّل مع كل ضغطة: محلي ← شبكة ← تلقائي (Auto). يذهب الوضع التلقائي إلى الشبكة إذا توفّر عنوان شبكة محلي، وإلى المحلي في غير ذلك.
• الضغط المطوّل على زر وضع الاتصال: إنشاء أو مسح رمز الاقتران — رمز من 6 أحرف يُضاف إلى العنوان (?token=XXXXXX) كي لا يتصل سوى الصندوق المصرّح له. ولا يُطبَّق هذا الرمز إلا في وضع الشبكة (ويُتجاهَل في الوضع المحلي)، ويُعرَض في العنوان بصيغة «Paired/Open».

سائر البطاقات والدخول إلى السجل

• Power Guard ← «إبقاء الجسر مستيقظًا» (Keep Bridge Awake): يفتح إعدادات بطارية Android كي لا ينقطع Bridge أثناء الخمول.
• السجلات: تُفعَّل/تُعطَّل بزر Enable/Disable Logs، ويفتح View Logs صفحة السجل؛ ويؤدي التعطيل إلى مسح السجلات المحفوظة. والطريقة الثانية لفتح السجل هي الضغط المطوّل (long-press) على الشريط أعلى الصفحة.
• صفحة السجل: للقراءة فقط — نص أحادي العرض يتحدّث كل ثانية ويُمرَّر إلى الأسفل؛ بلا زر مشاركة/تصدير (للإرسال إلى الدعم، يجب النسخ يدويًا).
• صفحة شاشة عرض العميل: تعرض على الشاشة الثانية أصنافَ الطلب وإجماليَه للعميل بقالب ويب. وفي Android تلتصق تلقائيًا بأي شاشة ثانية متصلة (دون اختيار يدوي؛ وتُزال عند فصل الكابل).

3-2. تطبيق سطح المكتب — «LonioBridge — Host»

نافذة تحكّم صغيرة لتشغيل Bridge على الحاسوب:

• نموذج الإعداد:
• منفذ WebSocket (الافتراضي 8088)
• عنوان الربط (Bind): هذا الحاسوب فقط أو الشبكة كاملةً (الافتراضي 0.0.0.0).
• شاشة عرض العميل: اختيار يدوي للشاشة التي ستكون شاشة عرض العميل (أو بلا شيء).
• تشغيل/إيقاف لتشغيل الجسر؛ وتُحفَظ الإعدادات في الملف ~/.loniobridge/host.properties بين مرات التشغيل.
• التشغيل التلقائي (Autostart): عبر المعامل --autostart (يضبطه المُثبِّت على Windows بسكربتات التفعيل/التعطيل كي يعمل عند تشغيل النظام).
• وضع بلا نافذة (Console): يمكن التشغيل بلا واجهة رسومية عبر --console.
• لوحة الحالة: حالة الخادم (متوقف / جارٍ البدء / جارٍ الإصغاء على المنفذ / منفذ غير صالح / خطأ)، وعدد الصناديق المتصلة، وحالة قارئ البطاقات، ومؤشّر مشغول/خامل (أثناء المعاملة).
• تقرير النشاط: سجل مؤرّخ للأحداث؛ وخيار Verbose لتسجيل الإطارات الخام لقارئ البطاقات (لتصحيح الأخطاء فقط).

⚠️ لا يوجد في نافذة سطح المكتب اختيار للطابعة أو الميزان؛ فقط المنفذ وعنوان الربط وشاشة عرض العميل. أما الطابعة والميزان فيُضبَطان من جهة الصندوق، ويقوم Bridge بتشغيلهما وفق رسالة الصندوق.

3-3. أي أجهزة تتصل

• قارئ البطاقات: يوجد مشغّلان يُختاران في ملف تعريف الطرفية:
• ZVT (الافتراضي) — عبر الشبكة/TCP، مع إعادة اتصال تلقائية (backoff) وحالات جارٍ الاتصال/الاستعادة/متصل.
• GP Tom (SoftPOS) — مشغّل Global Payments الذي يتخاطب على جهاز Android اللوحي نفسه مع تطبيق قارئ بطاقات GP (بيع/إبطال/إرجاع؛ التسوية اليومية عبر مسار App2App هذا غير مدعومة بعد).
• شاشة عرض العميل: قالب ويب (أصناف الطلب وإجماليه) يرسله الصندوق إليها؛ يلتصق Android تلقائيًا، وسطح المكتب باختيار الشاشة يدويًا.
• الطابعة:
• ⚠️ على Android، تُقبَل الطباعة حاليًا فقط لكن التنفيذ الفعلي للطباعة غير مُطبَّق؛ أما الطباعة الفعلية فتعمل على سطح المكتب.
• لسطح المكتب ثلاث طرق: تسلسلي (Serial)، وطابعة النظام (Windows)، والشبكة/TCP (الافتراضي، المنفذ 9100)؛ ويشمل ذلك قطع الورق وفتح درج النقود.
• الميزان: على سطح المكتب فقط — تسلسلي أو USB-HID، مع كشف الوحدة (kg/g/lb/oz) وحالة مستقرة/غير مستقرة. أما Android فلا ميزان له.

3-4. الإعداد الذي يجب أن يعرفه القائم بالإعداد

• المنفذ (الافتراضي 8088) وعنوان الربط (محلي مقابل شبكة).
• الفرق بين 127.0.0.1 (المحلي) وIP الشبكة: إذا كان الصندوق على الجهاز نفسه، فالمحلي يكفي؛ وإذا كان على جهاز آخر، فيلزم وضع الشبكة + IP، ويجب أن يكون كلاهما على الشبكة نفسها.
• رمز الاقتران (?token=…) في وضع الشبكة فقط.
• إعدادات بطارية Android (Keep Bridge Awake) لمنع الانقطاع.

3-5. استكشاف الأخطاء السريع