Enterprise phiên bản

Compliance — Tài liệu tham chiếu chuyên sâu

Nhìn tổng quan

Module Compliance định tuyến một PDF đã hoàn thiện tới một sidecar xác thực bên ngoài và trả về một kết quả đã chuẩn hóa. ComplianceGateway phân giải sidecar chịu trách nhiệm từ một ComplianceProfile, thực thi chính sách khả dụng fail-closed, và bọc mọi phán quyết của công cụ trong một ExternalValidationResult. Các bridge đi kèm cho veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (các mức PAdES), sidecar kết hợp Mustang/KoSIT (ZUGFeRD, Factur-X, EN 16931), và một daemon KoSIT độc lập. Module cũng cung cấp việc đóng dấu mức độ sẵn sàng AiReadyCertifier và một runner cho bộ kiểm thử KoSIT XRechnung chính thức.

Khả dụng và cấp phép

Capability này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và được kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có quyền sử dụng đó sẽ không nạp các lớp của capability. So sánh các phiên bản và lấy giấy phép.

Bề mặt Compliance/Evidence được cấp phép bởi capability enterprise.compliance.evidence. Một quyền sử dụng thiếu hoặc đã hết hạn sẽ từ chối tính năng; nó không âm thầm hạ cấp hành vi.

Bậc	Bề mặt Compliance
Core	Kiểm tra byte-stream và ngữ pháp trong tiến trình; không ủy quyền cho sidecar bên ngoài.
Pro	Xác thực EN 16931 / Factur-X / ZUGFeRD trong tiến trình; không có sidecar bên ngoài.
Enterprise	Cổng validator bên ngoài (module này) với một kết quả hợp nhất và một chính sách fail-closed.

Bộ xác thực hóa đơn điện tử trong tiến trình của Pro và sidecar ZUGFeRD bên ngoài của Enterprise là các bề mặt khác biệt. Cổng validator bên ngoài chỉ đi kèm trong gói nextpdf/enterprise.

Bề mặt Public API

composer require nextpdf/enterprise:^3

