فصل ۳ — برنامه Bridge (پل اتصال سخت‌افزار)

صندوق فروش در مرورگر اجرا می‌شود و مرورگر نمی‌تواند مستقیم با کارت‌خوان، پرینتر، ترازو و نمایشگر مشتری حرف بزند. برنامه Bridge این پل است: کنار صندوق اجرا می‌شود و این دستگاه‌ها را به صندوق وصل می‌کند.

سه شکل دارد که همگی یک کار می‌کنند (نسخه iOS آزمایشی است):

• اپ اندروید روی تبلت
• برنامه دسکتاپ روی کامپیوتر (Windows/Mac/Linux)
• اپ iOS (آزمایشی)

⚠️ زبان: رابط اپ اندروید عملاً انگلیسی است. فقط چند رشته قدیمی به آلمانی ترجمه شده‌اند؛ کل داشبوردی که اپراتور می‌بیند (وضعیت‌ها، Power Guard، Keep Bridge Awake، لاگ‌ها و…) انگلیسی است.

💡 معمولاً Bridge را یک بار راه‌اندازی می‌کنید و بعد در پس‌زمینه کار می‌کند. آدرس Bridge را در صندوق ← تنظیمات ← Bridge وارد می‌کنید (راهنمای صندوق، فصل ۹). اپ اندروید به‌صورت سرویس پیش‌زمینه پایدار اجرا می‌شود: با بستن برنامه از لیست هم زنده می‌ماند، بعد از به‌روزرسانی خودکار دوباره راه می‌افتد، و یک پایشگر هر ۳۰ ثانیه در صورت لازم سرور را دوباره بالا می‌آورد.

۳-۱. اپ اندروید — صفحه وضعیت

یک صفحه تمام‌صفحه (کیوسک) با یک خط خلاصه در بالا و چند کارت وضعیت. هنگام اجرا پیام «در حال آماده‌سازی پل، اتصال کارت‌خوان و نمایشگر مشتری» را می‌بینید.

• خلاصه کلی بالای صفحه، مثلاً: «پل آماده پرداخت»، «کارت‌خوان آماده، منتظر مرورگر»، «مرورگر وصل شد / کارت‌خوان آفلاین»، «در حال بازیابی اتصال کارت‌خوان»، یا «تراکنش در جریان است».
• کارت‌های وضعیت (هر کدام یک نقطه رنگی و یک کلمه وضعیت):
• WebSocket — درگاه محلی که صندوق به آن وصل می‌شود.
• مرورگر (Browser) — آیا صندوق وصل شده.
• کارت‌خوان (POS Terminal) — وضعیت‌ها: قطع / در حال اتصال / در حال اتصال دوباره / متصل / مشغول (Busy) هنگام تراکنش.
• نمایشگر مشتری — وضعیت نمایشگر دوم.
• Power Guard — محافظت باتری/پردازنده/وای‌فای برای جلوگیری از قطعی در بیکاری.

کارت آدرس Bridge

• آدرس را نشان می‌دهد (محلی 127.0.0.1:PORT یا آدرس شبکه با IP دستگاه) که باید در صندوق وارد شود.
• دکمه حالت اتصال، سه‌حالته است و با هر زدن می‌چرخد: محلی ← شبکه ← خودکار (Auto). حالت خودکار اگر آدرس شبکه محلی موجود باشد روی شبکه و در غیر این صورت روی محلی می‌رود.
• نگه داشتن دکمه حالت اتصال: ساخت یا پاک کردن توکن جفت‌سازی — یک کد ۶‌حرفی که به آدرس اضافه می‌شود (?token=XXXXXX) تا فقط صندوق مجاز بتواند وصل شود. این توکن فقط در حالت شبکه اعمال می‌شود (در حالت محلی نادیده گرفته می‌شود) و در آدرس به‌صورت «Paired/Open» نشان داده می‌شود.

سایر کارت‌ها و ورود به لاگ

• Power Guard → «بیدار نگه‌داشتن پل» (Keep Bridge Awake): تنظیمات باتری اندروید را باز می‌کند تا Bridge در بیکاری قطع نشود.
• لاگ‌ها: با دکمه Enable/Disable Logs روشن/خاموش می‌شود و View Logs صفحه لاگ را باز می‌کند؛ خاموش کردن، لاگ‌های ذخیره‌شده را پاک می‌کند. راه دوم برای باز کردن لاگ، نگه داشتن (long-press) روی نوار بالای صفحه است.
• صفحه لاگ: فقط‌خواندنی است — متن تک‌عرض که هر ثانیه تازه می‌شود و به پایین اسکرول می‌کند؛ دکمه اشتراک/خروجی ندارد (برای فرستادن به پشتیبانی باید دستی کپی کنید).
• صفحه نمایشگر مشتری: روی نمایشگر دوم، اقلام و جمع سفارش را با یک قالب وب به مشتری نشان می‌دهد. در اندروید خودکار به هر نمایشگر دومِ متصل می‌چسبد (بدون انتخاب دستی؛ با جدا شدن کابل حذف می‌شود).

