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

Tổng quan nhanh

Module Compliance gộp ba bề mặt độc lập dưới NextPDF\Pro\Compliance:

• Báo cáo language-tag — một facade chính sách /Lang PDF/UA-2 nghiêm ngặt cùng một trình báo cáo sự kiện tuân thủ có cấu trúc, định hình theo PSR-3.
• Xử lý hóa đơn điện tử — xác thực Factur-X 1.08 / ZUGFeRD 2.4 theo mô hình ngữ nghĩa EN 16931, và phát sinh PDF/A-3 lai.
• Xuất xứ — nhúng và trích xuất các manifest store C2PA do bên gọi cung cấp qua một trình phân tích JUMBF được gia cố chống đối kháng; việc tổng hợp claim vẫn bị giới hạn ở chế độ preview.

Module báo cáo những gì nó kiểm tra. Nó không chứng nhận tài liệu và không thực hiện ký mã hóa.

Tình trạng khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt với một license envelope hạng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Không tồn tại cờ giấy phép theo từng tính năng. Đây là một năng lực của phiên bản Pro. Trình dựng claim C2PA thử nghiệm còn yêu cầu thêm một opt-in môi trường tường minh (xem Trường hợp ngoại lệ & chế độ lỗi).

Bề mặt Public API

composer require nextpdf/pro:^3

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
LangComplianceReporter::warn() / ::error()	string $tag, string $reason, ?string $clauseReference = null	Phát ra một bản ghi JSON có cấu trúc cho mỗi sự kiện language-tag qua logger PSR-3	void	JsonException nếu bản ghi thất bại khi mã hóa JSON	warn = từ chối chế độ lỏng; error = từ chối chế độ nghiêm ngặt
LangComplianceReporter::reportException()	InvalidBcp47TagException $exception, string $severity = 'error'	Trích xuất tag và lý do từ ngoại lệ; ủy quyền cho warn() hoặc error()	void	Như trên	Đường tiện lợi
LangComplianceReporter::buildRecord()	string $severity, string $tag, string $reason, ?string $clauseReference = null	Xây dựng mảng bản ghi mà không ghi nhật ký	array	Không ném lỗi	Cho các sink tùy chỉnh như bản tóm tắt JSON theo từng tệp
ConformancePolicy::default()	?LoggerInterface $logger = null	Chính sách UA-2 nghiêm ngặt: các tag /Lang dị dạng hoặc chưa đăng ký bị từ chối	self	Không ném lỗi	Mặc định v5.0 là nghiêm ngặt
ConformancePolicy::fromCore()	CoreConformancePolicy $core, ?LoggerInterface $logger = null	Bọc một chính sách Core hiện có nguyên trạng; không lật trục nào	self	Không ném lỗi	Ưu tiên default() cho tư thế nghiêm ngặt
ConformancePolicy::withStrictUa2()	bool $enabled	Trả về một bản sao với trục nghiêm ngặt được thiết lập; việc vô hiệu hóa phát ra một notice PSR-3	self	Không ném lỗi	Opt-out đã deprecated; mục tiêu loại bỏ 6.0.0
ConformancePolicy::isStrictUa2() / ::mode()	—	Đọc chính sách Core nền tảng	bool / ConformanceMode	Không ném lỗi	—
EInvoiceValidator::validate()	string $pdfPath	Pipeline đầy đủ: kiểm tra wrapper PDF/A-3, trích xuất tệp đính kèm, phát hiện hồ sơ, quy tắc EN 16931, Schematron	EInvoiceValidationResult	Lớp con EInvoiceException khi lỗi I/O, cấu trúc PDF dị dạng, hoặc công cụ gặp sự cố	Giao diện SPI đóng băng; một PDF không-phải-hóa-đơn-điện-tử được tạo đúng định dạng trả về một kết quả, không bao giờ ném lỗi
EInvoiceXmlValidator::validate()	string $xmlPayload, ValidatorContext $context	Kiểm tra sơ bộ cấu trúc cùng corpus quy tắc ngữ nghĩa sâu EN 16931 trên một payload CII	hợp đồng ValidationResult	Không ném lỗi với đầu vào không hợp lệ; việc từ chối hiển thị dưới dạng một kết quả thất bại kèm phát hiện	Bộ xác thực đa tầng cụ thể; đầu vào được kiểm soát qua XmlGuard
EInvoiceValidationResult::isValid()	—	Chỉ đúng khi wrapper, đặc tả đính kèm, hồ sơ, cú pháp đều thỏa và không tồn tại vi phạm FATAL nào	bool	Không ném lỗi	Chỉ mình danh sách vi phạm rỗng không phải là tính hợp lệ
EInvoiceValidationResult::notAnEInvoice()	—	Kết quả tất-cả-null, tất-cả-false có tính tất định	self	Không ném lỗi	Factory cho trường hợp “không phải hóa đơn lai”
EInvoiceProfile	enum nền chuỗi	Các case MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, được hậu thuẫn bởi các URN BT-24	—	—	isEn16931Conformant() là false với MINIMUM và BASIC_WL
EInvoiceSyntax	enum nền chuỗi	Các case UN_CEFACT_CII, UBL_INVOICE, UBL_CREDIT_NOTE	—	—	Chỉ CII là isFacturXEligible(); UBL chỉ dành cho bộ xác thực
BusinessRuleViolation	string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null	DTO vi phạm bất biến	—	—	Các họ rule-id BR-, BR-CO-, BR-CL-, BR-DEC-, BR-FXEXT-
BusinessRuleSeverity	enum nền chuỗi	FATAL làm mất hiệu lực hóa đơn; WARNING đánh dấu một mối lo về chất lượng	—	—	Phản chiếu các mức Schematron EN 16931
FacturXEmbedder::embed()	xem khối chữ ký	Bổ sung stream tệp nhúng, filespec, và XMP vào một nguồn PDF/A; ghi lại xref	void	EInvoiceException khi XML dị dạng, nguồn không đọc được, thiếu catalog, nguồn dùng object-stream hoặc xref-stream, hoặc lỗi ghi đầu ra	Tệp nguồn được giữ nguyên vẹn
FacturXEmbedderOptions::default()	—	/AFRelationship /Alternative, tên tệp factur-x.xml, loại INVOICE, phiên bản 1.0	self	Không ném lỗi	Mặc định thỏa yêu cầu bắt buộc của Đức và vẫn được chấp nhận ở Pháp
FacturXEmbedderOptions::withRelationship() / ::withFilename()	string	Trả về một bản sao với ghi đè được áp dụng	self	InvalidArgumentException khi nằm ngoài các tập chấp nhận	Các relationship: Source, Data, Alternative; tên tệp bao gồm zugferd-invoice.xml và xrechnung.xml
FacturXEmbedderOptions::withDocumentType()	string $documentType	Trả về một bản sao với ghi đè loại-tài-liệu XMP	self	Không ném lỗi	Các giá trị không được liệt kê phòng thủ
FacturXContractEmbedder::embed()	string $pdfBytes, string $xmlPayload, EmbedderOptions $options	Adapter byte-vào, byte-ra trên FacturXEmbedder qua các tệp tạm ngắn hạn	string	EInvoiceException; hồ sơ XRECHNUNG bị từ chối vì chỉ dành cho Enterprise	Triển khai EmbedderInterface đa tầng
C2paManifestEmbedder::embed()	string $pdfBytes, ManifestStore $store	Nhúng bản tuần tự hóa byte của store tại vị trí hồ sơ	string	C2paException khi bất kỳ lỗi nhúng nào	Giao diện SPI đóng băng; chỉ byte, không I/O
C2paManifestEmbedder::extract()	string $pdfBytes	Phân tích cú pháp một store nhúng qua trình phân tích JUMBF đã gia cố	ManifestStore|null	Lớp con C2paException khi một store hiện diện nhưng vi phạm một giới hạn gia cố	Null báo hiệu sự vắng mặt; sự vắng mặt không bao giờ ném lỗi
ManifestStore::fromBoxes() / ::empty()	list<JumbfBox> / —	Xây dựng value object store bất biến	self	Không ném lỗi	Thứ tự box mang tính quyết định cho sự bằng nhau khi khứ hồi
ManifestStore::toBytes() / ::isEmpty() / ::size()	—	Tuần tự hóa các box gốc; store rỗng tuần tự hóa thành một chuỗi rỗng	string / bool / int	Không ném lỗi	—
JumbfBoxParser::parse()	string $bytes	Phân tích cú pháp các box JUMBF cấp gốc dưới các giới hạn cứng	list<JumbfBox>	MalformedJumbfException, JumbfBombException, JumbfCycleDetectedException, JumbfDepthExceededException	Giới hạn: độ sâu 8, 64 MiB mỗi box, 128 MiB tổng, MAX_CHILDREN_PER_SUPERBOX 4096
JumbfBox::superbox() / ::leaf()	string $tbox, …	Xây dựng một box đã xác thực; toBytes() khứ hồi qua trình phân tích	self	MalformedJumbfException khi TBox không đúng chính xác 4 byte	—
C2paCapabilityStatus::current() / ::summary()	—	Báo cáo độ trưởng thành của năng lực C2PA, hiện tại là preview-draft	self / string	Không ném lỗi	Dấu hiệu preview có thể kiểm tra bằng máy
Feature::PREVIEW_C2PA_DRAFT->isEnabled()	—	Đọc môi trường tiến trình trên mỗi lời gọi; chỉ ký tự '1' nguyên văn mới bật	bool	Không ném lỗi	Biến môi trường NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT
ExperimentalC2paEmbedder::buildManifestStore()	string $sourceBytes, string $producer	Xây dựng một manifest store ghim theo bản nháp với một khẳng định claim hash-binding SHA-256	ManifestStore	Constructor ném LogicException khi cờ preview tắt	Preview; định dạng truyền được ghim theo một ảnh chụp bản nháp; không phát ra chữ ký claim nào

