الامتثال — مرجع متعمّق

لمحة سريعة

توجّه وحدة الامتثال ملف ⁨PDF⁩ المكتمل إلى ⁨sidecar⁩ تدقيق خارجي وتُعيد نتيجة واحدة موحّدة. يحلّ ⁨ComplianceGateway⁩ ⁨sidecar⁩ المسؤول انطلاقًا من ⁨ComplianceProfile⁩، ويفرض سياسة توفّر تُغلق عند الفشل، ويغلّف كل حُكم أداة في ⁨ExternalValidationResult⁩. تُشحن جسور لأجل vera⁨PDF⁩ (⁨PDF⁩/A و⁨PDF⁩/UA و⁨PDF 2.0⁩ Arlington)، وEU DSS (مستويات ⁨PAdES⁩)، و⁨sidecar⁩ المدمج Mustang/KoSIT (⁨ZUGFeRD⁩ و⁨Factur-X⁩ وEN 16931)، وخفيّ KoSIT مستقل. توفّر الوحدة كذلك ختم الجاهزية عبر ⁨AiReadyCertifier⁩ ومُشغِّلًا لمجموعة اختبارات KoSIT XRechnung الرسمية.

التوفّر والترخيص

تُشحن هذه القدرة في ⁨NextPDF⁩ Enterprise (⁨nextpdf/enterprise⁩) وتُفعَّل بمظروف ترخيص من فئة Enterprise. لا يُحمّل أي نشر بلا هذا الاستحقاق أصنافَ القدرة. قارِن الإصدارات واحصل على ترخيص.

يُرخَّص سطح الامتثال/الأدلة عبر قدرة ⁨enterprise.compliance.evidence⁩. يمنع الاستحقاقُ المفقود أو المنتهي الميزةَ؛ ولا يخفّض السلوك بصمت.

الفئة	سطح الامتثال
Core	فحوص داخل العملية على تدفّق البايتات والقواعد النحوية؛ بلا تفويض إلى ⁨sidecar⁩ خارجي.
Pro	تدقيق داخل العملية لـ EN 16931 / Factur-X / ZUGFeRD؛ بلا ⁨sidecar⁩ خارجي.
Enterprise	بوّابة مُدقِّق خارجي (هذه الوحدة) بنتيجة موحّدة وسياسة إغلاق عند الفشل.

مُدقِّق الفواتير الإلكترونية داخل العملية في Pro و⁨sidecar⁩ ⁨ZUGFeRD⁩ الخارجي في Enterprise سطحان متمايزان. تُشحن بوّابة المُدقِّق الخارجي في حزمة ⁨nextpdf/enterprise⁩ وحدها.

سطح واجهة البرمجة العامة

