إعداد طابعة الإيصالات: كيفية الاتصال وطباعة الطلبات

Print Agent في RestaurantManage هو خدمة Windows خفيفة تستقبل أوامر الطباعة من السحابة وترسلها إلى الطابعة الحرارية الخاصة بك — مما يتيح طباعة الإيصالات تلقائياً عند تأكيد الدفع أو عند الحاجة إلى طباعة تذاكر المطبخ. يدعم الوكيل طابعات الشبكة (TCP المنفذ 9100) وطابعات USB واتصالات Windows Spooler. يغطي هذا الدليل التثبيت والتهيئة واتصال الطابعة واستكشاف الأخطاء وإصلاحها.

كيف تعمل طباعة الإيصالات؟

سير عمل الطباعة آلي بالكامل. عندما يؤكد أمين الصندوق الدفع أو يتم تشغيل تذكرة المطبخ، تقوم الواجهة الخلفية لـ RestaurantManage بإنشاء الإيصال الكامل كأوامر بايت ESC/POS. تُرسل هذه البايتات عبر اتصال WebSocket آمن (PrintHub) إلى Print Agent الذي يعمل على جهاز كمبيوتر Windows في مطعمك. يفك الوكيل تشفير البيانات ويعيد توجيهها مباشرة إلى الطابعة الحرارية المتصلة. تستغرق العملية بأكملها أقل من ثانيتين من تأكيد الدفع إلى طباعة الإيصال.

خط أنابيب الطباعة الكامل

فهم خط الأنابيب الكامل يساعد في استكشاف الأخطاء وإصلاحها. إليك تسلسل الأحداث في كل مرة يُطبع فيها إيصال أو تذكرة مطبخ:

1. تأكيد الدفع: يضع أمين الصندوق علامة على الطلب بوصفه مدفوعاً، أو يتم تشغيل تذكرة مطبخ يدوياً.
2. تنسيق الإيصال في الخلفية: يشغّل الخادم ReceiptFormattingService الذي يبني تخطيط الإيصال باستخدام ReceiptBuilder ويحوّله إلى أوامر بايت ESC/POS عبر EscPosCommands وEscPosRasterEncoder.
3. إرسال البيانات عبر PrintHub: تُبث بايتات الإيصال المنسقة (مشفرة بـ Base64) عبر قناة WebSocket آمنة (SignalR PrintHub) إلى Print Agent الصحيح المُعرَّف بمعرّف مطعمك.
4. استقبال Print Agent للمهمة: تستقبل خدمة Windows التي تعمل على جهاز الكمبيوتر المحلي الحمولة بـ Base64، وتفكك تشفيرها إلى بايتات ESC/POS الخام، وتحدد الطابعة التي ستُستخدم.
5. مخرجات الطابعة: تُرسل البايتات المفككة مباشرة إلى الطابعة الحرارية عبر TCP الشبكي أو Windows Spooler أو USB، ويُطبع الإيصال في غضون ثوانٍ.

ما الذي يتضمنه الإيصال المطبوع

يتضمن كل إيصال تنشئه RestaurantManage مجموعة كاملة من تفاصيل المعاملة. يعرض الرأس اسم المطعم وعنوانه وشعاره (إن تم تهيئته). يتضمن الجسم رقم الطاولة وقائمة مرقمة بجميع العناصر المطلوبة مع الكميات والأسعار الفردية وأي خصومات وتفصيلاً ضريبياً مصنّفاً. يعرض التذييل إجمالي الطلب وطريقة الدفع (نقداً أو بطاقة وما إلى ذلك) وتاريخ الدفع ووقته ورسالة شكر اختيارية. تتبع تذاكر المطبخ تنسيقاً مبسطاً يعرض رقم الطاولة وأسماء العناصر والكميات وأي ملاحظات.

متى يتم تشغيل الإيصالات