Chữ ký điểm vào, nguyên văn:

public static function default(?LoggerInterface $logger = null): self
public function withStrictUa2(bool $enabled): self
public function isStrictUa2(): bool

public function validate(string $pdfPath): EInvoiceValidationResult

public function embed(
    string $sourcePdfPath,
    string $xml,
    EInvoiceProfile $profile,
    string $outputPdfPath,
    ?FacturXEmbedderOptions $options = null,
): void

public function embed(string $pdfBytes, ManifestStore $store): string
public function extract(string $pdfBytes): ?ManifestStore

Hợp đồng hành vi

Báo cáo language-tag. LangComplianceReporter phát ra một bản ghi JSON có cấu trúc cho mỗi sự kiện language-tag PDF/UA-2. Mỗi bản ghi mang theo bộ phân biệt sự kiện cố định, một mức độ nghiêm trọng (warn cho từ chối chế độ lỏng, error cho từ chối chế độ nghiêm ngặt), tag vi phạm nguyên văn, một lý do máy-đọc-được, các thành phần tag đã phân tích cú pháp (hoặc null khi tag không thỏa ngữ pháp hình thái RFC 5646), một tham chiếu điều khoản ISO 14289-2 §8.4.4, và một dấu thời gian UTC với micro giây. JSON đi theo dạng thân thông điệp PSR-3; các sink hạ nguồn phân tích trực tiếp trường thông điệp. ConformancePolicy là facade Premium trên chính sách phù hợp Core. Mặc định của nó áp dụng xử lý ngôn ngữ UA-2 nghiêm ngặt và từ chối một tag dị dạng hoặc chưa đăng ký đi vào /Lang. Trình trợ giúp opt-out withStrictUa2(false) quay về hành vi lỏng cũ và ghi một notice PSR-3 khi giá trị hiệu lực thực sự thay đổi. NextPDF đánh dấu trình trợ giúp đó deprecated kể từ v5.0 với mục tiêu loại bỏ 6.0.0. Để di chuyển: rà soát corpus để tìm các giá trị /Lang dị dạng bằng composer pdfua2:audit-lang-tags <pdf-or-dir>, sửa chúng, rồi bỏ lời gọi opt-out.

