Enterprise รุ่น

Compliance — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยย่อ

โมดูล Compliance ส่ง PDF ที่เสร็จสมบูรณ์ไปยัง sidecar การตรวจสอบภายนอกและคืนผลลัพธ์ที่ทำให้เป็นมาตรฐานหนึ่งชุด ComplianceGateway แก้ไขหา sidecar ที่รับผิดชอบจาก ComplianceProfile บังคับใช้นโยบายความพร้อมใช้งานแบบ fail-closed และห่อคำตัดสินของเครื่องมือทุกครั้งไว้ใน ExternalValidationResult bridge จัดส่งมาสำหรับ veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (ระดับ PAdES), sidecar Mustang/KoSIT ที่รวมกัน (ZUGFeRD, Factur-X, EN 16931) และ KoSIT daemon แบบสแตนด์อโลน โมดูลนี้ยังมีการประทับตราความพร้อม AiReadyCertifier และตัวรันสำหรับชุดทดสอบ KoSIT XRechnung อย่างเป็นทางการ

ความพร้อมใช้งานและการอนุญาตสิทธิ์

ความสามารถนี้จัดส่งมาใน NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วยซองใบอนุญาตขั้นรุ่น Enterprise การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

พื้นผิว Compliance/Evidence ได้รับอนุญาตสิทธิ์โดยความสามารถ enterprise.compliance.evidence สิทธิ์ที่ขาดหายหรือหมดอายุจะปฏิเสธฟีเจอร์นี้ ไม่ใช่การลดระดับพฤติกรรมแบบเงียบ ๆ

ระดับ	พื้นผิว Compliance
Core	การตรวจสอบ byte-stream และไวยากรณ์ในกระบวนการ ไม่มีการมอบหมายไปยัง sidecar ภายนอก
Pro	การตรวจสอบ EN 16931 / Factur-X / ZUGFeRD ในกระบวนการ ไม่มี sidecar ภายนอก
Enterprise	เกตเวย์ตัวตรวจสอบภายนอก (โมดูลนี้) พร้อมผลลัพธ์แบบรวมและนโยบาย fail-closed

ตัวตรวจสอบ e-invoice ในกระบวนการของ Pro และ sidecar ZUGFeRD ภายนอกของ Enterprise เป็นพื้นผิวที่แตกต่างกัน เกตเวย์ตัวตรวจสอบภายนอกจัดส่งมาในแพ็กเกจ nextpdf/enterprise เท่านั้น

พื้นผิว API สาธารณะ

