Pro 版本

合規 — 深入參考

概覽

Compliance 模組將三個獨立的介面彙整於 NextPDF\Pro\Compliance 之下：

語言標籤回報 — 一個嚴格的 PDF/UA-2 /Lang 政策外觀（facade），外加一個結構化、PSR-3 型態的合規事件回報器。
電子發票處理 — 依 EN 16931 語意模型進行的 Factur-X 1.08 / ZUGFeRD 2.4 驗證，以及混合式 PDF/A-3 產出。
來源證明 — 透過一個對抗性強化的 JUMBF 剖析器，嵌入與擷取呼叫端提供的 C2PA 清單儲存區；聲明合成仍受 preview 閘控。

此模組回報它所檢查的內容。它不認證文件，也不執行密碼學簽署。

可用性與授權

此功能隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級的授權封套啟用。缺少該授權的部署不會載入此功能的類別。比較版本並取得授權。

不存在逐功能授權旗標。這是一項 Pro 版本功能。實驗性的 C2PA 聲明建構器另外需要一個明確的環境選擇加入（見「邊界案例與失效模式」）。

公開 API 介面

composer require nextpdf/pro:^3

符號	參數	預設行為	回傳	拋出或失敗於	備註
`LangComplianceReporter::warn()` / `::error()`	`string $tag, string $reason, ?string $clauseReference = null`	透過 PSR-3 logger 為每個語言標籤事件發出一筆結構化 JSON 記錄	`void`	若記錄的 JSON 編碼失敗則拋出 `JsonException`	`warn` = lax 模式拒絕；`error` = strict 模式拒絕
`LangComplianceReporter::reportException()`	`InvalidBcp47TagException $exception, string $severity = 'error'`	從例外中擷取標籤與原因；委派給 `warn()` 或 `error()`	`void`	同上	便利路徑
`LangComplianceReporter::buildRecord()`	`string $severity, string $tag, string $reason, ?string $clauseReference = null`	建構記錄陣列而不記錄日誌	`array`	不拋出	用於自訂接收端，例如逐檔 JSON 摘要
`ConformancePolicy::default()`	`?LoggerInterface $logger = null`	嚴格 UA-2 政策：格式錯誤或未註冊的 `/Lang` 標籤會被拒絕	`self`	不拋出	v5.0 預設為嚴格
`ConformancePolicy::fromCore()`	`CoreConformancePolicy $core, ?LoggerInterface $logger = null`	原樣包裝一個既有的 Core 政策；不翻轉任何軸	`self`	不拋出	若要嚴格姿態，優先使用 `default()`
`ConformancePolicy::withStrictUa2()`	`bool $enabled`	回傳一份已設定嚴格軸的副本；停用時發出一則 PSR-3 `notice`	`self`	不拋出	已棄用的選擇退出；移除目標 `6.0.0`
`ConformancePolicy::isStrictUa2()` / `::mode()`	—	讀取底層的 Core 政策	`bool` / `ConformanceMode`	不拋出	—
`EInvoiceValidator::validate()`	`string $pdfPath`	完整流程：PDF/A-3 包裝檢查、附件擷取、設定檔偵測、EN 16931 規則、Schematron	`EInvoiceValidationResult`	在 I/O 失敗、PDF 結構格式錯誤或工具崩潰時拋出 `EInvoiceException` 子類別	凍結的 SPI 介面；一份格式正確的非電子發票 PDF 會回傳結果，絕不拋出
`EInvoiceXmlValidator::validate()`	`string $xmlPayload, ValidatorContext $context`	結構前置檢查，外加對 CII 酬載執行 EN 16931 深度語意規則語料庫	合約 `ValidationResult`	對無效輸入不拋出；拒絕會以帶有發現項的失敗結果呈現	具體的跨層驗證器；輸入透過 `XmlGuard` 閘控
`EInvoiceValidationResult::isValid()`	—	僅當包裝、附件規格、設定檔、語法皆成立且不存在 FATAL 違規時才為 true	`bool`	不拋出	單憑空的違規清單並不構成有效性
`EInvoiceValidationResult::notAnEInvoice()`	—	決定性的全 null、全 false 結果	`self`	不拋出	用於「並非混合式發票」情形的工廠
`EInvoiceProfile`	字串型 enum	案例 `MINIMUM`、`BASIC_WL`、`BASIC`、`EN16931`、`EXTENDED`，以 BT-24 URN 為後盾	—	—	`isEn16931Conformant()` 對 `MINIMUM` 與 `BASIC_WL` 為 false
`EInvoiceSyntax`	字串型 enum	案例 `UN_CEFACT_CII`、`UBL_INVOICE`、`UBL_CREDIT_NOTE`	—	—	只有 CII 是 `isFacturXEligible()`；UBL 僅供驗證
`BusinessRuleViolation`	`string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null`	不可變的違規 DTO	—	—	規則 id 族群 `BR-`、`BR-CO-`、`BR-CL-`、`BR-DEC-`、`BR-FXEXT-`
`BusinessRuleSeverity`	字串型 enum	`FATAL` 使發票無效；`WARNING` 標記品質疑慮	—	—	對映 EN 16931 Schematron 層級
`FacturXEmbedder::embed()`	見簽章區塊	將嵌入檔串流、filespec 與 XMP 附加到 PDF/A 來源；重寫 xref	`void`	在 XML 格式錯誤、來源無法讀取、缺少 catalog、物件串流或 xref 串流來源，或輸出寫入失敗時拋出 `EInvoiceException`	來源檔案保持不變
`FacturXEmbedderOptions::default()`	—	`/AFRelationship /Alternative`、檔名 `factur-x.xml`、類型 `INVOICE`、版本 `1.0`	`self`	不拋出	預設值滿足德國強制規定，且在法國仍被接受
`FacturXEmbedderOptions::withRelationship()` / `::withFilename()`	`string`	回傳一份套用了覆寫的副本	`self`	超出接受集合時拋出 `InvalidArgumentException`	關係：`Source`、`Data`、`Alternative`；檔名包含 `zugferd-invoice.xml` 與 `xrechnung.xml`
`FacturXEmbedderOptions::withDocumentType()`	`string $documentType`	回傳一份帶有 XMP 文件類型覆寫的副本	`self`	不拋出	這些值未經防禦性列舉
`FacturXContractEmbedder::embed()`	`string $pdfBytes, string $xmlPayload, EmbedderOptions $options`	透過短生命週期暫存檔，覆蓋於 `FacturXEmbedder` 之上的位元組進、位元組出轉接器	`string`	`EInvoiceException`；`XRECHNUNG` 設定檔因僅限 Enterprise 而被拒絕	跨層 `EmbedderInterface` 實作
`C2paManifestEmbedder::embed()`	`string $pdfBytes, ManifestStore $store`	在設定檔位置嵌入儲存區的位元組序列化	`string`	任何嵌入失敗時拋出 `C2paException`	凍結的 SPI 介面；僅位元組，無 I/O
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	透過強化的 JUMBF 剖析器剖析嵌入的儲存區	`ManifestStore\|null`	當儲存區存在但違反某項強化上限時，拋出 `C2paException` 子類別	null 表示不存在；不存在絕不拋出
`ManifestStore::fromBoxes()` / `::empty()`	`list<JumbfBox>` / —	建構不可變的儲存區值物件	`self`	不拋出	盒子順序對來回相等性具承載作用
`ManifestStore::toBytes()` / `::isEmpty()` / `::size()`	—	序列化根盒子；空儲存區序列化為空字串	`string` / `bool` / `int`	不拋出	—
`JumbfBoxParser::parse()`	`string $bytes`	在硬性上限下剖析根層 JUMBF 盒子	`list<JumbfBox>`	`MalformedJumbfException`、`JumbfBombException`、`JumbfCycleDetectedException`、`JumbfDepthExceededException`	上限：深度 8、每盒 64 MiB、總計 128 MiB、`MAX_CHILDREN_PER_SUPERBOX` 4096
`JumbfBox::superbox()` / `::leaf()`	`string $tbox, …`	建構一個經驗證的盒子；`toBytes()` 可透過剖析器來回轉換	`self`	當 TBox 不恰好為 4 個位元組時拋出 `MalformedJumbfException`	—
`C2paCapabilityStatus::current()` / `::summary()`	—	回報 C2PA 功能成熟度，目前為 `preview-draft`	`self` / `string`	不拋出	機器可檢核的 preview 標記
`Feature::PREVIEW_C2PA_DRAFT->isEnabled()`	—	每次呼叫皆讀取行程環境；只有字面值 `'1'` 才啟用	`bool`	不拋出	環境變數 `NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT`
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes, string $producer`	建構一個釘選於草案的清單儲存區，帶有一筆 SHA-256 雜湊綁定聲明主張	`ManifestStore`	當 preview 旗標關閉時，建構子拋出 `LogicException`	Preview；線路格式釘選於一份草案快照；不發出聲明簽章

進入點簽章，逐字：

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

行為合約

語言標籤回報。 LangComplianceReporter 會為每個 PDF/UA-2 語言標籤事件發出一筆結構化 JSON 記錄。每筆記錄承載固定的事件鑑別子、一個嚴重度（lax 模式拒絕為 warn，strict 模式拒絕為 error）、逐字的引起問題標籤、一個機器可讀的原因、剖析後的標籤元件（或當標籤未通過 RFC 5646 形態文法時為 null）、一個 ISO 14289-2 §8.4.4 條款參照，以及一個帶微秒的 UTC 時間戳記。此 JSON 以 PSR-3 訊息主體傳遞；下游接收端直接剖析 message 欄位。ConformancePolicy 是覆蓋於 Core 一致性政策之上的 Premium 外觀。其預設套用嚴格的 UA-2 語言處理，並拒絕一個抵達 /Lang 的格式錯誤或未註冊標籤。選擇退出輔助 withStrictUa2(false) 會還原為舊版寬鬆行為，並在有效值確實變更時記錄一則 PSR-3 notice。NextPDF 自 v5.0 起將該輔助標記為已棄用，移除目標為 6.0.0。要遷移：使用 composer pdfua2:audit-lang-tags <pdf-or-dir> 稽核語料庫中格式錯誤的 /Lang 值、加以修正，接著移除該選擇退出呼叫。

電子發票處理。 EInvoiceValidator 是混合式 PDF 驗證的凍結 SPI 合約：PDF/A-3 包裝檢查、/AF 附件擷取、從 BT-24 規格識別碼進行的設定檔偵測、EN 16931 商業規則引擎，以及一次 Schematron 通道。一份格式正確的非 Factur-X PDF 會回傳 EInvoiceValidationResult::notAnEInvoice() 而非拋出例外；只有 I/O 失敗、PDF 結構格式錯誤或工具崩潰才會拋出 EInvoiceException 子類別。EInvoiceXmlValidator 是具體的跨層 XML 驗證器：它透過 Core XmlGuard 閘控輸入，執行結構前置檢查與深度的 EN 16931 語意規則語料庫，並以失敗關閉（fail closed）— 引擎錯誤會以錯誤發現項呈現，絕不靜默通過。FacturXEmbedder 會將一份 PDF/A 來源修訂為混合式 PDF/A-3：它附加一個嵌入檔串流、一個帶可設定 /AFRelationship 的 filespec，以及一個 Factur-X XMP 延伸封包，接著重寫傳統的交叉參照表。catalog /AF 陣列與 /Names /EmbeddedFiles 名稱樹皆會參照該附件，因此舊版 ZUGFeRD 讀取器能解析它。

來源證明。 C2paManifestEmbedder 會將呼叫端提供的 C2PA 清單儲存區嵌入一個 PDF 位元組字串，或從中擷取一個。ManifestStore 是跨越邊界的不可變值物件。此接縫僅位元組且供應商中立：它不合成聲明、不擷取 URI 參照，也不解析雜湊綁定，且不執行任何網路或檔案系統 I/O。extract() 在未命中時回傳 null，且在沒有儲存區的 PDF 上開銷低廉。每一次非 null 的擷取都已通過 JumbfBoxParser 強化上限。

此模組回報它所檢查的內容。它不認證一份文件、不使其具法律約束力，也不保證任何輸出滿足某項法規。此電子發票驗證器不是稅務機關驗證器，並排除各國延伸（例如義大利 SDI、法國 Chorus Pro、德國 XRechnung）。如同 EN 16931-1 所述，發票開立者仍須負責滿足相關法規的規則。對某項標準的支援並不等於對它的一致性。關於法規充分性，請諮詢你的合規團隊。

邊界案例與失效模式

一份格式正確的非 Factur-X PDF 會回傳一個「並非電子發票」的結果；它不會拋出例外。
一份空的商業規則違規清單本身並不代表文件有效；包裝與附件檢查也同樣適用。
FacturXEmbedder 對使用壓縮物件串流（/Type /ObjStm）或交叉參照串流（/Type /XRef、混合式 /XRefStm）的來源會失敗關閉。請先以傳統交叉參照表重新儲存此類來源。
XML 酬載透過 Core XmlGuard 閘控：DOCTYPE 或實體宣告、過大的輸入，以及無效的 UTF-8，在嵌入路徑上會以 EInvoiceException 拒絕，或在驗證器路徑上以失敗結果拒絕。
FacturXContractEmbedder 會明確拒絕 XRECHNUNG 設定檔，而非靜默降級；XRechnung 產出是一項 Enterprise 功能。
C2paManifestEmbedder::extract() 會區分不存在（null）與格式錯誤（C2paException 子類別，會指名被違反的不變量：結構格式錯誤、大小或計數炸彈、偏移循環、巢狀深度）。
ExperimentalC2paEmbedder 的建構會拋出 LogicException，除非 preview 環境旗標等於 '1'。它的線路格式釘選於一份 C2PA 草案快照，且可能不經通知而變更；它不發出任何聲明簽章。此功能會維持 preview，直到 C2PA PDF 設定檔凍結為止。
嚴格 UA-2 的寬鬆選擇退出已棄用；請遷移到嚴格預設（見「行為合約」）。
此模組不執行密碼學簽署。C2PA 聲明簽署與金鑰保管超出範圍；FIPS 模式簽署行為請參閱 Security 模組。

一致性

行為	參考	狀態
自然語言宣告（`/Lang`）	ISO 14289-2:2024 §8.4.4	已檢查/已回報
核心發票語意模型	EN 16931-1:2026	已檢查（開立者仍須負責）
關聯檔案/嵌入檔串流	ISO 32000-2:2020 §14.13.2	已產出（`/AF`、`/EF`、`/Params`）
附件關係與容器規則	Factur-X 1.08 §3.1, §6.2	已產出/已檢查（預設 `/AFRelationship /Alternative`）
C2PA 清單儲存區/JUMBF	C2PA 2.1 §11.1	支援嵌入/擷取；聲明合成為 preview

此處記錄此模組所依循建構的規範，以及它所檢查或產出的內容。它不是認證或法規充分性的陳述。NextPDF 未持有這些標準的任何認證。

開發備註

回報器的記錄形態是一份穩定合約；下游告警規則可釘選於固定的事件鑑別子。
停用嚴格 UA-2 只有在有效值變更時才會發出遙測可見的棄用通知；重新斷言目前的值則是靜默的。
Factur-X 嵌入器會逐字保留來源位元組並附加新物件；它力求保留 PDF/A-3 一致性，但不會重新驗證。若要硬性佐證，請將輸出送過外部 PDF/A 驗證器。
C2PA 接縫凍結五項不變量：無第三方匯入、僅位元組合約、無 I/O、未命中回傳 null 的擷取，以及穩定層中不進行聲明合成。
JumbfBoxParser 的上限是公開常數；請依據它們來設定你所接受輸入的大小，而非重新推導限制。

發佈邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名，以及票券前綴皆不在範圍內。