Xử lý hóa đơn điện tử. EInvoiceValidator là hợp đồng SPI đóng băng cho việc xác thực PDF lai: kiểm tra wrapper PDF/A-3, trích xuất tệp đính kèm /AF, phát hiện hồ sơ từ định danh đặc tả BT-24, engine quy tắc nghiệp vụ EN 16931, và một lượt Schematron. Một PDF không-phải-Factur-X được tạo đúng định dạng trả về EInvoiceValidationResult::notAnEInvoice() thay vì ném lỗi; chỉ các lỗi I/O, cấu trúc PDF dị dạng, hoặc sự cố công cụ mới nâng lên một lớp con EInvoiceException. EInvoiceXmlValidator là bộ xác thực XML đa tầng cụ thể: nó kiểm soát đầu vào qua XmlGuard của Core, chạy kiểm tra sơ bộ cấu trúc và corpus quy tắc ngữ nghĩa sâu EN 16931, và thất bại đóng — các lỗi engine hiển thị dưới dạng phát hiện lỗi, không bao giờ là các lượt thông qua âm thầm. FacturXEmbedder sửa đổi một nguồn PDF/A thành một PDF/A-3 lai: nó bổ sung một stream tệp nhúng, một filespec với một /AFRelationship có thể cấu hình, và một gói mở rộng XMP Factur-X, rồi ghi lại bảng tham chiếu chéo cổ điển. Cả mảng /AF của catalog lẫn name tree /Names /EmbeddedFiles đều tham chiếu tệp đính kèm, nên các trình đọc ZUGFeRD cũ phân giải được nó.

