تشغيل تشخيصات البيئة في NextPDF Connect

لمحة سريعة

تحقَّق من سلامة خادم ⁨NextPDF Connect⁩ ومن توفر القدرات التي يحتاج إليها سير عملك قبل تشغيل أي عمل فعلي. استخدم هذه الصفحة كخطوة أولى في أي مسار وكيل (⁨agentic⁩). الأدوات التي جرى التحقق منها مقابل سجل أدوات الخادم هي diagnostic.doctor وdiagnostic.capabilities وdiagnostic.verify. يعرضها السجل بأسماء بروتوكول منقّطة، وتوجد أيضًا أداة ذات صلة هي diagnostic.inspect. وكلها أدوات ⁨Core.⁩

التثبيت

composer require nextpdf/server

اربط وسيلة نقل. لا تحتاج إلى ⁨veraPDF⁩ إلا في خطوة التحقق من التوافق الاختيارية. ولا يتطلب التحقق البنيوي أداة خارجية.

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

diagnostic.doctor تُرجع تقريرًا أساسيًّا عن سلامة البيئة: إصدار ⁨PHP⁩، والامتدادات المحمَّلة، وإصدار الخادم، والمستوى النشط، وأي تحذيرات. عامِل status بوصفه البوابة. تابِع عند ok، واقرأ warnings عند warning، وتوقف عند error.
diagnostic.capabilities تسرد القدرات المسجَّلة مع مستواها وحالتها أثناء التشغيل (available وunavailable وdegraded). عدد القدرات يعتمد على وقت التشغيل والمستوى، لذا لا تضع إجماليًّا ثابتًا في الشيفرة. تحقَّق من كل قدرة يحتاج إليها سير عملك.
diagnostic.verify تتحقق من السلامة البنيوية: ترويسة ⁨PDF⁩، وعلامة ⁨EOF⁩، وجدول الإحالة المرجعية. هذه هي بنية المستند التي يجري الوصول إليها عبر شجرة الصفحات (⁨ISO 32000-2⁩ §7.5). ومع compliance_flavour، تستدعي ⁨veraPDF⁩ أيضًا.

تأتي نتيجة التشخيص كاستجابة عادية عبر كل وسيلة نقل (⁨PHP Standard Recommendation 18⁩, ⁨PSR-18⁩ §⁨p2⁩).

سطح ⁨API⁩

الأداة	الدور	مستوى الخطورة
`diagnostic.doctor`	تقرير سلامة البيئة	آمن
`diagnostic.capabilities`	جرد القدرات وحالتها	آمن
`diagnostic.verify`	التحقق البنيوي / التحقق من التوافق	آمن
`create_pdf`، `add_text`، `output_pdf`	اختبار تحقق سريع لمستند	كما هو موثَّق في موضع آخر

هذه هي أسماء البروتوكول كما تظهر في السجل. كتالوج الأدوات هو الكتالوج المرجعي. يحدد المستوى المثبَّت الأدوات والقدرات المتاحة، لذا لا تفترض أبدًا عددًا ثابتًا للأدوات أو القدرات.

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

diagnostic.doctor (بدون وسائط) ← اقرأ status.
diagnostic.capabilities (بدون وسائط) ← تأكد من أن كل قدرة مطلوبة هي available.
create_pdf ثم add_text ← مستند تحقق سريع بسيط.
diagnostic.verify مع document_id ← فحوص بنيوية.
اختياريًّا diagnostic.verify مع compliance_flavour: "4" ← ⁨veraPDF.⁩
output_pdf (⁨base64⁩) ← أنهِ جلسة التحقق السريع.

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

اجعل diagnostic.doctorstatus بوابة المسار. اربط كل اعتمادية في سير العمل بمعرّف قدرة محدد، وتحقَّق من available قبل تشغيل الخطوات المعتمِدة. عامِل degraded بوصفه خطرًا على الجودة يستلزم فحصًا موضعيًّا. شغِّل دائمًا فحص diagnostic.verify البنيوي. شغِّل متغيِّر التوافق فقط عندما يكون التوافق مهمًّا. إذا كان ⁨veraPDF⁩ غائبًا، فستُرجع نتيجة واضحة تفيد بعدم العثور عليه، لا عيبًا في الخادم.

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

⁨veraPDF⁩ غائب. يُرجع استدعاء التوافق نتيجة صريحة تفيد بعدم العثور عليه. تظل الفحوص البنيوية تعمل. إذا كنت بحاجة إلى التحقق من التوافق، فثبِّت ⁨veraPDF⁩ وأضِفه إلى المسار ⁨PATH⁩ الخاص بعملية الخادم.
انتهاء مهلة ⁨veraPDF.⁩ قد تتسبب المستندات الكبيرة في تجاوز مهلة التحقق. قلِّل حجم المستند، أو ارفع المهلة في إعدادات الخادم.
قدرة degraded. تكون الاعتمادية متاحة جزئيًّا فقط، لذا قد تنخفض جودة المُخرجات. راجِع سجلات الخادم لمعرفة البديل المستخدَم.
حالة error في ⁨Doctor.⁩ يوجد متطلَّب حَرِج غير مستوفى. لا تتابع.

الأداء

التحقق البنيوي سريع. ينشئ مسار التوافق عملية ⁨veraPDF⁩ ويظل ضمن مهلة التحقق. تعكس الميزانية الواسعة وجود تلك العملية الفرعية.

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

يكشف مُخرَج التشخيص تفاصيل البيئة: إصدار ⁨PHP⁩ والامتدادات والمستوى. عامِله بوصفه مخصصًا للمشغِّل فقط، ولا تُظهِره للمستدعِين غير الموثوقين.

التوافق

العبارة	المواصفة	البند	⁨reference_id⁩
نتيجة التشخيص هي استجابة نقل عادية.	⁨PSR-18⁩	§⁨p2⁩
تستهدف السلامة البنيوية البنية المرتكزة على شجرة الصفحات.	⁨ISO 32000-2⁩	§7.5

يُشغِّل متغيِّر التوافق ⁨veraPDF⁩ ويبلِّغ عن حكمه. لا يؤكِّد ⁨NextPDF⁩ التوافق بنفسه؛ فالمُحقِّق هو من يقرِّر.

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

غير منطبق: جميع أدوات التشخيص هي ⁨Core.⁩

توافر وسائل النقل

وسيلة النقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم	نتائج التشخيص هي نتائج أدوات.
⁨REST⁩	نعم	ترتبط نقاط نهاية السلامة بهذه الأدوات.
⁨gRPC⁩	نعم	أحادي؛ تحمل النتيجة حقول الحالة نفسها.

مستوى خطورة ⁨HITL⁩

جميع أدوات التشخيص الثلاث آمنة: فهي للقراءة فقط، دون أي أثر جانبي. لا تُفعِّل بوابة التأكيد أبدًا. output_pdf في اختبار التحقق السريع هو وضع ⁨base64⁩ (مراجعة، دون بوابة).

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

التشخيصات لا تستخدم بوابة أبدًا.

{ "allowed": true }