composer require nextpdf/enterprise:^3

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
ComplianceGateway::__construct	list<ExternalValidator> $validators، LoggerInterface $logger، bool $optional = false	يفهرس المُدقِّقات باسم الأداة	—	—	الوضع الاختياري يخفّض فحص التوفّر إلى تحذير فقط
ComplianceGateway::validate	string $pdfContent، ComplianceProfile $profile، array $options = []	يحلّ المُدقِّق عبر ComplianceProfile::toolName()، ويفحص التوفّر، ويفوّض	?ExternalValidationResult	ComplianceSidecarUnavailableException؛ InvalidArgumentException (لا مُدقِّق مُسجَّل للأداة)	يُعيد null في الوضع الاختياري فقط مع تعطّل الـ ⁨sidecar⁩
ComplianceGateway::validateAllProfiles	string $pdfContent، string $toolName	يدقّق كل ملف تعريف مربوط بالأداة	list<ExternalValidationResult>	كما في validate()	يتخطّى نتائج null (الوضع الاختياري)
ComplianceGateway::healthCheck	—	يسبر كل نقطة نهاية صحّة لـ ⁨sidecar⁩ مُسجَّل	array<string, bool>	—	يُبلّغ عن قابلية الوصول؛ لا يدقّق أي مستند
ComplianceGateway::buildComplianceMatrix (ساكن)	list<ExternalValidationResult> $results، string $commitSha	يختزل النتائج إلى مصفوفة ذات إصدار مخطّط	array<string, mixed>	—	إصدار المخطّط 1.0؛ يسجّل خرج الأداة ولا يؤكّد شيئًا
ComplianceProfile (enum)	15 حالة مدعومة بسلسلة نصّية	يربط كل ملف تعريف بلافتة معيار وأداة	—	—	standardReference(): string، toolName(): string
ExternalValidator (interface)	—	عقد جسر ⁨sidecar⁩ فوق PSR-18	—	validate() يرمي ComplianceSidecarUnavailableException عند فشل النقل	getToolName()، isAvailable()، validate()
VeraPdfValidator::validate	توقيع الواجهة	POST متعدد الأجزاء إلى ⁨sidecar⁩ veraPDF REST؛ تحليل تقرير JSON	ExternalValidationResult	ComplianceSidecarUnavailableException؛ InvalidArgumentException (ملف تعريف غير مدعوم)	PDF/A وPDF/UA وArlington؛ يحلّل JSON فقط، لا XML أبدًا
DssValidator::validate	توقيع الواجهة	POST بصيغة Base64 JSON إلى ⁨sidecar⁩ EU DSS REST	ExternalValidationResult	ComplianceSidecarUnavailableException؛ InvalidArgumentException (ملف تعريف غير مدعوم)	PAdES من B-B حتى B-LTA؛ يرفض الباني المُهَل دون ثانية واحدة
ZugferdExternalValidator::validate	توقيع الواجهة	POST متعدد الأجزاء إلى ⁨sidecar⁩ المدمج Mustang/KoSIT	ExternalValidationResult	ComplianceSidecarUnavailableException (وكذلك عند قاطع دائرة مفتوح)؛ InvalidArgumentException (ملف تعريف غير مدعوم)	ZUGFeRD 2.4 وFactur-X 1.08 وEN 16931؛ قاطع دائرة اختياري مُحقَن
KoSitValidator::validate	توقيع الواجهة	POST بـ XML خام إلى خفيّ KoSIT مستقل	ExternalValidationResult	ComplianceSidecarUnavailableException؛ InvalidArgumentException (ملف تعريف غير مدعوم)	EN 16931 فقط؛ يحلّل تقرير Schematron SVRL بإغلاق عند الفشل
ExternalValidationResult	كائن قيمة للقراءة فقط	حُكم أداة موحّد	—	—	passes()، fails()، nonConformanceCount()، toComplianceMatrix()
NonConformance	كائن قيمة للقراءة فقط	نتيجة مفردة بمعرّف قاعدة وبند وشدّة وموضع	—	—	toArray()
ComplianceSidecarUnavailableException	string $toolName، string $endpoint، int $code = 0، ?Throwable $previous = null	إشارة عدم توفّر ⁨sidecar⁩ بإغلاق عند الفشل	—	—	toolName وendpoint عامّان للقراءة فقط
AiReadyCertifier::certify	string $pdfBytes	يقيّم ثلاثة معايير جاهزية؛ يختم أصلية XMP	array{0: AiReadyCertification, 1: string}	InvalidArgumentException (الختم يتطلّب جدول مراجع تقاطعية كلاسيكيًّا)	العنصر الثاني يساوي المُدخَل حين يكون المستوى not_certified
AiReadyCertification	كائن قيمة للقراءة فقط	تقييم جاهزية بمستوى وعدد معايير ومشكلات وتجزئة مصدر	—	—	لافتة جاهزية داخلية، وليست شهادة معايير
XRechnungTestSuiteRunner::__construct	string $suitePath، ExternalValidator $validator، bool $useCuratedNegativeFallback = true	يحلّ دليل المجموعة المستخرَجة	—	InvalidArgumentException (الدليل غير موجود)	يستهدف مجموعة اختبارات KoSIT XRechnung الرسمية
XRechnungTestSuiteRunner::run	bool $stopOnFirstFailure = false	يدقّق كل نموذج مجموعة عبر الجسر	XRechnungTestSuiteResult	XRechnungTestSuiteException (المُدقِّق غير متوفّر؛ لا ملفات XML)	كذلك isAvailable()، getSuitePath()، discoverTestFiles()
XRechnungTestSuiteResult	كائن قيمة للقراءة فقط	ناتج مجموعة مجمّع	—	—	allPassed()، totalCount()، getFailures()، getErrors()، toSummary()
XRechnungTestCaseResult	كائن قيمة للقراءة فقط	ناتج لكل حالة	—	—	passed()، hasError()، getFilename()
XRechnungTestSuiteException	بواني ساكنة	إشارة فشل تشغيل المجموعة	self	—	validatorUnavailable()، noTestFilesFound(string $suitePath)