تُطبع إيصالات العملاء تلقائياً عندما يؤكد أمين الصندوق الدفع الكامل أو الجزئي لطلب ما. تُطبع تذاكر المطبخ عند تقديم طلب جديد من لوحة أمين الصندوق أو تطبيق النادل المحمول. في كلتا الحالتين، تعالج الخلفية مهمة الطباعة بالكامل وتوجّهها إلى Print Agent تلقائياً. يمكن للموظفين المخوّلين أيضاً بدء إعادة طباعة من لوحة الإدارة إذا فاتت الطباعة الأصلية أو كانت مشوّهة.

كيف أثبّت Print Agent؟

يستغرق التثبيت حوالي خمس دقائق على أي جهاز كمبيوتر حديث يعمل بنظام Windows. يجب أن يظل جهاز الكمبيوتر في وضع التشغيل خلال ساعات عمل المطعم لأن Print Agent يعمل كخدمة Windows في الخلفية.

1. التنزيل: احصل على أحدث مثبّت لـ Print Agent من لوحة الإدارة أو تواصل مع الدعم.
2. التثبيت: شغّل المثبّت على جهاز كمبيوتر Windows سيظل في وضع التشغيل خلال ساعات الخدمة.
3. التهيئة: افتح config.json وأدخل عنوان URL الأساسي لواجهة برمجة التطبيقات ومعرّف المطعم ومفتاح الوكيل السري (الذي يوفره المسؤول).
4. توصيل الطابعة: وصّل الطابعة الحرارية عبر USB أو اربطها بنفس الشبكة التي يتصل بها الكمبيوتر.
5. بدء الخدمة: شغّل Print Agent — فيتصل بـ PrintHub تلقائياً ويعرض مؤشر حالة أخضر.
6. طباعة اختبارية: أجرِ دفعة اختبارية من لوحة أمين الصندوق وتحقق من طباعة الإيصال بشكل صحيح.

متطلبات النظام

يتطلب Print Agent موارد أجهزة بسيطة لكنه يعتمد على نظام تشغيل وبيئة تشغيل مدعومَين:

• نظام التشغيل: Windows 10 (الإصدار 1909 أو أحدث) أو Windows 11. Print Agent خدمة مخصصة لنظام Windows فقط ولا تعمل على macOS أو Linux.
• بيئة التشغيل: يجب تثبيت .NET 8 Runtime. سيطلب منك المثبّت تنزيله إذا لم يكن موجوداً — وهو مجاني من Microsoft.
• اتصال الإنترنت: مطلوب اتصال إنترنت مستقر للتواصل مع سحابة RestaurantManage. يعيد الوكيل الاتصال تلقائياً بعد الانقطاعات القصيرة.
• الوصول إلى الشبكة: يجب أن يتمكن الكمبيوتر من الوصول إلى الطابعة — إما عبر كابل USB أو على نفس قطاع الشبكة المحلية.
• المعالج والذاكرة العشوائية: أي معالج حديث مع 512 ميغابايت على الأقل من الذاكرة العشوائية المتاحة كافٍ. الوكيل خفيف جداً.

التشغيل كخدمة Windows

للاستخدام في بيئة الإنتاج، يجب تثبيت Print Agent كخدمة Windows حتى يبدأ تلقائياً عند تشغيل الكمبيوتر — حتى قبل تسجيل دخول المستخدم. لتسجيله كخدمة، انقر بزر الماوس الأيمن على install-service.bat واختر تشغيل كمسؤول. يُسجّل هذا الوكيل باسم RestaurantPrintAgent في مدير التحكم بخدمات Windows. بعد التثبيت، يمكنك إدارته من لوحة الخدمات (services.msc) أو من سطر الأوامر باستخدام sc start RestaurantPrintAgent وsc stop RestaurantPrintAgent. لإزالة الخدمة، شغّل uninstall-service.bat كمسؤول.

العثور على معرّف المطعم والمفتاح السري