Symbol	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	Đánh chỉ mục validator theo tên công cụ	—	—	Chế độ tùy chọn hạ cấp việc kiểm tra khả dụng xuống chỉ-cảnh-báo
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	Phân giải validator theo `ComplianceProfile::toolName()`, kiểm tra khả dụng, ủy quyền	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (không có validator nào được đăng ký cho công cụ)	Chỉ trả về `null` ở chế độ tùy chọn khi sidecar ngừng hoạt động
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	Xác thực mọi profile ánh xạ tới công cụ	`list<ExternalValidationResult>`	Giống như `validate()`	Bỏ qua các kết quả `null` (chế độ tùy chọn)
`ComplianceGateway::healthCheck`	—	Thăm dò mọi endpoint health của sidecar đã đăng ký	`array<string, bool>`	—	Báo cáo khả năng tiếp cận; không xác thực tài liệu nào
`ComplianceGateway::buildComplianceMatrix` (static)	`list<ExternalValidationResult> $results`, `string $commitSha`	Rút gọn các kết quả thành một ma trận có phiên bản schema	`array<string, mixed>`	—	Phiên bản schema `1.0`; ghi lại đầu ra công cụ, không khẳng định điều gì
`ComplianceProfile` (enum)	15 case dựa trên string	Ánh xạ mỗi profile tới một nhãn tiêu chuẩn và một công cụ	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (interface)	—	Hợp đồng bridge sidecar trên PSR-18	—	`validate()` ném `ComplianceSidecarUnavailableException` khi lỗi truyền tải	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	Chữ ký interface	POST multipart tới sidecar veraPDF REST; phân tích báo cáo JSON	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (profile không được hỗ trợ)	PDF/A, PDF/UA, Arlington; chỉ phân tích JSON, không bao giờ XML
`DssValidator::validate`	Chữ ký interface	POST JSON Base64 tới sidecar EU DSS REST	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (profile không được hỗ trợ)	PAdES B-B đến B-LTA; constructor từ chối timeout dưới một giây
`ZugferdExternalValidator::validate`	Chữ ký interface	POST multipart tới sidecar kết hợp Mustang/KoSIT	`ExternalValidationResult`	`ComplianceSidecarUnavailableException` (cả khi circuit breaker mở); `InvalidArgumentException` (profile không được hỗ trợ)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931; circuit breaker tùy chọn được tiêm vào
`KoSitValidator::validate`	Chữ ký interface	POST XML thô tới một daemon KoSIT độc lập	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (profile không được hỗ trợ)	Chỉ EN 16931; phân tích báo cáo Schematron SVRL theo hướng fail-closed
`ExternalValidationResult`	Value object readonly	Phán quyết công cụ đã chuẩn hóa	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	Value object readonly	Một phát hiện đơn lẻ với rule id, clause, mức độ nghiêm trọng, vị trí	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	Tín hiệu sidecar không khả dụng theo hướng fail-closed	—	—	`toolName` và `endpoint` public readonly
`AiReadyCertifier::certify`	`string $pdfBytes`	Đánh giá ba tiêu chí sẵn sàng; đóng dấu provenance XMP	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException` (việc đóng dấu yêu cầu một bảng cross-reference cổ điển)	Phần tử thứ hai bằng đầu vào khi mức là `not_certified`
`AiReadyCertification`	Value object readonly	Đánh giá mức độ sẵn sàng với level, số tiêu chí, vấn đề, source hash	—	—	Nhãn sẵn sàng nội bộ, không phải chứng nhận theo tiêu chuẩn
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	Phân giải thư mục suite đã giải nén	—	`InvalidArgumentException` (thư mục không tồn tại)	Nhắm tới bộ kiểm thử KoSIT XRechnung chính thức
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	Xác thực mỗi instance của suite qua bridge	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException` (validator không khả dụng; không có tệp XML)	Cũng có `isAvailable()`, `getSuitePath()`, `discoverTestFiles()`
`XRechnungTestSuiteResult`	Value object readonly	Kết quả tổng hợp của suite	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	Value object readonly	Kết quả theo từng case	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	Constructor tĩnh	Tín hiệu lỗi runtime của suite	`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;
}

Hợp đồng hành vi

ComplianceGateway::validate() phân giải ExternalValidator đã đăng ký có getToolName() khớp với ComplianceProfile::toolName(), kiểm tra isAvailable(), ủy quyền, và trả về một ExternalValidationResult đã chuẩn hóa. Các quy tắc quan sát được từ bên ngoài:

Mặc định fail-closed. Khi sidecar được phân giải không khả dụng và chế độ tùy chọn đang tắt, lệnh gọi phát sinh ComplianceSidecarUnavailableException. Tài liệu không được kiểm tra; nó không bao giờ được coi là đã đạt.
Chế độ tùy chọn. Việc khởi tạo gateway với optional: true (người vận hành nối dây điều này từ biến môi trường NEXTPDF_COMPLIANCE_OPTIONAL) hạ cấp một sidecar không khả dụng xuống một cảnh báo được ghi log và một giá trị trả về null. Bên gọi phải coi null là “chưa được kiểm tra”. Chế độ tùy chọn chỉ bao phủ việc thăm dò khả dụng trước khi chạy; một lỗi truyền tải trong chính lệnh gọi xác thực sẽ phát sinh ComplianceSidecarUnavailableException ở cả hai chế độ.
Profile không xác định. Một profile không có validator đã đăng ký sẽ phát sinh InvalidArgumentException; nó không bao giờ âm thầm đạt.
Ngữ nghĩa đạt. ExternalValidationResult::passes() yêu cầu conformant là true và không có non-conformance nào. Mỗi kết quả mang theo profile, tên và phiên bản công cụ, số lượng assertion, các phát hiện, SHA-256 của các byte đã xác thực, một dấu thời gian UTC, và thời lượng lệnh gọi.
Ma trận là một bản ghi, không phải một khẳng định. buildComplianceMatrix() là một reducer tĩnh tạo ra một cấu trúc có phiên bản schema kèm theo phiên bản công cụ và một commit SHA để truy vết. Nó ghi lại đầu ra công cụ; nó không khẳng định điều gì.
Luồng dữ liệu. Toàn bộ byte stream của PDF được truyền tới sidecar đã cấu hình qua một client PSR-18. Mỗi lần xác thực được ghi log qua PSR-3 với profile, công cụ, đạt/không đạt, số lượng assertion, và thời lượng.

Định tuyến profile-tới-công cụ, như được trả về bởi ComplianceProfile::standardReference() và ::toolName():

Các case profile	Tham chiếu tiêu chuẩn	Công cụ
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (Level B; Level F cho 4f)	veraPDF
`pdfua-1`, `pdfua-2`	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
`pdf20-arlington`	ISO 32000-2:2020 (mô hình Arlington)	veraPDF
`pades-b-b`, `pades-b-t`, `pades-b-lt`, `pades-b-lta`	ETSI EN 319 142-1 B-B đến 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() đánh giá ba tiêu chí: sự hiện diện của chữ ký cấu trúc, sức khỏe LTV, và sự vắng mặt của mã hóa. Ba tiêu chí đạt sẽ cho mức certified; một hoặc hai cho partial; không tiêu chí nào cho not_certified. Ở mức certified hoặc partial, nó nối thêm một bản cập nhật tăng dần mang theo một stream provenance XMP và một override Catalog; các byte gốc không bao giờ bị thay đổi. Mức “certified” là một nhãn sẵn sàng nội bộ của NextPDF, không phải một chứng nhận theo tiêu chuẩn.

VeraPdfValidator chỉ phân tích các phản hồi sidecar dạng JSON (không XML; sạch XXE theo thiết kế). KoSitValidator phân tích báo cáo SVRL dạng XML của daemon với các khai báo DOCTYPE bị từ chối và truy cập mạng bị vô hiệu hóa, và coi một báo cáo không thể phân tích là một lỗi của lệnh gọi.

Trường hợp biên và chế độ lỗi

Timeout hoặc lỗi truyền tải của sidecar hiển thị như ComplianceSidecarUnavailableException từ bridge; mặc định fail-closed áp dụng.
Một phản hồi sidecar khác 200 tạo ra một kết quả không đạt với một phát hiện đặc thù theo công cụ (ví dụ VERAPDF-HTTP-ERROR); nó không bao giờ là một lần đạt phù hợp tiêu chuẩn.
Một thân JSON hoặc XML sidecar không đúng định dạng là một lỗi xác thực của lệnh gọi, không phải một lần đạt phù hợp tiêu chuẩn.
Kết quả EU DSS không có chữ ký sẽ thất bại với DSS-NO-SIGNATURES. Một indication khác TOTAL_PASSED sẽ thất bại với DSS-SIG-INVALID. Một mức chữ ký thấp hơn baseline mong đợi sẽ thất bại với DSS-LEVEL-MISMATCH.
DssValidator công bố ngân sách timeout theo từng yêu cầu trên mỗi yêu cầu qua header X-NextPDF-Timeout-Seconds; client PSR-18 của người tích hợp phải tôn trọng nó để một sidecar bị treo không thể chặn thread gọi vô thời hạn.
ZugferdExternalValidator tùy chọn định tuyến các lệnh gọi sidecar qua một circuit breaker được tiêm vào; một breaker mở ánh xạ tới ComplianceSidecarUnavailableException (fail-fast, vẫn fail-closed). Mặc định là một breaker no-op.
KoSitValidator::isAvailable() chấp nhận HTTP 200 và 405 từ việc thăm dò health của daemon; daemon trả lời GET bằng 405 khi vẫn khỏe mạnh.
Việc đóng dấu AiReadyCertifier thất bại theo hướng fail-closed với InvalidArgumentException khi tài liệu gốc thiếu một bảng cross-reference cổ điển (ví dụ, các cross-reference stream).
XRechnungTestSuiteRunner::run() từ chối chạy khi validator không khả dụng hoặc suite không chứa tệp XML nào; khi useCuratedNegativeFallback được bật, nó thay thế bằng một corpus tiêu cực được tuyển chọn khi suite không đi kèm instance không hợp lệ nào.

Hành vi ở chế độ FIPS

Module này không thực hiện việc ký và không lưu giữ khóa. Chính sách thuật toán ở chế độ FIPS do các module Security và Signature quản lý. Sự phù hợp chữ ký được ủy quyền cho EU DSS, vốn tự đưa ra phán quyết của riêng nó.

Phù hợp tiêu chuẩn

Gateway ủy quyền phán quyết phù hợp tiêu chuẩn cho một công cụ bên ngoài; thiết kế này phản ánh chính ranh giới của các tiêu chuẩn rằng sự phù hợp được xác định dựa trên các yêu cầu, chứ không phải do nhà sản xuất khẳng định.

Hành vi	Tham chiếu
Nghĩa vụ của processor phù hợp; sự phù hợp được xác định dựa trên tiêu chuẩn	ISO 19005-4:2020 §5.2
Yêu cầu tệp PDF/A-4 so với tự khẳng định của nhà sản xuất	ISO 19005-4:2020 §6.6.4
Sự phù hợp PDF/UA-2 là một thuộc tính của tệp	ISO 14289-2:2024 §6
Các mức chữ ký baseline PAdES	ETSI EN 319 142-1 §5.4.3

Công cụ bên ngoài tạo ra phán quyết. NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào; việc hỗ trợ một profile không phải là sự phù hợp với nó. Các kết quả xác thực là các bản ghi kiểm tra cấu trúc kỹ thuật để tham khảo, không phải ý kiến pháp lý; hãy tham khảo nhóm tuân thủ của bạn để đánh giá tính đầy đủ về mặt quy định.

Ghi chú phát triển

Người vận hành lưu trữ và vận hành các sidecar, ghim phiên bản của chúng, hạn chế phạm vi mạng của chúng, xác thực TLS của chúng, và kiểm soát môi trường cho phép chế độ tùy chọn. Các endpoint sidecar là một ranh giới tin cậy; các kiểm soát về nơi lưu trú và lưu giữ đối với tài liệu, kết quả, và log là trách nhiệm của người vận hành.
Đầu ra của buildComplianceMatrix() được thiết kế cho việc truy vết CI: ghim commit SHA và lưu trữ ma trận bên cạnh các build artifact.
Runner XRechnung mong đợi bộ kiểm thử chính thức được giải nén vào một thư mục cục bộ; thông điệp constructor của nó nêu tên nguồn tải xuống công khai.
Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của repository nguồn và nằm ngoài phạm vi của tài liệu hướng dẫn này.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, lớp helper, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Xem thêm

Tổng quan capability Compliance
Validation — tài liệu tham chiếu chuyên sâu
Evidence — Tài liệu tham chiếu chuyên sâu
Pro Compliance — hóa đơn điện tử trong tiến trình (bề mặt khác biệt)
Core Conformance