> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plato.ae/llms.txt
> Use this file to discover all available pages before exploring further.

# استكشاف الأخطاء وإصلاحها

> تشخيص مشكلات برنامج التشغيل والطابعة وقائمة الانتظار وRedis وHTTPS ووحدة التحكم.

# استكشاف الأخطاء وإصلاحها

ابدأ بأصغر مسار أولاً:

1. صحة عملية السائق.
2. إمكانية الوصول إلى برنامج التشغيل إلى الطابعة TCP.
3. حالة قائمة الانتظار.
4. تكوين الطابعة وحدة التحكم.
5. HTTPS أو مشكلات الثقة في المتصفح.

## السائق غير قابل للوصول

يفحص:

```sh theme={null}
curl http://localhost:8080/health
```

إذا فشلت الصحة المحلية:

* تأكد من تشغيل `plato-printer.exe`.
* تأكد من أن `config.json` صالح JSON.
* تأكد من عدم استخدام `server.port` بالفعل.
* تحقق من سجلات بدء التشغيل بحثًا عن `Port already in use`.

إذا مرت الصحة المحلية ولكن لا يمكن لـ POS الوصول إليها:

* افتح جدار حماية Windows لـ `server.port`.
* استخدم عنوان شبكة السائق من شعار بدء التشغيل.
* تأكد من أن جهاز POS موجود على نفس الشبكة أو أنه يسمح بشبكة VLAN.

## الطابعة غير متصل

يتصل:

```sh theme={null}
curl -X POST http://localhost:8080/status \
  -H "Content-Type: application/json" \
  -d '{"ip_address":"192.168.1.50","port":"9100","validate":true}'
```

الأسباب الشائعة:

| الخطأ الأخير                           | معنى                                       | يصلح                                                                            |
| -------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| `Connection Refused`                   | يمكن الوصول إلى المضيف ولكن المنفذ مغلق.   | تحقق من منفذ الطابعة وإعدادات TCP الأولية.                                      |
| `Connection Timeout`                   | لا يمكن الوصول إلى IP/منفذ الطابعة.        | تحقق من IP، والشبكة، وVLAN، وجدار الحماية، وطاقة الطابعة.                       |
| `Printer open timed out after 2000ms`  | لم يكتمل اتصال TCP.                        | تحقق من مسار شبكة الطابعة.                                                      |
| `Printer write timed out after 6000ms` | تم فتح المقبس ولكن لم يتم مسح الكتابة.     | أعد تشغيل الطابعة، وتحقق من المخزن المؤقت أو الشبكة أو البرامج الثابتة للطابعة. |
| `TCP connection closed`                | أغلقت الطابعة مأخذ التوصيل بشكل غير متوقع. | أعد التحقق من المنفذ الأولي للطابعة وحجم حمولة المهمة.                          |

## وظائف عالقة

فحص قوائم الانتظار:

```sh theme={null}
curl http://localhost:8080/queue-status
```

يقرأ:

* `waiting`: وظائف جاهزة ولكنها غير نشطة.
* `active`: تتم الطباعة حاليًا.
* `delayed`: المهام المستقبلية المجدولة أو إعادة المحاولة المؤجلة.
* `failed`: المهام الفاشلة التي احتفظ بها BullMQ.
* `totalPending`: الانتظار والتأخير في جميع الطابعات.
* `isProcessing`: توجد وظيفة نشطة واحدة على الأقل.

إذا كانت تتم إعادة محاولة المهام الفاشلة إلى الأبد، فقم بإصلاح اتصال الطابعة أولاً. سيتم استرداد قائمة الانتظار تلقائيًا بمجرد إمكانية الوصول إلى الطابعة.

## تم قبول طلب الطباعة ولكن لم يتم طباعة أي شيء

إذا قامت `/print` بإرجاع `{ "ok": true, "queued": true }`، فهذا يعني أن السائق قد قبل المهمة.

الفحوصات التالية:

1. `GET /queue-status`.
2. `POST /status` مع `validate: true`.
3. IP الطابعة والمنفذ في تكوين وحدة التحكم.
4. يدعم طراز الطابعة خطوط ESC/POS النقطية عبر TCP.
5. الطابعة بها ورق ولم يتم إيقافها مؤقتًا.

## عنوان الطابعة مفقود

يتطلب برنامج التشغيل الحالي كلا من:

```json theme={null}
{
  "ip_address": "192.168.1.50",
  "port": "9100"
}
```

في وحدة التحكم، يعني هذا عادةً أن عنوان IP أو المنفذ الفعلي للطابعة مفقود. برنامج التشغيل URL ليس هو نفس عنوان IP الخاص بالطابعة.

## فشل HTTPS

يفحص:

```sh theme={null}
curl http://localhost:8080/ca.crt
curl https://plato-printer.local/health
```

الإصلاحات المحتملة:

* قم بتثبيت شهادة CA على جهاز POS.
* قم بإجراء حل `plato-printer.local` لجهاز التشغيل.
* فتح المنفذ `443`.
* تأكيد وجود `assets/certs`.
* تأكيد بدء العلبة في السجلات.

## فشل الشبكة

يفحص:

```sh theme={null}
curl http://localhost:8080/mesh-status
```

إذا تم تعطيل الشبكة، فاضبط:

```json theme={null}
{
  "features": {
    "meshEnabled": true
  }
}
```

في حالة استخدام HTTPS، تستخدم الشبكة:

```txt theme={null}
wss://plato-printer.local/mesh
```

## فشل Redis في البدء

يمكن أن يفشل بدء تشغيل Redis المضمن في حالة:

* الإصدار الثنائي Redis الذي تم تكوينه مفقود أو تالف.
* منفذ Redis الذي تم تكوينه قيد الاستخدام بالفعل.
* يقوم Windows بحظر الملف الثنائي الذي تم تنزيله.
* إصدار Redis الذي تم اكتشافه لا يتطابق مع `redis.version`.

الإصلاحات:

* قم بتشغيل البرنامج النصي للحزمة لإعداد `redis-binaries`.
* تغيير `redis.port`.
* احذف مجلد `redis-binaries/<version>` التالف وأعد البناء.
* استخدم `redis.mode: "external"` مع خادم Redis المعروف.

## إعادة تعيين آمنة

لإعادة التعيين المحلي أثناء التطوير:

```sh theme={null}
pnpm --filter @plato/pc-printer clean
```

يؤدي هذا إلى إزالة `dist` و`output` و`logs` و`plato-printer.zip` و`dump.rdb`.

في مرحلة الإنتاج، لا تقم بحذف `dump.rdb` إلا إذا كنت تريد عمدًا مسح قوائم الانتظار المستمرة وحالة تسجيل الطابعة المعروفة.