التعامل مع الأخطاء في سير عمل NextPDF Connect

لمحة سريعة

ابنِ سير عمل ⁨Connect⁩ مرنًا في مواجهة الأخطاء. تحقّق من صحة كل نتيجة أداة، وأغلق الجلسة التي فشلت، ثم أعد المحاولة من حالة جديدة. يُرجِع استدعاء الأداة الفاشل نتيجة خطأ مُنظَّمة. تعامل مع تلك النتيجة بوصفها استجابة عادية، لا فشلًا في النقل. يقرّر معيار ⁨PHP Standards Recommendation⁩ (⁨PSR⁩)-18 التمييز نفسه: تُرجَع استجابة حتى عندما تشير الحالة إلى خطأ (⁨PSR-18⁩ §3).

التثبيت

composer require nextpdf/server

اربط وسيلة نقل. تستخدم هذه الوصفة create_pdf وadd_text وoutput_pdf. تتوفر الأدوات الثلاث كلها ضمن الإصدار الأساسي (⁨Core⁩).

نظرة مفاهيمية عامة

يُرجِع استدعاء الأداة الفاشل نتيجة خطأ. تحمل النتيجة علامة خطأ، ورسالة قابلة للقراءة البشرية، ورمزًا عند الاقتضاء. أما النتيجة الناجحة فلا تحمل علامة خطأ، بل تحمل المخرجات العادية للأداة. في كلتا الحالتين، تكون وسيلة النقل قد أرسلت الطلب وتلقّت الاستجابة (⁨PSR-18⁩ §⁨p2⁩).

اجعل الحلقة الدفاعية قصيرة. أرسل الاستدعاء، ثم اقرأ النتيجة. إذا كانت النتيجة خطأ، فسجّل الخطأ وصنّفه وطبّق استراتيجية التعافي، وتوقّف عن استخدام الحالة القديمة. وإلا، فاستخرج الحقول التي تحتاجها وتابِع.

واجهة ⁨API⁩

الأداة	الدور	فئة المخاطر
`create_pdf`	فتح الجلسة	آمنة
`add_text`	كتابة نص	تنبيه
`output_pdf`	تصيير ملف ⁨PDF⁩ وإرجاعه	موافقة مطلوبة / مراجعة (⁨base64⁩)

كتالوج الأدوات هو المرجع الموثوق. وتعتمد الأدوات المتاحة على الإصدار المثبَّت.

عينة شفرة — بداية سريعة

شغّل مسار النجاح (create_pdf ← add_text ← output_pdf) وتحقّق من كل نتيجة. ثم تعمّد إعادة استخدام document_id تالفًا في add_text لتوليد خطأ في الجلسة. تعافَ من ذلك بإنشاء جلسة جديدة وإعادة تطبيق المحتوى.

عينة شفرة — للإنتاج

صنّف الأخطاء إلى فئات، ثم استجِب وفقًا لذلك:

التحقق من المدخلات — خطأ حتمي. صحّح الوسائط، ثم أعد المحاولة بالاستدعاء نفسه. أمثلة: نص فارغ، محاذاة غير صالحة، حجم غير موجب، حجم صفحة غير معروف، عائلة خط غير معروفة.
الجلسة — لم يعد document_id موجودًا. أنشئ جلسة جديدة، ثم أعد تطبيق كل المحتوى.
النظام — قيد على مورد من موارد الخادم، مثل حد الجلسات. تراجع، ثم أعد المحاولة.
الموافقة — قد يتوقف output_pdf عند الإخراج إلى ملف مؤقتًا في انتظار موافقة بشرية. هذا توقّف مؤقت في سير العمل، لا فشل. مرّر التحدي وانتظر، ثم أعد الاستدعاء برمز التأكيد.

لا تفترض النجاح أبدًا. لا تُعِد أبدًا استخدام document_id بعد خطأ جلسة. لا ترسل أبدًا output_pdf حتى تنجح كل خطوة من خطوات المحتوى.

الحالات الحدّية والمزالق

الموافقة ليست خطأ. تحدي التدخل البشري في الحلقة (⁨HITL⁩) هو توقّف مؤقت. لا تُعِد المحاولة في حلقة ضيقة. مرّره إلى المراجع البشري.
إعادة تشغيل الخادم. تُمحى كل الجلسات الموجودة في الذاكرة، ويصبح كل document_id سابقًا غير صالح.
سير عمل جزئي. إذا فشل add_text في منتصف المستند، فقد تكون الجلسة غير متسقة. التعافي الآمن هو جلسة جديدة، لا إصلاح جزئي.

الأداء

الأثر ضئيل. تتناول هذه الوصفة تدفق التحكم، لا العرض. وتكون السمة structural لأي مخرجات مُنتَجة.

ملاحظات أمنية

رسائل الخطأ موجَّهة إلى الوكيل المُستدعِي والمُشغِّل. لا تُكرِّر نص خطأ الخادم الخام حرفيًا للمستخدمين النهائيين غير الموثوقين. اعرض بدلًا من ذلك رسالة مصنَّفة ومنقّاة.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
يُرجِع النقل استجابة بغض النظر عن النتيجة.	⁨PSR-18⁩	§⁨p2⁩
تُرجَع استجابة حتى عند حالة خطأ.	⁨PSR-18⁩	§3

السياق التجاري

لا ينطبق — الأدوات جميعها ضمن الإصدار الأساسي (⁨Core⁩).

توفّر النقل

النقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم	ترد الأخطاء في صورة نتيجة أداة تحمل علامة خطأ.
⁨REST⁩	نعم	تحمل الاستجابة ذات الحالة غير 2⁨xx⁩ متن الخطأ المصنَّف نفسه.
⁨gRPC⁩	نعم	رمز حالة مع رسالة نتيجة خطأ.

في كل وسيلة نقل، افحص خطأ مستوى الأداة بوصفه استجابة عادية، لا استدعاءً مُسقَطًا (⁨PSR-18⁩ §3).

فئة مخاطر ⁨HITL⁩

create_pdf آمنة، وadd_text تنبيه، وoutput_pdf موافقة مطلوبة، تُخفَّض إلى مراجعة في وضع ⁨base64⁩. تظهر عملية كتابة الملف المعلّقة في صورة تحدي موافقة. يجب أن تتعامل معه حلقة الأخطاء كتوقّف مؤقت، لا كفشل (فئات مخاطر ⁨HITL⁩).

غلاف ⁨JSON⁩ لبوابة التأكيد

تُرجِع الموافقة المعلّقة ما يلي:

{ "allowed": false, "challenge": "<human-readable challenge text>", "token": "confirm_<single-use-hex>" }

أعد استدعاء الأداة نفسها مع تعيين _confirmation_token إلى ذلك الرمز. تُرجِع { "allowed": true }. للاطلاع على التدفق الكامل، راجع ⁨output-approval⁩.