Xuất xứ. C2paManifestEmbedder nhúng một manifest store C2PA do bên gọi cung cấp vào một chuỗi byte PDF, hoặc trích xuất một manifest. ManifestStore là value object bất biến đi qua ranh giới. Đường nối chỉ dùng byte và trung lập với nhà cung cấp: nó không tổng hợp các claim, không nạp các tham chiếu URI, và không phân giải các hash binding, và nó không thực hiện I/O mạng hay hệ thống tệp nào. extract() trả về null khi trượt và rẻ trên các PDF không có store. Mọi lần trích xuất khác-null đều đã vượt qua các giới hạn gia cố của JumbfBoxParser.

Module này báo cáo những gì nó kiểm tra. Nó không chứng nhận một tài liệu, không làm cho nó ràng buộc về mặt pháp lý, và không bảo đảm rằng bất kỳ đầu ra nào thỏa mãn một quy định. Bộ xác thực hóa đơn điện tử không phải là một bộ xác thực của cơ quan thuế và loại trừ các phần mở rộng quốc gia (ví dụ SDI của Ý, Chorus Pro của Pháp, XRechnung của Đức). Như EN 16931-1 nêu rõ, bên phát hành hóa đơn vẫn chịu trách nhiệm đáp ứng các quy tắc của pháp luật liên quan. Việc hỗ trợ một tiêu chuẩn không phải là sự phù hợp với tiêu chuẩn đó. Hãy tham vấn đội ngũ tuân thủ của bạn về tính đủ đáp ứng quy định.

Trường hợp ngoại lệ & chế độ lỗi