namespace NextPDF\Enterprise\Compliance;

final class ComplianceGateway
{
    /** @param list<ExternalValidator> $validators */
    public function __construct(
        array $validators,
        private readonly LoggerInterface $logger,
        private readonly bool $optional = false,
    );

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ?ExternalValidationResult;

    /** @return list<ExternalValidationResult> */
    public function validateAllProfiles(string $pdfContent, string $toolName): array;

    /** @return array<string, bool> */
    public function healthCheck(): array;

    /**
     * @param list<ExternalValidationResult> $results
     * @return array<string, mixed>
     */
    public static function buildComplianceMatrix(array $results, string $commitSha): array;
}

interface ExternalValidator
{
    public function getToolName(): string;

    public function isAvailable(): bool;

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ExternalValidationResult;
}

enum ComplianceProfile: string
{
    case PdfA1b = 'pdfa-1b';
    // PdfA2b, PdfA3b, PdfA4, PdfA4f, PdfUa1, PdfUa2, Pdf20Arlington,
    // PadesBasic, PadesTimestamp, PadesLongTerm, PadesArchive,
    // Zugferd24, FacturX108, En16931

    public function standardReference(): string;

    public function toolName(): string;
}

final class AiReadyCertifier
{
    /** @return array{0: AiReadyCertification, 1: string} Tuple of [certification, stamped PDF bytes] */
    public function certify(string $pdfBytes): array;
}

عقد السلوك

يحلّ ⁨ComplianceGateway::validate()⁩ الـ ⁨ExternalValidator⁩ المُسجَّل الذي يطابق ⁨getToolName()⁩ فيه ⁨ComplianceProfile::toolName()⁩، ويفحص ⁨isAvailable()⁩، ويفوّض، ويُعيد ⁨ExternalValidationResult⁩ موحّدة. القواعد المرصودة خارجيًّا:

• الافتراض: الإغلاق عند الفشل. حين يكون الـ ⁨sidecar⁩ المُحلَّل غير متوفّر والوضع الاختياري مُطفأ، يرفع الاستدعاء ⁨ComplianceSidecarUnavailableException⁩. المستند لا يُفحص؛ ولا يُعامَل قطّ على أنه ناجح.
• الوضع الاختياري. بناء البوّابة بـ ⁨optional: true⁩ (يربطه المشغّلون من متغيّر البيئة ⁨NEXTPDF_COMPLIANCE_OPTIONAL⁩) يخفّض الـ ⁨sidecar⁩ غير المتوفّر إلى تحذير مُسجَّل وقيمة ⁨null⁩ مُعادة. على المستدعين معاملة ⁨null⁩ على أنها “لم يُفحص”. يغطّي الوضع الاختياري سبر التوفّر التمهيدي فقط؛ أما فشل النقل أثناء استدعاء التدقيق نفسه فيرفع ⁨ComplianceSidecarUnavailableException⁩ في الوضعين كليهما.
• ملف تعريف مجهول. ملف تعريف بلا مُدقِّق مُسجَّل يرفع ⁨InvalidArgumentException⁩؛ ولا ينجح بصمت أبدًا.
• دلالات النجاح. يتطلّب ⁨ExternalValidationResult::passes()⁩ أن يكون ⁨conformant⁩ صحيحًا و صفرًا من حالات عدم المطابقة. تحمل كل نتيجة ملف التعريف واسم الأداة وإصدارها وعدد التأكيدات والنتائج وSHA-256 للبايتات المُدقَّقة وطابعًا زمنيًّا بتوقيت UTC ومدّة الاستدعاء.
• المصفوفة سجلّ، لا تأكيد. ⁨buildComplianceMatrix()⁩ مُختزِل ساكن يُنتج بنية ذات إصدار مخطّط بإصدارات الأدوات وSHA لالتزام لأجل التتبّع. يسجّل خرج الأداة؛ ولا يؤكّد شيئًا.
• تدفّق البيانات. يُرسَل تدفّق بايتات ⁨PDF⁩ الكامل إلى الـ ⁨sidecar⁩ المُهيّأ عبر عميل ⁨PSR-18⁩. يُسجَّل كل تدقيق عبر ⁨PSR-3⁩ بملف التعريف والأداة والنجاح/الفشل وعدد التأكيدات والمدّة.

