Interop

速覽

NextPDF Pro 提供一組版本化的結果資料傳輸物件（DTO），會將 PDF 分析輸出 —— 文件資訊、頁面、文字區塊、分段與表單資料 —— 序列化為一個穩定、綱要鎖定的 JSON 形態，供外部系統與工具消費。

可用性與授權

此能力隨附於 NextPDF Pro（nextpdf/pro），並以 Pro 等級的授權封套啟用。沒有該授權的部署不會載入此能力的類別。Interop 是 Pro 版本的一部分；並沒有獨立的逐功能授權旗標。比較各版本並取得授權。

安裝

composer require nextpdf/pro:^3

概念總覽

當 PDF 處理輸出跨越行程或服務邊界時，接收方需要一個穩定的合約。Interop V1 介面提供了這一點：

• InteropResultInterface —— 每個結果 DTO 都實作此介面。每一個都會序列化為一個 JSON 安全的陣列（永遠承載一個 schema_version 鍵），以及一個 JSON 字串。
• 結果 DTO —— DocumentInfo、PageInfo、BoundingBox、ExtractedText / ExtractedPage / TextBlock、DocumentSegmentation / Segment，以及 FormData / FormField。每一個都是某一項分析結果的不可變視圖。
• SchemaLock —— 一道 CI 防護。它持有凍結綱要的 SHA-256，並在綱要檔案變更卻沒有對應的版本提升時讓建置失敗，因此線路合約無法默默漂移。

Interop 介面是明確版本化的（SCHEMA_VERSION）。請將它視為一個公開 API 合約：增添式的變更提升綱要；破壞性的變更需要一個新的主要版本。

為何這樣設計

序列化的形態被當作一個公開 API 合約，而非實作細節。每個 DTO 都承載一個 schema_version 鍵，因此消費者是依據所收到的形態分支，而非用猜的。SchemaLock 在 CI 中釘住凍結綱要的 SHA-256，因此格式無法在沒有版本提升的情況下漂移。這正是讓外部系統能安全地依 JSON 建置的原因：合約只在版本移動時才移動。輸出保持可攜 —— 是你所擁有、已記載且版本化的資料，而不是一個在你腳下變動的形態。

設計背景：開放核心，不鎖定。

API 介面

類別	職責
InteropResultInterface	共通的序列化合約。
DocumentInfo, PageInfo, BoundingBox	共通的文件/頁面 DTO。
ExtractedText, ExtractedPage, TextBlock	文字抽取 DTO。
DocumentSegmentation, Segment	文件分段 DTO。
FormData, FormField	表單資料 DTO。
SchemaLock	CI 綱要漂移防護。

程式碼範例 —— 快速上手

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

程式碼範例 —— 正式環境

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

邊界案例與陷阱

• toArray() 永遠包含 schema_version；下游消費者應依它分支。
• 若綱要檔案遺失或被修改，SchemaLock::verify() 會回傳 false。
• 這些 DTO 是唯讀視圖；它們不會重新執行分析。

效能

序列化與結果圖（result graph）的大小呈線性關係。

安全注意事項

DTO 只承載你所填入的分析輸出。序列化期間不會發生任何檔案系統或網路 I/O。

一致性

Interop 定義的是一個由 NextPDF 擁有的版本化綱要；它不實作任何外部標準。

行為合約

• 每個結果 DTO 都實作 InteropResultInterface，並序列化為一個 JSON 安全的陣列（永遠承載一個 schema_version 鍵），以及一個 JSON 字串。
• 結果 DTO（DocumentInfo、PageInfo、BoundingBox、ExtractedText/ExtractedPage/TextBlock、DocumentSegmentation/Segment、FormData/FormField）是不可變的唯讀視圖；它們不會重新執行分析。
• SchemaLock::verify() 持有凍結綱要的 SHA-256，並在綱要檔案遺失或被修改時回傳 false，因此線路合約無法默默漂移。
• 此介面是明確版本化的（SCHEMA_VERSION）：增添式的變更提升綱要；破壞性的變更需要一個新的主要版本。
• 序列化期間不會發生任何檔案系統或網路 I/O。

Enterprise 邊界註記

Enterprise 不會改變 Interop 的行為。Enterprise 新增更高等級的功能，另行記載；它們對於使用版本化結果 DTO 並非必要。

Core 回退/替代方案

綱要鎖定、版本化的結果 DTO 沒有任何 Core 對應方案。這是一項 Pro 的新增功能。

發佈邊界

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

另請參閱

• Extraction —— 產生文字與分段結果。
• Form —— 產生表單資料結果。
• Interop —— 深入參考 —— 完整的 DTO 欄位參考。