• Một PDF không-phải-Factur-X được tạo đúng định dạng trả về một kết quả “không phải hóa đơn điện tử”; nó không ném lỗi.
• Một danh sách vi phạm quy tắc nghiệp vụ rỗng tự nó không có nghĩa là tài liệu hợp lệ; các phép kiểm tra wrapper và đính kèm cũng được áp dụng.
• FacturXEmbedder thất bại đóng trên các nguồn dùng object stream nén (/Type /ObjStm) hoặc cross-reference stream (/Type /XRef, /XRefStm lai). Hãy lưu lại các nguồn đó với một bảng tham chiếu chéo cổ điển trước.
• Các payload XML được kiểm soát qua XmlGuard của Core: các khai báo DOCTYPE hoặc entity, đầu vào quá cỡ, và UTF-8 không hợp lệ bị từ chối với một EInvoiceException trên đường nhúng, hoặc một kết quả thất bại trên đường xác thực.
• FacturXContractEmbedder từ chối hồ sơ XRECHNUNG một cách rõ ràng thay vì âm thầm hạ cấp nó; việc phát sinh XRechnung là một năng lực Enterprise.
• C2paManifestEmbedder::extract() phân biệt sự vắng mặt (null) với sự dị dạng (lớp con C2paException nêu tên bất biến bị vi phạm: cấu trúc dị dạng, bom kích thước hoặc số lượng, chu trình offset, độ sâu lồng nhau).
• Việc khởi tạo ExperimentalC2paEmbedder ném một LogicException trừ khi cờ môi trường preview bằng '1'. Định dạng truyền của nó được ghim theo một ảnh chụp bản nháp C2PA và có thể thay đổi mà không báo trước; nó không phát ra chữ ký claim nào. Năng lực này vẫn ở chế độ preview cho đến khi hồ sơ PDF C2PA đóng băng.
• Opt-out lỏng UA-2 nghiêm ngặt đã deprecated; hãy di chuyển sang mặc định nghiêm ngặt (xem Hợp đồng hành vi).
• Module này không thực hiện ký mã hóa. Việc ký claim C2PA và giám hộ khóa nằm ngoài phạm vi; xem module Security để biết hành vi ký ở chế độ FIPS.

Tính phù hợp

Hành vi	Tham chiếu	Tình trạng
Khai báo ngôn ngữ tự nhiên (/Lang)	ISO 14289-2:2024 §8.4.4	Đã kiểm tra / báo cáo
Mô hình ngữ nghĩa hóa đơn lõi	EN 16931-1:2026	Đã kiểm tra (bên phát hành vẫn chịu trách nhiệm)
Tệp liên kết / stream tệp nhúng	ISO 32000-2:2020 §14.13.2	Đã phát sinh (/AF, /EF, /Params)
Quy tắc quan hệ đính kèm và container	Factur-X 1.08 §3.1, §6.2	Đã phát sinh / kiểm tra (mặc định /AFRelationship /Alternative)
Manifest store C2PA / JUMBF	C2PA 2.1 §11.1	Hỗ trợ nhúng / trích xuất; tổng hợp claim ở chế độ preview

Điều này ghi lại các đặc tả mà module được xây dựng theo và những gì nó kiểm tra hoặc phát sinh. Đây không phải là một phát biểu về chứng nhận hay tính đủ đáp ứng quy định. NextPDF không nắm giữ chứng nhận nào cho các tiêu chuẩn này.

Ghi chú phát triển

• Hình thái bản ghi của trình báo cáo là một hợp đồng ổn định; các quy tắc cảnh báo hạ nguồn có thể ghim theo bộ phân biệt sự kiện cố định.
• Việc vô hiệu hóa UA-2 nghiêm ngặt phát ra một thông báo deprecation hiển thị trong telemetry chỉ khi giá trị hiệu lực thay đổi; việc tái khẳng định giá trị hiện tại là âm thầm.
• Trình nhúng Factur-X giữ nguyên văn các byte nguồn và bổ sung các object mới; nó nhắm đến việc bảo toàn sự phù hợp PDF/A-3 nhưng không xác thực lại. Hãy đưa đầu ra qua một bộ xác thực PDF/A bên ngoài để có chứng thực chắc chắn.
• Đường nối C2PA đóng băng năm bất biến: không import bên thứ ba, hợp đồng chỉ byte, không I/O, trích xuất null-khi-trượt, và không tổng hợp claim trong tầng ổn định.
• Các giới hạn của JumbfBoxParser là các hằng số public; hãy định cỡ các đầu vào bạn chấp nhận theo chúng thay vì tự suy ra lại các giới hạn.

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ộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Hướng dẫn năng lực Compliance
• Preview C2PA
• Security — Tài liệu tham chiếu chuyên sâu
• Đặc tả