اصطلاحات وصفات Connect

اصطلاحات وصفات ⁨Connect⁩

تلتزم كل وصفة في كتاب وصفات ⁨Connect⁩ بالعقد نفسه. توثّق هذه الصفحة ذلك العقد لتعرف ما ينبغي أن تتوقعه بصفتك قارئًا، وما يجب أن تستوفيه الوصفة بصفتك مؤلفًا. هذه الصفحة وصفية: فهي تسجّل الاصطلاح. أما الإنفاذ ففي أدوات مستودع nextpdf/server وفي صفحة تجاوز نمط التوثيق، لا هنا.

يكتب المؤلفون وصفات ⁨Connect⁩ في مستودع nextpdf/server ضمن docs/public/، ثم يسحبها المُجمِّع إلى هذا الموقع. تنطبق الاصطلاحات أدناه أينما كانت وصفة ⁨Connect⁩ موجودة.

1. استدعاءات الأدوات مستقلة عن وسيلة النقل

تستخدم كل وصفة من وصفات ⁨Connect⁩ استدعاء الأداة نفسه عبر كل وسيلة نقل.

تُظهر الوصفة استدعاء الأداة مرة واحدة. يشغّل الاستدعاء ذاته الأداة عبر ⁨Model Context Protocol⁩ (tools/call)، ونقطة نهاية أداة ⁨Representational State Transfer⁩ (⁨REST⁩)، وخدمة ⁨gRPC⁩، لأن الوسائل الثلاث كلها تشترك في مُنفِّذ أدوات واحد.
مخطط الوسائط المرجعي لأي أداة هو ما يعيده النشر الفعلي من tools/list (⁨MCP⁩) أو واصف الخدمة (⁨gRPC⁩). أما الوسائط النموذجية في الوصفة فتُبيّن شكل الاستدعاء فقط، ولا تكون مخططًا مجمّدًا تعيد الوصفة تعريفه.
لا تؤكّد الوصفة أبدًا عددًا إجماليًّا ثابتًا للأدوات. الفهرس المعتمَد هو فهرس أدوات الخادم نفسه، وهو الفهرس الذي تربط إليه الوصفة.

2. الأدوات المشروطة بالطبقة تُذكَر صراحةً، لا تُفترَض

يسجّل سجل أدوات الخادم الأدوات الأساسية دائمًا. ثم يستكشف مزوّدي ⁨Pro⁩ و⁨Enterprise⁩ باستخدام class_exists()، ولا يسجّل أدواتها إلا عندما يكون nextpdf/premium مثبّتًا إلى جانب الخادم.

الوصفة التي تعتمد على أداة ⁨Pro⁩ أو ⁨Enterprise⁩ تذكر هذه التبعية الطبقية صراحةً، وتوضّح لك كيف تتحقق من وجود الأداة في نشرك عبر استدعاء tools/list.
في نشرٍ لا تُحلّ فيه الأداة، يعيد الاستدعاء خطأ أداة غير معروفة. تعرض الوصفة تلك النتيجة بوصفها حدّ الطبقة المقصود، لا تدهورًا، ولا تلمّح أبدًا إلى أن أداةً مقيّدة بالطبقة متاحة دائمًا.

3. نموذج المخاطر وبوابة التأكيد

تعلن كل أداة عن مستوى واحد من بين أربعة مستويات للمخاطر. وعند المستوى الأعلى، approval_required، لا تُنفَّذ الأداة في الاستدعاء الأول.

الوصفة التي يمكن أن تكون أداتها approval_required (بحكم التصميم أو عبر تجاوز من المُشغِّل) توثّق ⁨ConfirmationGate⁩: تعيد البوابة رمز تحدٍّ أحادي الاستخدام مرتبطًا باسم الأداة، وبرقم عشوائي يُستخدم مرة واحدة (⁨nonce⁩)، وبمدة بقاء (⁨TTL⁩) مقدارها 300 ثانية، وليس بالوسائط. يعيد المُستدعي استدعاء الأداة نفسها مرة واحدة مع arguments._confirmation_token.
تذكر الوصفة أن تجاوز التهيئة لا يمكنه إلا رفع مستوى مخاطر الأداة، ولا يمكنه أبدًا خفض أداة هي approval_required بحكم التصميم. وتتصرف البوابة بصورة متطابقة عبر وسائل النقل.

4. معالجة الأخطاء تفصل وسيلة النقل عن الحالة

في الوصفة التي تصل إلى خدمة بعيدة عبر ⁨Hypertext Transfer Protocol⁩ (⁨HTTP⁩)، يُعدّ فشل النقل وحالة ⁨HTTP⁩ غير الناجحة حالتين متمايزتين. يرفع عميل ⁨PSR-18⁩ استثناء عميل مُصنَّف نوعيًّا فقط حين يتعذّر عليه إرسال الطلب كليًّا — ⁨PSR-18⁩ §4؛ أما استجابة 4xx أو 5xx فهي قيمة إرجاع عادية تفحصها الوصفة، وليست استثناءً تلتقطه. تعالج وصفة ⁨Connect⁩ الجاهزة للإنتاج كلتا الحالتين على نحو متمايز، دون كتلة ⁨catch⁩ فارغة.

