Pro 版本

Output Pipeline

速覽

Output Pipeline 會依依賴順序執行一份 PDF 步驟的宣告式清單，並支援逐步驟重試與遇錯即停選項。某些步驟型別需要額外的 Enterprise Pack 能力。

供應狀況與授權

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

管線執行器本身屬於 Pro 版本。另有三種步驟型別需要具名的 Enterprise Pack 能力：遮蔽步驟需要 Privacy Pack 能力，而擷取與 OCR-overlay 步驟需要 Intelligence Pack 能力。未授權的閘控步驟會在執行時 fail closed——它會產生一個失敗的步驟結果，且其解析器永遠不會被叫用——而非中止整個執行。

安裝

composer require nextpdf/pro:^3

程式碼位於 NextPDF\Pro\OutputPipeline 命名空間下。

概念總覽

PipelineExecutor 會接受一個 PipelineManifest，將步驟排入拓撲順序，並將每個步驟分派給註冊在 StepResolverRegistry 中的解析器。步驟輸出會存放在 PipelineContext 中，供下游步驟使用。執行器會強制一個全域逾時、支援逐步驟重試，並可從具名步驟恢復。它的設計是要在非同步工作背景工作者中執行，而非直接從請求處理器執行。

內建步驟型別包括 generate、merge、split、inspect、compress、sign 與 convert。redaction、extraction 與 OCR-overlay 步驟型別屬於能力授權，並對應到 Enterprise Pack 能力。

為何如此設計

執行器僅負責編排。它會排序步驟、強制執行授權閘門，並將每個步驟分派給已註冊的解析器，但本身不執行任何 PDF 工作。這樣的切分讓同一份清單既可透過這條循序的 PHP 路徑執行，也可透過在頻道外並行分派步驟的工作者執行，而呼叫端程式碼無須任何變更。此設計以非同步工作背景工作者為目標，而非請求處理器，因為多步驟管線往往會超出一次請求的預算，而佇列可藉由增加工作者來擴充吞吐量。全域逾時之所以在各步驟之間檢查，也是同樣的道理：一整個步驟就是交給解析器的工作單位，而編排者不介入該解析器的執行。失敗會以逐步驟的 StepResult 值呈現，而非拋出例外，因此單一失敗步驟永遠不會拖垮工作者所回報的整體 PipelineResult。

設計背景：大量文件產生。

行為合約

execute($manifest, $variables) 會回傳一個結果，內含整體狀態、逐步驟結果、執行時間，以及已完成與失敗步驟的計數。
步驟以拓撲順序執行；某個步驟型別缺少解析器時，會產生一個附帶清楚訊息的失敗步驟。
PipelineOptions::$stopOnError 會在第一次失敗時中止執行；否則執行會繼續，而最終狀態會反映任何失敗。
全域逾時若有設定，當在下一個步驟開始前超過時間時，會讓整條管線失敗。
逐步驟重試受所設定的上限界定；只有非終局性的失敗會被重試。
Resume-from-step 會略過較早的步驟，直到抵達具名步驟為止。
當缺少所需的 Pack 能力時，能力閘控步驟型別會在執行時以一個授權錯誤碼 fail closed；其解析器永遠不會被叫用。

程式碼範例——快速上手

以下反映已記載的公開 API。此模組的儲存庫並未隨附可執行範例。

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

程式碼範例——正式環境

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

邊界案例與陷阱

此管線的設計是要透過工作系統非同步執行。同步行內執行它會讓呼叫端阻塞整條管線的執行時間。
一個沒有註冊解析器的步驟型別只會讓該步驟失敗，而不會中止整條管線（除非設定了遇錯即停）。
全域逾時是在各步驟之間檢查，而非在步驟中途檢查；一個長時間執行的步驟可能在檢查觸發前就已超出預算。

效能

總執行時間是各步驟執行時間加上重試額外負擔的總和。全域逾時會界定最壞情況的牆鐘時間。沒有公布的吞吐量數字；管線成本主要由你納入的步驟主導。請以具代表性的清單量測。

安全注意事項

執行器會將輸入文件與變數傳給步驟解析器；請將它們視為不受信任，並在每個解析器內驗證。能力閘控步驟在未授權時會 fail closed。執行器不記錄任何文件內容。

一致性

執行器本身不執行任何格式一致性工作；一致性取決於各別的步驟解析器（generate、merge、split、sign、convert）。撰寫時 RAG 語料庫無法使用，因此本頁不主張任何外部條款識別碼。

Enterprise 邊界註記

Enterprise 在行為層級加入可解鎖閘控步驟型別（遮蔽、擷取、OCR overlay）的 Pack 能力。沒有那些 Pack，管線仍會執行每一個非閘控步驟。Pack 內部實作超出此處範圍。

Core 回退/替代方案

若無 Pro，請以 NextPDF Core API 命令式地編排 PDF 作業；宣告式清單、依賴排序與重試是 Pro 新增的功能。

發佈邊界

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