توجيه ملف التعريف إلى الأداة، كما يُعيده ⁨ComplianceProfile::standardReference()⁩ و⁨::toolName()⁩:

حالات ملف التعريف	مرجع المعيار	الأداة
pdfa-1b، pdfa-2b، pdfa-3b، pdfa-4، pdfa-4f	ISO 19005-1/-2/-3/-4 (المستوى B؛ المستوى F لـ 4f)	veraPDF
pdfua-1، pdfua-2	ISO 14289-1:2014، ISO 14289-2:2024	veraPDF
pdf20-arlington	ISO 32000-2:2020 (نموذج Arlington)	veraPDF
pades-b-b، pades-b-t، pades-b-lt، pades-b-lta	ETSI EN 319 142-1 من B-B حتى B-LTA	EU DSS
zugferd-2.4، factur-x-1.08، en-16931	ZUGFeRD 2.4 / Factur-X 1.08 / EN 16931-1:2017	Mustang/KoSIT

يقيّم ⁨AiReadyCertifier::certify()⁩ ثلاثة معايير: وجود توقيع بنيوي، وصحّة LTV، وغياب التشفير. المعايير الثلاثة الناجحة تُنتج المستوى ⁨certified⁩؛ واحد أو اثنان يُنتجان ⁨partial⁩؛ والصفر يُنتج ⁨not_certified⁩. عند ⁨certified⁩ أو ⁨partial⁩، يُلحِق تحديثًا تراكميًّا يحمل تدفّق أصلية XMP وتجاوزًا لـ Catalog؛ ولا تُعدَّل البايتات الأصلية أبدًا. المستوى “certified” لافتة جاهزية داخلية في ⁨NextPDF⁩، وليس شهادة معايير.

يحلّ ⁨VeraPdfValidator⁩ ردود ⁨sidecar⁩ من نوع ⁨JSON⁩ فقط (لا ⁨XML⁩؛ نظيف من XXE بحكم البناء). يحلّ ⁨KoSitValidator⁩ تقرير ⁨XML⁩ SVRL من الخفيّ مع رفض إعلانات DOCTYPE وتعطيل الوصول للشبكة، ويعامل تقريرًا غير قابل للتحليل على أنه فشل للاستدعاء.

الحالات الحدّية وأنماط الفشل

• تظهر مهلة الـ ⁨sidecar⁩ أو خطأ النقل بوصفها ⁨ComplianceSidecarUnavailableException⁩ من الجسر؛ وينطبق افتراض الإغلاق عند الفشل.
• يُنتج ردّ ⁨sidecar⁩ غير 200 نتيجةً فاشلة بنتيجة خاصّة بالأداة (مثل ⁨VERAPDF-HTTP-ERROR⁩)؛ ولا يكون قطّ نجاح مطابقة.
• جسم ⁨JSON⁩ أو ⁨XML⁩ مُشوّه من الـ ⁨sidecar⁩ هو فشل تدقيق للاستدعاء، لا نجاح مطابقة.
• نتائج EU DSS بلا توقيعات تفشل بـ ⁨DSS-NO-SIGNATURES⁩. أي إشارة غير ⁨TOTAL_PASSED⁩ تفشل بـ ⁨DSS-SIG-INVALID⁩. مستوى توقيع دون الخطّ الأساس المتوقَّع يفشل بـ ⁨DSS-LEVEL-MISMATCH⁩.
• ينشر ⁨DssValidator⁩ ميزانية مهلته لكل طلب في كل طلب عبر ترويسة ⁨X-NextPDF-Timeout-Seconds⁩؛ وعلى عميل ⁨PSR-18⁩ لدى المُكامِل احترامها كي لا يستطيع ⁨sidecar⁩ متعثّر حجب الخيط المستدعي بلا حدّ.
• يوجّه ⁨ZugferdExternalValidator⁩ اختياريًّا استدعاءات الـ ⁨sidecar⁩ عبر قاطع دائرة مُحقَن؛ ويُخطَّط قاطع مفتوح إلى ⁨ComplianceSidecarUnavailableException⁩ (فشل سريع، ومع ذلك إغلاق عند الفشل). الافتراضي قاطع بلا أثر.
• يقبل ⁨KoSitValidator::isAvailable()⁩ الرمزين ⁨HTTP⁩ 200 و405 من سبر صحّة الخفيّ؛ يردّ الخفيّ على GET بـ 405 وهو سليم.
• يفشل ختم ⁨AiReadyCertifier⁩ بإغلاق عبر ⁨InvalidArgumentException⁩ حين يفتقر المستند الأصلي إلى جدول مراجع تقاطعية كلاسيكي (مثل تدفّقات المراجع التقاطعية).
• يرفض ⁨XRechnungTestSuiteRunner::run()⁩ التشغيل حين يكون المُدقِّق غير متوفّر أو تخلو المجموعة من ملفات ⁨XML⁩؛ ومع تفعيل ⁨useCuratedNegativeFallback⁩ يستبدل مجموعة سلبية منسّقة حين لا تشحن المجموعة نماذج غير صالحة.