composer require nextpdf/enterprise:^3

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ยกข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	จัดทำดัชนี validators ตามชื่อเครื่องมือ	—	—	โหมด optional ลดการตรวจสอบความพร้อมใช้งานให้เหลือเพียงคำเตือนเท่านั้น
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	แก้ไขหา validator ด้วย `ComplianceProfile::toolName()` ตรวจสอบความพร้อมใช้งาน แล้วมอบหมายงาน	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (ไม่มี validator ลงทะเบียนสำหรับเครื่องมือนี้)	คืนค่า `null` เฉพาะในโหมด optional เมื่อ sidecar ไม่ทำงาน
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	ตรวจสอบทุกโปรไฟล์ที่แมปกับเครื่องมือ	`list<ExternalValidationResult>`	เหมือนกับ `validate()`	ข้ามผลลัพธ์ `null` (โหมด optional)
`ComplianceGateway::healthCheck`	—	ตรวจสอบ health endpoint ของ sidecar ที่ลงทะเบียนไว้ทุกตัว	`array<string, bool>`	—	รายงานความเข้าถึงได้ ไม่ตรวจสอบเอกสารใด
`ComplianceGateway::buildComplianceMatrix` (static)	`list<ExternalValidationResult> $results`, `string $commitSha`	ลดผลลัพธ์ให้เป็นเมทริกซ์ที่กำหนดเวอร์ชันด้วย schema	`array<string, mixed>`	—	เวอร์ชัน schema `1.0` บันทึกผลลัพธ์ของเครื่องมือ ไม่ยืนยันสิ่งใด
`ComplianceProfile` (enum)	15 case แบบ string-backed	แมปแต่ละโปรไฟล์ไปยังป้ายมาตรฐานและเครื่องมือ	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (interface)	—	สัญญา sidecar bridge บน PSR-18	—	`validate()` ยก `ComplianceSidecarUnavailableException` เมื่อการขนส่งล้มเหลว	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	ลายเซ็นของ interface	POST แบบ multipart ไปยัง sidecar REST ของ veraPDF การแจงรายงาน JSON	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (โปรไฟล์ที่ไม่รองรับ)	PDF/A, PDF/UA, Arlington แจงเฉพาะ JSON ไม่แจง XML เด็ดขาด
`DssValidator::validate`	ลายเซ็นของ interface	POST แบบ Base64 JSON ไปยัง sidecar REST ของ EU DSS	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (โปรไฟล์ที่ไม่รองรับ)	PAdES B-B ถึง B-LTA คอนสตรัคเตอร์ปฏิเสธค่า timeout ที่ต่ำกว่าหนึ่งวินาที
`ZugferdExternalValidator::validate`	ลายเซ็นของ interface	POST แบบ multipart ไปยัง sidecar Mustang/KoSIT ที่รวมกัน	`ExternalValidationResult`	`ComplianceSidecarUnavailableException` (รวมถึงเมื่อ circuit breaker เปิด); `InvalidArgumentException` (โปรไฟล์ที่ไม่รองรับ)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931 circuit breaker แบบ inject เสริมได้
`KoSitValidator::validate`	ลายเซ็นของ interface	POST XML ดิบไปยัง KoSIT daemon แบบสแตนด์อโลน	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (โปรไฟล์ที่ไม่รองรับ)	EN 16931 เท่านั้น แจงรายงาน Schematron SVRL แบบ fail-closed
`ExternalValidationResult`	value object แบบ readonly	คำตัดสินของเครื่องมือที่ทำให้เป็นมาตรฐานแล้ว	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	value object แบบ readonly	ข้อค้นพบเดี่ยวพร้อม rule id, clause, ระดับความรุนแรง และตำแหน่ง	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	สัญญาณความไม่พร้อมใช้งานของ sidecar แบบ fail-closed	—	—	`toolName` และ `endpoint` แบบ public readonly
`AiReadyCertifier::certify`	`string $pdfBytes`	ประเมินเกณฑ์ความพร้อมสามข้อ ประทับตราแหล่งที่มา XMP	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException` (การประทับตราต้องใช้ตาราง cross-reference แบบคลาสสิก)	องค์ประกอบที่สองเท่ากับอินพุตเมื่อระดับเป็น `not_certified`
`AiReadyCertification`	value object แบบ readonly	การประเมินความพร้อมพร้อมระดับ จำนวนเกณฑ์ ปัญหา และ source hash	—	—	ป้ายความพร้อมภายใน ไม่ใช่การรับรองตามมาตรฐาน
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	แก้ไขหาไดเรกทอรีของชุดทดสอบที่แตกไฟล์แล้ว	—	`InvalidArgumentException` (ไดเรกทอรีไม่มีอยู่)	มุ่งเป้าที่ชุดทดสอบ KoSIT XRechnung อย่างเป็นทางการ
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	ตรวจสอบแต่ละอินสแตนซ์ของชุดทดสอบผ่าน bridge	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException` (validator ไม่พร้อมใช้งาน ไม่มีไฟล์ XML)	มี `isAvailable()`, `getSuitePath()`, `discoverTestFiles()` ด้วย
`XRechnungTestSuiteResult`	value object แบบ readonly	ผลลัพธ์รวมของชุดทดสอบ	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	value object แบบ readonly	ผลลัพธ์ต่อกรณี	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	คอนสตรัคเตอร์แบบ static	สัญญาณความล้มเหลวขณะรันของชุดทดสอบ	`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 ที่ทำให้เป็นมาตรฐานแล้ว กฎที่สังเกตได้จากภายนอกมีดังนี้

ค่าเริ่มต้นแบบ fail-closed เมื่อ sidecar ที่แก้ไขได้ไม่พร้อมใช้งานและโหมด optional ถูกปิด การเรียกจะยก ComplianceSidecarUnavailableException เอกสารจะ ไม่ถูกตรวจสอบ และจะไม่ถูกถือว่าผ่านเด็ดขาด
โหมด optional การสร้างเกตเวย์ด้วย optional: true (ผู้ปฏิบัติการเชื่อมค่านี้จากตัวแปรสภาพแวดล้อม NEXTPDF_COMPLIANCE_OPTIONAL) จะลด sidecar ที่ไม่พร้อมใช้งานให้เหลือเพียงคำเตือนที่บันทึกไว้และการคืนค่า null ผู้เรียกต้องถือว่า null เป็น “ยังไม่ถูกตรวจสอบ” โหมด optional ครอบคลุมเฉพาะการตรวจความพร้อมใช้งานก่อนบินเท่านั้น ส่วนความล้มเหลวของการขนส่งระหว่างการเรียกตรวจสอบเองจะยก ComplianceSidecarUnavailableException ในทั้งสองโหมด
โปรไฟล์ที่ไม่รู้จัก โปรไฟล์ที่ไม่มี validator ลงทะเบียนไว้จะยก InvalidArgumentException และไม่มีวันผ่านแบบเงียบ ๆ
ความหมายของการผ่าน ExternalValidationResult::passes() ต้องการให้ conformant เป็นจริง และ ไม่มีความไม่สอดคล้องเลย ทุกผลลัพธ์มีโปรไฟล์ ชื่อและเวอร์ชันของเครื่องมือ จำนวนการยืนยัน ข้อค้นพบ ค่า SHA-256 ของไบต์ที่ตรวจสอบ เวลา UTC และระยะเวลาของการเรียก
เมทริกซ์คือบันทึก ไม่ใช่การยืนยัน buildComplianceMatrix() เป็น static reducer ที่สร้างโครงสร้างซึ่งกำหนดเวอร์ชันด้วย schema พร้อมเวอร์ชันของเครื่องมือและ commit SHA เพื่อความสามารถในการสืบย้อน มันบันทึกผลลัพธ์ของเครื่องมือ ไม่ยืนยันสิ่งใด
การไหลของข้อมูล byte stream ของ PDF ทั้งหมดถูกส่งไปยัง sidecar ที่กำหนดค่าไว้ผ่านไคลเอนต์ PSR-18 การตรวจสอบแต่ละครั้งถูกบันทึกผ่าน PSR-3 พร้อมโปรไฟล์ เครื่องมือ ผ่าน/ไม่ผ่าน จำนวนการยืนยัน และระยะเวลา

การแก้ไขจากโปรไฟล์ไปยังเครื่องมือ ตามที่ ComplianceProfile::standardReference() และ ::toolName() คืนค่า

Case โปรไฟล์	เอกสารอ้างอิงมาตรฐาน	เครื่องมือ
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (Level B; Level 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 มันจะเพิ่ม incremental update ที่บรรจุ XMP provenance stream และ Catalog override โดยไบต์ต้นฉบับจะไม่ถูกเปลี่ยนแปลงเด็ดขาด ระดับ “certified” คือป้ายความพร้อมภายในของ NextPDF ไม่ใช่การรับรองตามมาตรฐาน

VeraPdfValidator แจงเฉพาะการตอบกลับ sidecar แบบ JSON (ไม่มี XML ปลอดจาก XXE โดยการออกแบบ) ส่วน KoSitValidator แจงรายงาน XML SVRL ของ daemon โดยปฏิเสธการประกาศ DOCTYPE และปิดการเข้าถึงเครือข่าย และถือว่ารายงานที่แจงไม่ได้เป็นความล้มเหลวของการเรียก

กรณีขอบและโหมดความล้มเหลว

การหมดเวลาของ sidecar หรือข้อผิดพลาดการขนส่งจะปรากฏเป็น ComplianceSidecarUnavailableException จาก bridge และจะใช้ค่าเริ่มต้นแบบ fail-closed
การตอบกลับ sidecar ที่ไม่ใช่ 200 จะสร้างผลลัพธ์ที่ล้มเหลวพร้อมข้อค้นพบเฉพาะเครื่องมือ (ตัวอย่างเช่น VERAPDF-HTTP-ERROR) และไม่มีวันเป็นการผ่านความสอดคล้อง
เนื้อหา JSON หรือ XML ของ sidecar ที่ผิดรูปแบบคือความล้มเหลวของการตรวจสอบในการเรียกนั้น ไม่ใช่การผ่านความสอดคล้อง
ผลลัพธ์ EU DSS ที่ไม่มีลายเซ็นจะล้มเหลวด้วย DSS-NO-SIGNATURES การบ่งชี้อื่นนอกจาก TOTAL_PASSED จะล้มเหลวด้วย DSS-SIG-INVALID ระดับลายเซ็นที่ต่ำกว่า baseline ที่คาดไว้จะล้มเหลวด้วย DSS-LEVEL-MISMATCH
DssValidator เผยแพร่งบประมาณ timeout ต่อคำขอในทุกคำขอผ่านเฮดเดอร์ X-NextPDF-Timeout-Seconds ไคลเอนต์ PSR-18 ของผู้ผสานรวมต้องเคารพค่านี้ เพื่อไม่ให้ sidecar ที่ค้างสามารถบล็อกเธรดที่เรียกได้อย่างไม่จำกัด
ZugferdExternalValidator สามารถกำหนดเส้นทางการเรียก sidecar ผ่าน circuit breaker แบบ inject ได้เสริม breaker ที่เปิดจะแมปเป็น ComplianceSidecarUnavailableException (fail-fast แต่ยังคง fail-closed) ค่าเริ่มต้นคือ breaker แบบ no-op
KoSitValidator::isAvailable() ยอมรับ HTTP 200 และ 405 จากการตรวจสุขภาพ daemon โดย daemon ตอบ GET ด้วย 405 ขณะที่สุขภาพดี
การประทับตราของ AiReadyCertifier จะล้มเหลวแบบ fail-closed ด้วย InvalidArgumentException เมื่อเอกสารต้นฉบับขาดตาราง cross-reference แบบคลาสสิก (ตัวอย่างเช่น cross-reference stream)
XRechnungTestSuiteRunner::run() ปฏิเสธที่จะรันเมื่อ validator ไม่พร้อมใช้งานหรือชุดทดสอบไม่มีไฟล์ XML เมื่อเปิด useCuratedNegativeFallback มันจะแทนที่ด้วย corpus เชิงลบที่คัดสรรไว้เมื่อชุดทดสอบไม่ได้จัดส่งอินสแตนซ์ที่ไม่ถูกต้องมา

พฤติกรรมในโหมด FIPS

โมดูลนี้ไม่ทำการลงลายเซ็นและไม่เก็บรักษาคีย์ใด ๆ นโยบายอัลกอริทึมในโหมด FIPS ถูกกำกับโดยโมดูล Security และ Signature ส่วนความสอดคล้องของลายเซ็นถูกมอบหมายให้แก่ EU DSS ซึ่งเป็นผู้ตัดสินเอง

ความสอดคล้อง

เกตเวย์มอบหมายคำตัดสินความสอดคล้องให้แก่เครื่องมือภายนอก การออกแบบนี้สะท้อนขอบเขตของมาตรฐานเองที่ว่าความสอดคล้องถูกตัดสินเทียบกับข้อกำหนด ไม่ใช่ถูกยืนยันโดยผู้ผลิต

พฤติกรรม	เอกสารอ้างอิง
ภาระหน้าที่ของ conforming-processor ความสอดคล้องถูกตัดสินเทียบกับมาตรฐาน	ISO 19005-4:2020 §5.2
ข้อกำหนดไฟล์ PDF/A-4 เทียบกับการยืนยันตนเองของผู้ผลิต	ISO 19005-4:2020 §6.6.4
ความสอดคล้อง PDF/UA-2 เป็นคุณสมบัติของไฟล์	ISO 14289-2:2024 §6
ระดับลายเซ็น baseline ของ PAdES	ETSI EN 319 142-1 §5.4.3

เครื่องมือภายนอกเป็นผู้สร้างคำตัดสิน NextPDF ไม่ถือการรับรองใดและไม่มอบการรับรองใด การรองรับโปรไฟล์ไม่ใช่ความสอดคล้องกับโปรไฟล์นั้น ผลการตรวจสอบเป็นบันทึกการตรวจโครงสร้างเชิงเทคนิคสำหรับอ้างอิง ไม่ใช่ความเห็นทางกฎหมาย ปรึกษาทีมการปฏิบัติตามข้อกำหนดของคุณเพื่อตัดสินความเพียงพอทางการกำกับดูแล

หมายเหตุการพัฒนา

ผู้ปฏิบัติการเป็นผู้โฮสต์และดำเนินการ sidecar ปักหมุดเวอร์ชัน จำกัดการเข้าถึงเครือข่าย ตรวจสอบ TLS และควบคุมสภาพแวดล้อมที่เปิดใช้โหมด optional ปลายทาง sidecar เป็นขอบเขตความเชื่อถือ การควบคุมถิ่นที่อยู่และการเก็บรักษาเอกสาร ผลลัพธ์ และบันทึก เป็นความรับผิดชอบของผู้ปฏิบัติการ
เอาต์พุตของ buildComplianceMatrix() ถูกออกแบบมาเพื่อความสามารถในการสืบย้อนของ CI ปักหมุด commit SHA และจัดเก็บเมทริกซ์ไว้ข้างสิ่งประดิษฐ์ของการ build
ตัวรัน XRechnung คาดหวังชุดทดสอบอย่างเป็นทางการที่แตกไฟล์ไปยังไดเรกทอรีในเครื่อง ข้อความของคอนสตรัคเตอร์ระบุแหล่งดาวน์โหลดสาธารณะ
รายละเอียดกลไกภายในอยู่ในเอกสารภายในของ repository ต้นทางและอยู่นอกขอบเขตของคู่มือนี้

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น internal namespace paths, helper class, ตารางกลไก, ชื่อไฟล์ runbook และ ticket prefix อยู่นอกขอบเขต

ดูเพิ่มเติม

ภาพรวมความสามารถ Compliance
Validation — เอกสารอ้างอิงเชิงลึก
Evidence — เอกสารอ้างอิงเชิงลึก
Pro Compliance — e-invoice ในกระบวนการ (พื้นผิวที่แตกต่างกัน)
Core Conformance