5. حدّ المطابقة وإصدار الشهادات

تتعامل وصفة ⁨Connect⁩ مع دعم معيارٍ ما على أنه دعم، لا على أنه مطابقة ولا اعتماد أبدًا.

يُنتج المحرّك مخرجات يُقصد بها أن تطابق معيارًا (⁨PDF/UA-2⁩، و⁨PDF/A-4⁩، ومستوى ⁨PAdES⁩)؛ وتُحدَّد المطابقة وفق متطلبات المعيار بواسطة مُدقِّق مستقل، لا يؤكّدها البرنامج المُنتِج — ⁨PDF/A-4⁩ §6.7.3.
تقييم الجاهزية مؤشر جاهزية، لا اعتماد. الإقرار ليس ضمانًا قانونيًّا. مادة التحقق طويل الأمد الموجودة في مستندٍ ما قدرة يحملها المستند، وليست ضمانًا لصلاحية توقيع غير محدودة المدة. إنها قدرة خاصة بطبقة ⁨Enterprise⁩ وحدها، ومتمايزة عن مستويات ⁨PAdES⁩ الأدنى.
لا تُستخدَم كلمات المطابقة المطلقة بوصفها ادعاءات للمحرّك. قائمة الحظر المعجمية التي تُفحَص الوصفة إزاءها هي، حرفيًّا، الرموز “⁨certified⁩”، ثم “⁨guaranteed⁩”، ثم العبارة المكوّنة من كلمتين “⁨fully⁩” + “⁨compliant⁩”، ثم “⁨tamper-proof⁩”، ثم “⁨legally valid⁩”: لا يجوز لأيٍّ منها أن يظهر بوصفه خاصية مؤكَّدة لمخرجات ⁨NextPDF⁩، لأن المطابقة يقرّرها مُدقِّق مستقل وفق متطلبات المعيار، لا البرنامج المُنتِج — ⁨PDF/A-4⁩ §6.7.3. الوصفة التي تخفّف ادعاءً واردًا من المصدر تسجّل هذا التخفيف في ملف الادعاءات المخفَّضة المُرافِق لها.

6. بوابة النشر

تحمل كل وصفة ⁨Connect⁩ publish: false إلى أن تجتاز بوابة الكتابة. الافتراضي هو الرفض: فدمج الصفحة لا ينشرها؛ ولا ينشرها سوى قرار بوابة صريح مُسجَّل في المقدمة الوصفية (⁨front-matter⁩). الوصفة التي تعذّر تثبيت استشهاداتها المعيارية بسبب انقطاع حقيقي في محرّك المطابقة تحمل أيضًا علامة استشهاد غير محسوم وتبقى publish: false إلى أن يُعاد تثبيت الاستشهاد. يضبط تلك العلامة بروتوكولُ التراجع عند انقطاع البنية التحتية الخاص بالتوليد المعزَّز بالاسترجاع (⁨RAG⁩) في المستودع؛ ويتّبعه المؤلف بدلًا من اختلاق استشهاد أو إسقاط الادعاء.

7. المُجمِّع يكتب حقول المنشأ

لا يكتب مؤلف وصفة ⁨Connect⁩ يدويًّا حقول منشأ المصدر الأربعة التي يملكها المُجمِّع: source_repo، وsource_ref، وsource_hash، وmanifest_hash. يملؤها المُجمِّع حين يسحب الوصفة من nextpdf/server، بحيث تسجّل الصفحة المنشورة المراجعة الدقيقة التي أنتجتها. أما هذا الفهرس وصفحة الاصطلاحات هذه فهما أصليان في التوثيق، لذا تُملأ حقول منشأهما بالأصفار بحكم التصميم ولا يستبدلها المُجمِّع.

الخلاصة

تشتمل وصفة ⁨Connect⁩ على استدعاءات أدوات مستقلة عن وسيلة النقل، وتبعية طبقة مذكورة صراحةً، ونموذج المخاطر وبوابة التأكيد الموثَّقين، ومعالجة أخطاء تفصل وسيلة النقل عن الحالة، وحدّ مطابقة أمين، وافتراض publish: false إلى أن تجتاز بوابة الكتابة. الصفحة التي تستوفي الستة جميعها وصفة؛ والصفحة التي تستوفي أقل من ذلك مسوّدة.

انظر أيضًا

كتاب وصفات ⁨Connect⁩ — خريطة معرّفات الوصفات وحدّ الطبقة ووسيلة النقل.
اصطلاحات وصفات كتاب التكامل — عقد الوصفات على مستوى المنظومة بأكملها، وهو ما تخصّصه هذه الصفحة لـ ⁨Connect⁩.