السلوك في وضع ⁨FIPS⁩

لا تؤدّي هذه الوحدة أي توقيع ولا حراسة مفاتيح. تحكم سياسةَ خوارزميات وضع FIPS وحدتا الأمان والتوقيع. يُفوَّض تطابق التوقيع إلى EU DSS الذي يتّخذ تحديده الخاص.

المطابقة

تفوّض البوّابة حُكم المطابقة إلى أداة خارجية؛ ويعكس التصميم حدَّ المعايير نفسها بأن المطابقة تُحدَّد إزاء المتطلّبات، لا يؤكّدها مُنتِج.

السلوك	المرجع
التزام المعالج المطابِق؛ تحديد المطابقة إزاء المعيار	ISO 19005-4:2020 §5.2
متطلّبات ملف PDF/A-4 مقابل التأكيد الذاتي من المُنتِج	ISO 19005-4:2020 §6.6.4
تطابق PDF/UA-2 خاصّية للملف	ISO 14289-2:2024 §6
مستويات توقيع PAdES الأساسية	ETSI EN 319 142-1 §5.4.3

تُنتج الأداة الخارجية الحُكم. لا تملك ⁨NextPDF⁩ أي شهادة ولا تمنح أيًّا؛ ودعم ملف تعريف ليس مطابقةً له. نتائج التدقيق سجلّات فحص بنيوي تقني للاسترشاد، لا مشورة قانونية؛ استشِر فريق الامتثال لديك للحكم في الكفاية التنظيمية.

ملاحظات التطوير

• يستضيف المشغّل الـ ⁨sidecars⁩ ويشغّلها، ويثبّت إصداراتها، ويقيّد وصولها الشبكي، ويتحقّق من TLS لديها، ويتحكّم في البيئة التي تُفعّل الوضع الاختياري. نقاط نهاية الـ ⁨sidecar⁩ حدُّ ثقة؛ وضوابط الإقامة والاحتفاظ للمستندات والنتائج والسجلّات مسؤولية المشغّل.
• خرج ⁨buildComplianceMatrix()⁩ مصمَّم لتتبّع CI: ثبّت SHA لالتزام وأرشِف المصفوفة إلى جانب مُخرجات البناء.
• يتوقّع مُشغِّل XRechnung مجموعة الاختبارات الرسمية مستخرَجة إلى دليل محلّي؛ وتُسمّي رسالة بانيه مصدرَ التنزيل العام.
• تفاصيل الآلية الداخلية تبقى في التوثيق الداخلي لمستودع المصدر وهي خارج نطاق هذا الدليل.

حدّ النشر

توثّق هذه الصفحة السلوك المرصود خارجيًّا وسطح واجهة البرمجة العامة المدعوم فقط. مسارات النطاق الداخلية وأصناف المساعدة وجداول الآليات وأسماء ملفات كتيّبات التشغيل وبادئات التذاكر خارج النطاق.

انظر أيضًا

• نظرة عامة على قدرة الامتثال
• التدقيق — مرجع متعمّق
• الأدلة — مرجع متعمّق
• امتثال Pro — فوترة إلكترونية داخل العملية (سطح متمايز)
• مطابقة Core