معرّف المطعم هو المعرّف الفريد لمطعمك في نظام RestaurantManage. يمكن العثور عليه في لوحة الإدارة ضمن الإعدادات → معلومات المطعم. مفتاح الوكيل السري بيانات اعتماد منفصلة تُصادق على Print Agent مع نقطة نهاية WebSocket الخاصة بـ PrintHub — وليس نفس كلمة مرور المستخدم. لإنشاء مفتاح سري أو إعادة إنشائه، انتقل إلى الإعدادات → Print Agent في لوحة الإدارة وانقر على إنشاء مفتاح جديد. انسخ المفتاح فوراً والصقه في config.json — لن يظهر مجدداً بعد التنقل. إذا فقدت المفتاح، ما عليك سوى إنشاء مفتاح جديد؛ سيُبطَل المفتاح القديم تلقائياً.

ما أنواع اتصال الطابعة المدعومة؟

يدعم Print Agent ثلاث طرق اتصال مع آلية احتياط تلقائية بينها. تدعم طابعات الشبكة وطابعات USB واتصالات Windows Spooler جميعها. يجرّب الوكيل Spooler أولاً ثم ينتقل إلى USB المباشر وأخيراً يحاول مشاركات شبكة UNC.

طابعات الشبكة (موصى بها)

طابعات الشبكة هي طريقة الاتصال الموصى بها لمعظم المطاعم. تمتلك الطابعة الحرارية المتصلة بالشبكة عنوان IP خاصاً بها وتقبل بيانات الطباعة الخام على TCP المنفذ 9100 — المنفذ القياسي لطباعة ESC/POS. للإعداد، وصّل الطابعة بجهاز التوجيه أو المبدّل بكابل Ethernet، ثم استخدم صفحة التهيئة المدمجة أو قائمة اللوحة الأمامية لتعيين عنوان IP ثابت (مثل 192.168.1.100). أدخل هذا العنوان والمنفذ 9100 في تهيئة Print Agent. العنوان الثابت مهم — إذا حصلت الطابعة على عنوان IP جديد من DHCP في كل مرة تُعاد تشغيلها، ستفشل مهام الطباعة.

طابعات USB وWindows Spooler

تتصل الطابعات الحرارية USB مباشرة بجهاز كمبيوتر Windows الذي يشغّل Print Agent. بعد توصيل كابل USB، ثبّت برنامج تشغيل Windows من الشركة المصنّعة إذا لزم الأمر (تستخدم معظم طابعات ESC/POS الحديثة برنامج تشغيل عام مدمج في Windows). يكتشف Print Agent الطابعة عبر Windows Spooler. إذا لم تظهر الطابعة في Spooler، يمكن تجربة طريقة عنونة USB المباشرة: يمكن للوكيل الكتابة مباشرة إلى مسارات أجهزة USB مثل \\?\USB001 أو مسارات المنافذ الموازية مثل LPT1.

ترتيب الاحتياط التلقائي

عند استلام مهمة طباعة، يجرّب Print Agent طرق الاتصال بهذا الترتيب: 1) Windows Spooler — إذا كانت الطابعة مسجلة في Windows ويمكن الوصول إليها عبر Spooler، يُستخدم هذا الأسلوب أولاً. 2) USB المباشر — إذا فشل Spooler، يحاول الوكيل الكتابة مباشرة إلى مسارات أجهزة USB (USB001، USB002 إلخ) ومنافذ LPT. 3) مشاركة شبكة UNC — كملاذ أخير، يحاول الوكيل الوصول إلى الطابعة عبر مسار مشاركة شبكة Windows. إذا فشلت الطرق الثلاث، يُسجَّل الخطأ في مجلد logs/ مع التفاصيل.

كيف أهيّئ Print Agent؟

يتم تهيئة Print Agent من خلال ملف config.json واحد موجود في دليل التثبيت. جميع الإعدادات نص عادي وتصبح نافذة المفعول في المرة التالية التي تبدأ فيها الخدمة (أو تُعاد تشغيلها). لا توجد واجهة رسومية للتهيئة — يكفي تحرير الملف بأي محرر نصوص.

شرح ملف config.json

يحتوي ملف التهيئة على ثلاثة حقول مطلوبة وإعدادات طابعة اختيارية:

• ApiBaseUrl: عنوان URL الأساسي لخادم RestaurantManage، مثل <code>https://restaurantmanage.xyz</code>. لا تضف شرطة مائلة في النهاية. يستخدم Print Agent هذا العنوان للاتصال بـ PrintHub والتحقق من التحديثات.
• RestaurantId: المعرّف الفريد لمطعمك. يمكن العثور عليه في لوحة الإدارة ضمن الإعدادات → معلومات المطعم.
• AgentSecretKey: المفتاح السري الذي يُنشأ في لوحة الإدارة ضمن الإعدادات → Print Agent. يُصادق هذا المفتاح على الوكيل مع الخادم دون الحاجة إلى تسجيل دخول مستخدم. احتفظ به سراً.

يبدو مثال كامل لـ config.json هكذا: {"ApiBaseUrl": "https://restaurantmanage.xyz", "RestaurantId": "معرف-مطعمك", "AgentSecretKey": "مفتاحك-السري"}. بعد تحرير الملف، أعد تشغيل خدمة Print Agent لتصبح التغييرات نافذة المفعول.

تهيئة اسم الطابعة وعنوان IP

لطابعات الشبكة، تحتاج إلى عنوان IP الطابعة. للعثور عليه: تطبع معظم الطابعات الحرارية صفحة تهيئة عند الضغط على زر التغذية أثناء تشغيل الجهاز — عنوان IP مدرج هناك. بدلاً من ذلك، تحقق من قائمة عملاء DHCP في جهاز التوجيه للعثور على اسم مضيف الطابعة. بمجرد حصولك على عنوان IP، عيّنه كعنوان ثابت في إعدادات شبكة الطابعة. بالنسبة لطابعات Windows Spooler، يجب أن يتطابق اسم الطابعة تماماً مع ما يظهر في إعدادات Windows → الطابعات والماسحات الضوئية.

ملفات السجل والتشخيص

يكتب Print Agent سجلات مفصّلة في المجلد الفرعي logs/ داخل دليل التثبيت. تُسمّى ملفات السجل حسب التاريخ (مثل log-2026-04-06.txt) وتتدوّر يومياً. تتضمن كل إدخال سجل طابعاً زمنياً ومستوى خطورة (معلومات، تحذير، خطأ) ووصفاً لما حدث. إذا كنت تستكشف أخطاء الطباعة، راجع ملف السجل لتاريخ المشكلة — رسالة الخطأ الدقيقة ستشير إلى ما إذا كانت المشكلة متعلقة بالشبكة أو المصادقة أو الطابعة.

كيف يعمل التحديث التلقائي؟

يتحقق Print Agent من التحديثات تقريباً كل 2.5 ساعة باستدعاء نقطة نهاية التحديث على خادم RestaurantManage. إذا كان إصدار جديد متاحاً، يقوم بتنزيل حزمة التحديث كملف ZIP إلى مجلد التحديثات المعلّقة، ويشغّل نص برمجي للتثبيت، ويُعيد تشغيل الخدمة تلقائياً. هذا يعني أن مطعمك يشغّل دائماً أحدث إصدار دون تدخل يدوي. تتضمن فحوصات التحديث تأخيراً زمنياً لكل مطعم لتجنب تحديث جميع الوكلاء في نفس الوقت.

استكشاف المشكلات الشائعة وإصلاحها

تقع معظم مشاكل الطباعة في إحدى الفئات الثلاث: مشاكل الاتصال، مشاكل أجهزة الطابعة، أو أخطاء التهيئة. ملفات السجل في مجلد logs/ هي أفضل نقطة بداية لتشخيص أي مشكلة.

أخطاء الاتصال والمصادقة