۳-۲. برنامه دسکتاپ — «LonioBridge — Host»

یک پنجره کوچک کنترل برای اجرای Bridge روی کامپیوتر:

• فرم راه‌اندازی:
• پورت WebSocket (پیش‌فرض ۸۰۸۸)
• آدرس اتصال (Bind): فقط این کامپیوتر یا کل شبکه (پیش‌فرض 0.0.0.0).
• نمایشگر مشتری: انتخاب دستی مانیتوری که نمایشگر مشتری باشد (یا هیچ‌کدام).
• شروع/توقف برای اجرای پل؛ تنظیمات در فایل ~/.loniobridge/host.properties بین اجراها حفظ می‌شود.
• اجرای خودکار (Autostart): با پارامتر --autostart (نصب‌کننده روی ویندوز آن را با اسکریپت‌های فعال/غیرفعال‌سازی تنظیم می‌کند تا با روشن شدن سیستم بالا بیاید).
• حالت بدون پنجره (Console): با --console می‌توان بدون رابط گرافیکی اجرا کرد.
• پنل وضعیت: حالت سرور (متوقف / در حال شروع / در حال گوش دادن روی پورت / پورت نامعتبر / خطا)، تعداد صندوق‌های متصل، وضعیت کارت‌خوان، و نشانگر مشغول/بیکار (هنگام تراکنش).
• گزارش فعالیت: لاگ زمان‌دار رویدادها؛ گزینه Verbose برای ثبت فریم‌های خام کارت‌خوان (فقط برای عیب‌یابی).

⚠️ در پنجره دسکتاپ انتخاب پرینتر یا ترازو وجود ندارد؛ فقط پورت، آدرس اتصال و نمایشگر مشتری. پرینتر و ترازو از سمت صندوق پیکربندی می‌شوند و Bridge آنها را طبق پیام صندوق راه می‌اندازد.

۳-۳. چه دستگاه‌هایی وصل می‌شوند

• کارت‌خوان: دو راه‌انداز وجود دارد که در پروفایل ترمینال انتخاب می‌شود:
• ZVT (پیش‌فرض) — از طریق شبکه/TCP، با اتصال دوباره خودکار (backoff) و وضعیت‌های در حال اتصال/بازیابی/متصل.
• GP Tom (SoftPOS) — راه‌انداز Global Payments که روی همان تبلت اندروید با اپ کارت‌خوان GP حرف می‌زند (فروش/ابطال/عودت؛ تسویه‌ی روزانه از این مسیر App2App هنوز پشتیبانی نمی‌شود).
• نمایشگر مشتری: قالب وب (اقلام و جمع سفارش) که صندوق به آن می‌فرستد؛ اندروید خودکار می‌چسبد، دسکتاپ با انتخاب دستی مانیتور.
• پرینتر:
• ⚠️ روی اندروید، چاپ فعلاً فقط پذیرفته می‌شود ولی اجرای واقعی چاپ پیاده نشده؛ چاپ واقعی روی دسکتاپ کار می‌کند.
• دسکتاپ سه راه دارد: سریال، پرینتر سیستم (ویندوز)، و شبکه/TCP (پیش‌فرض، پورت 9100)؛ شامل برش کاغذ و باز کردن کشوی پول.
• ترازو: فقط روی دسکتاپ — سریال یا USB-HID، با تشخیص واحد (kg/g/lb/oz) و حالت پایدار/ناپایدار. اندروید ترازو ندارد.

۳-۴. پیکربندی که راه‌انداز باید بداند

• پورت (پیش‌فرض ۸۰۸۸) و آدرس اتصال (محلی در برابر شبکه).
• تفاوت 127.0.0.1 (محلی) و IP شبکه: اگر صندوق روی همین دستگاه است، محلی کافی است؛ اگر روی دستگاه دیگر است، حالت شبکه + IP لازم است و هر دو باید روی یک شبکه باشند.
• توکن جفت‌سازی (?token=…) فقط در حالت شبکه.
• تنظیمات باتری اندروید (Keep Bridge Awake) برای جلوگیری از قطعی.

۳-۵. عیب‌یابی سریع