輸出管線

速覽

NextPDF Enterprise 會以可設定的並行上限，以及對已完成輸出的選用合規交接，協調 NextPDF Pro 輸出管線清單的大規模批次執行。它是建構在 Pro 輸出管線之上的批次層。

供應與授權

此能力隨附於 NextPDF Enterprise（nextpdf/enterprise），並以 Enterprise 層級的授權封套啟用。缺少該授權的部署不會載入此能力的類別。比較各版本並取得授權。

Enterprise 批次介面建構於 Pro 輸出管線（pro.output.pipeline）之上，後者是先決條件而非閘門。並沒有獨立的逐功能能力碼；只要安裝了已授權的 nextpdf/enterprise 套件，批次協調器與合規交接即可使用。

安裝

composer require nextpdf/enterprise:^3

概念總覽

BatchPipelineOrchestrator 會將許多 PipelineManifest 實例作為一個批次執行。每份清單都會經由 Pro 的 PipelineExecutor 執行；協調器則加入批次協調、一個有界資源防護（每批次的清單數量設有上限）、逐批次的逾時處理，以及一個選用的合規交接。

BatchPipelineConfig 控制三件事：最大並行 worker 回呼數、一個以毫秒為單位的選用全域批次逾時，以及在管線完成後是否對每份輸出執行合規檢查。當合規檢查啟用時，ComplianceHandoff 會整合為一個管線步驟，透過 Enterprise 合規閘道重新驗證每份衍生 PDF，使被管線修改過的文件會被重新檢查，而非沿用其修改前的狀態信任。

在正式環境部署中，並行的 worker 派送與背壓由一個獨立的執行 sidecar 處理；此處所述的 PHP 協調器提供批次協調與合規交接邏輯，並由作業 worker 而非請求處理器直接呼叫。

為何如此設計

大量批次生成可拆分為兩項關注點：協調哪些清單在何種保證下執行，以及驅動原始的並行吞吐。NextPDF 將協調與合規語意保留在這個具決定性的 PHP 協調器中，並將並行的 worker 派送與背壓委派給一個獨立的執行 sidecar。該邊界讓吞吐層得以獨立擴展並行度，同時讓協調器保持簡單、有界且可稽核。每批次清單數量的硬性上限使尖峰記憶體可預測，因此單一大型提交無法拖垮 worker 池。合規交接會重新驗證每份衍生輸出，而非信任其修改前的狀態，並且採失敗即關閉。一份完成的清單唯有在閘道確認其一致性時才會通過，絕不預設通過。

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

API 介面

類別	職責
BatchPipelineOrchestrator	以有界並行將許多清單作為一個批次執行。
BatchPipelineConfig	最大並行數、批次逾時、完成時合規檢查開關。
BatchPipelineResult	彙總：逐清單結果、已完成與失敗計數、計時。
ComplianceHandoff	選用的管線末端合規重新驗證步驟。

程式碼範例——快速上手

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;

$result = (new BatchPipelineOrchestrator($executor))->executeBatch($manifests);

程式碼範例——正式環境

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;
use NextPDF\Enterprise\OutputPipeline\BatchPipelineConfig;

$config = new BatchPipelineConfig(
    maxConcurrency: 4,
    timeoutMs: 600_000,
    complianceCheckOnComplete: true,
);

$result = (new BatchPipelineOrchestrator($executor, $config))
    ->executeBatch($manifests, $variablesMap);

$logger->info('pipeline.batch', [
    'completed' => $result->completedCount,
    'failed'    => $result->failedCount,
]);

邊界案例與陷阱

• 批次會對清單數量強制執行一個上界；超過它會引發資源防護錯誤，而非默默地降級。
• 全域逾時為零代表沒有批次逾時；請在正式環境中設定一個有限值，使卡住的清單不會無限期阻擋批次。
• 合規交接需要上游步驟輸出中有一份可辨識的 PDF；若找不到，該步驟會為那份清單回報一個失敗，而非默默通過。
• 本模組依賴 Pro 輸出管線；它加入的是批次協調，而非一套新的步驟模型。

效能

吞吐量會隨設定的並行數與逐清單成本而擴展。並行數相對於 worker 池應保守設定，以免回呼把它佔滿。逐批次的清單上限會界定尖峰記憶體。

安全注意事項

批次協調器會處理呼叫端提供的任何清單與變數；請以對待任何其他不可信 PDF 工作負載的方式對待管線輸入。合規交接是一項重新驗證的輔助，而非一項授權控制。

資料落地與 PII 緩解措施

批次輸出可能含有個人資料。處理在行程內於本機進行；此協調器不進行任何對外網路呼叫。請對批次輸出套用你自己的保留控制措施。

安全遙測與日誌清洗

批次結果回報計數與計時，而非文件內容。若清單識別碼編碼了租戶或案件資料，請從日誌中將其清洗。

一致性

本模組不主張任何標準一致性；它是一個協調層。選用的合規交接會委派給 Enterprise 合規閘道，而後者帶有其自有的參考。

FIPS 模式行為

本模組不進行任何加密運算。

威脅模型

主要輸入是呼叫端提供的清單與變數。緩解措施：每批次清單數量的硬性上限、有界並行、對衍生輸出的選用重新驗證，以及協調器本身不進行任何網路 I/O。

行為合約

• executeBatch() 會將每份清單經由 Pro 管線執行器執行，並回傳帶有已完成與失敗計數及計時的逐清單結果。
• 一個硬性上限會界定每批次的清單數量；超過它會引發資源防護錯誤，而非默默地降級。
• 全域逾時為零代表沒有批次逾時；一個有限值會界定卡住的清單。
• 啟用時，合規交接會重新驗證每份衍生 PDF，並在上游找不到可辨識 PDF 時回報一個步驟失敗，而非默默通過。

發佈邊界

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

Core 回退

NextPDF Core 沒有任何輸出管線模型。僅有 Core 的部署會直接針對 Core API 自行組合步驟；沒有清單、沒有批次協調，也沒有合規交接。

Pro 回退

在僅有 Pro 的部署中，受支援的介面是單份清單的 Pro 輸出管線（pro.output.pipeline）：Pro 的 PipelineExecutor 一次執行一份清單。Pro 不提供批次協調器、有界並行批次防護、逐批次逾時或 Enterprise 合規交接；在僅有 Pro 的部署中，請求批次協調或合規交接的設定，沒有任何 Enterprise 元件能滿足它。Pro 管線介面請參閱 Pro 總覽。

Enterprise 邊界註記

批次協調、資源防護界限與合規交接接線皆僅以行為層級描述。內部的 sidecar 派送協定、內部的背壓語意，以及內部的合規閘道接線，皆不在公開介面範圍內，此處不予重現。

部署邊界

在正式環境中，並行的 worker 派送與背壓由一個獨立的執行 sidecar 處理；此處所述的 PHP 協調器提供批次協調與合規交接邏輯，並由作業 worker 而非請求處理器直接呼叫。Worker 池大小、sidecar 佈建，以及相對於 PHP worker 池的並行上限皆為運維人員的責任。合規交接是一項重新驗證的輔助，而非一項授權控制。

法律合規邊界

選用的合規交接會對衍生文件重新執行一次驗證。它回報發現；它不對任何文件進行認證、不保證法規充分性，也不構成法律建議。判斷某份輸出是否符合你的義務是你的責任。

另請參閱

• 輸出管線（Enterprise 參考） — 批次協調器 API 參考。
• Pro 總覽 — 其底層的輸出管線。
• Enterprise 總覽
• Core、Pro 與 Enterprise 功能對照表