• لا يتصل الوكيل بالخادم: تحقق من أن ApiBaseUrl في config.json صحيح ويمكن الوصول إليه من الكمبيوتر. افتح متصفحاً على نفس الكمبيوتر وانتقل إلى عنوان URL لواجهة برمجة التطبيقات — يجب أن ترى استجابة. تحقق من أن للكمبيوتر اتصالاً نشطاً بالإنترنت.
• فشل المصادقة (خطأ 401 في السجلات): AgentSecretKey غير صحيح أو تمت إعادة إنشائه. سجّل الدخول إلى لوحة الإدارة وأنشئ مفتاحاً جديداً ضمن الإعدادات → Print Agent، وحدّث config.json، وأعد تشغيل الخدمة.
• الاتصال ينقطع ويُعيد الاتصال بشكل متكرر: يشير هذا عادةً إلى مشكلة عدم استقرار الشبكة. انتقل من Wi-Fi إلى Ethernet السلكي. تحقق مما إذا كان جدار الحماية أو برنامج مكافحة الفيروسات يحجب اتصالات WebSocket الصادرة (يستخدم الوكيل HTTPS المنفذ 443).
• الوكيل يتصل لكنه لا يستقبل مهام طباعة: تحقق من أن معرّف المطعم في config.json يطابق تماماً المعرّف في لوحة الإدارة (حساس لحالة الأحرف). تحقق أيضاً من أن Print Agent مُفعَّل في الإعدادات → Print Agent.

مشاكل جودة الطباعة والترميز

• أحرف أو رموز مشوهة على الإيصال: قد لا تدعم طابعتك الحرارية مجموعة أوامر ESC/POS المستخدمة في RestaurantManage بالكامل. تحقق من وثائق الطابعة للتأكد من التوافق. معظم الطابعات الحرارية بعرض 58 ملم و80 ملم المصنّعة بعد عام 2015 متوافقة.
• يُطبع الإيصال لكن النص مقطوع: قد يكون إعداد عرض الورق غير صحيح. تُنسّق RestaurantManage الإيصالات لورق 80 ملم افتراضياً. إذا كنت تستخدم طابعة 58 ملم، تواصل مع الدعم لتفعيل وضع الورق الضيق.
• يُطبع الإيصال فارغاً أو بمحتوى جزئي فقط: قد يشير هذا إلى لفة ورق منخفضة أو رأس طباعة مسدود. استبدل الورق ونظّف رأس الطباعة بقطعة قماش جافة. إذا استمرت المشكلة، اختبر الطابعة مباشرة من Windows لعزل المشكلة.
• الأحرف الخاصة أو نص RTL لا يُطبع بشكل صحيح: تأكد من ضبط مجموعة أحرف طابعتك على UTF-8 أو صفحة الرموز المناسبة للغتك. يمكن الوصول عادةً إلى هذا الإعداد من قائمة تهيئة الطابعة.

أعطال بدء تشغيل الخدمة

• الوكيل لا يبدأ كخدمة Windows: يجب تشغيل install-service.bat كمسؤول (انقر بزر الماوس الأيمن → تشغيل كمسؤول). بدون صلاحيات مرفوعة، لا يمكن تسجيل الخدمة في مدير التحكم بخدمات Windows.
• الخدمة تبدأ ثم تتوقف فوراً: تحقق من عارض أحداث Windows (eventvwr.msc) ضمن سجلات Windows → التطبيق لرسائل الخطأ من RestaurantPrintAgent. تحقق أيضاً من مجلد logs/ للأخطاء التي تحدث عند البدء. الأسباب الشائعة هي ملف config.json المفقود أو المشوّه، أو بيئة تشغيل .NET 8 المفقودة، أو تعارض المنافذ.
• بيئة التشغيل .NET مفقودة: نزّل وثبّت .NET 8 Runtime من https://dotnet.microsoft.com. بعد التثبيت، أعد تشغيل خدمة Print Agent.
• جدار الحماية يحجب الوكيل: قد يحجب Windows Defender أو جدار حماية خارجي الاتصال الصادر للوكيل. أضف استثناءً للملف التنفيذي لـ Print Agent في إعدادات جدار الحماية.

أدلة ذات صلة

• لوحة أمين الصندوق: كيفية معالجة المدفوعات التي تُشغّل طباعة الإيصالات
• شاشة المطبخ: كيفية تكامل طباعة تذاكر المطبخ مع سير الطلبات
• البدء: دليل إعداد كامل من التسجيل إلى أول طلب