Enterprise 版本

Output Pipeline — 深度参考

概览

NextPDF\Enterprise\OutputPipeline 将许多 Pro 管线清单作为一个批次执行。BatchPipelineOrchestrator 用批量协调包裹 Pro 的 PipelineExecutor：一个针对批量大小的有界资源守卫、一个可选的全局批量超时、逐清单变量注入，以及聚合计数。一个可选的批次末端合规检查会通过 Enterprise 合规网关对每份已完成的输出重新校验，并且失败即关闭（fail closed）。每次运行都返回一个 BatchPipelineResult，其中携带逐清单结果、完成数与失败数、计时，以及那份可选的合规报告。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）发行，并以一份 Enterprise 层级的授权信封激活。没有该授权凭据的部署不会加载此能力的类。比较各版本并获取授权。

层级	Output-pipeline 接口面
Core	无 output-pipeline 接口面。
Pro	单清单管线（能力 `pro.output.pipeline`）。
Enterprise	批量编排、批量大小上界、批量超时、合规交接。

Enterprise 批量接口面不携带单独的逐功能能力代码；由包边界对其设门。Pro 的单清单能力 pro.output.pipeline 是一个前置条件，而非门槛。仅有一份 Pro 授权只解锁底层的单清单管线，而非这一批量接口面。

composer require nextpdf/enterprise:^3

公共 API 接口面

符号	参数	默认行为	返回	抛出或失败于	备注
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	默认配置；无网关；profile 为 `ComplianceProfile::PdfA4`	—	无	当启用合规检查时注入一个网关；没有网关时，每个受检清单都会被报告为失败。
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	按提交顺序执行清单；变量按清单 ID 解析	`BatchPipelineResult`	当批次超过 10,000 份清单时抛出 `OverflowException`；启用合规检查时抛出网关异常（见边界情形）	解析器的 `Throwable` 绝不逸出；Pro 执行器会将其降级为失败的步骤结果。
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	并发 4；无超时；无合规检查	—	无	只读值对象。`timeoutMs = 0` 禁用批量超时。
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	对逐清单 `PipelineResult` 值的聚合	—	无	只读。除非检查已运行，否则 `complianceReport` 保持为 `null`。
`BatchPipelineResult::allSucceeded()`	—	检测 `failedCount === 0`	`bool`	无	对于一个因超时被截断且零失败的批次会返回 true；见边界情形。
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	无	对空批次返回 `1.0`。
`BatchPipelineResult::hasComplianceReport()`	—	检测 `complianceReport !== null`	`bool`	无	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

行为契约

executeBatch() 首先将批量大小对照 10,000 份清单的上限进行断言。超过上限的批次会在任何清单执行之前抛出 OverflowException；不会有任何静默降级。

随后清单会按提交顺序通过 Pro 的 PipelineExecutor 执行。每份清单接收 $variablesMap 中以其 ID 为键的变量条目；没有对应条目的清单接收一个空的变量映射。当清单的 PipelineResult 状态为 Completed 时计为已完成；任何其他终态计为失败。解析器异常不会逸出：Pro 执行器会把每个解析器 Throwable 转换为一个失败的步骤结果，因此 executeBatch() 始终聚合结果，而不会在某个步骤出错时于批次中途中止。

当 timeoutMs 大于零时，会在每份清单开始之前检查已用时间。一旦预算耗尽，剩余清单会被跳过：它们不产生 PipelineResult，既不计为已完成也不计为失败。totalManifests 始终报告提交的数量。

当启用 complianceCheckOnComplete 时，编排器会通过注入的 ComplianceGateway，将每份已完成清单的最终 PDF 对照所配置的 ComplianceProfile 进行校验。该检查失败即关闭（fail closed）：

未注入网关：每个受检清单都被报告为失败，因为合规从未被校验。
无法从清单的步骤输出中解析出 PDF 输出：失败。
网关未返回结果（可选模式下 sidecar 不可用）：失败。缺少肯定结果不算通过。
网关报告任何不符合项：失败。

最终 PDF 通过扫描一份已完成清单的步骤输出来解析，从最后一个步骤开始，查找以 %PDF 头部起始的直接字符串值。步骤输出绝不会在子数组中嵌套 PDF 字节串；只检查直接的输出值。未完成的清单会被跳过，而不予检查。

合规报告是一个数组，键为 profile、checked、passed、failed 与 failures；每条失败条目携带 manifestId 与 reason。该报告附着于 BatchPipelineResult::$complianceReport，并可通过 hasComplianceReport() 到达。

合规交接是一种重新校验的辅助手段，而非一种授权控制。它仅报告各项发现。

边界情形与失败模式

超过 10,000 份清单：在任何执行开始之前抛出 OverflowException。
timeoutMs = 0 表示无批量超时。在生产中请设置一个有限值。
超时截断：被跳过的清单不出现在任何计数中，因此 completedCount + failedCount 可能小于 totalManifests。allSucceeded() 仅检测 failedCount === 0，对被截断的批次可能返回 true。将 count($result->results) 与 totalManifests 比较以检测截断。
successRate() 对空批次（提交零份清单）返回 1.0。
清单 ID 不会在批次层级去重。两份共享同一 ID 的清单都会执行，并解析同一个变量条目。
结构性清单错误（步骤列表为空、步骤 ID 重复、未知依赖、依赖环、输出类型不匹配、缺失续跑步骤）会在清单构造时抛出 InvalidArgumentException，早于 executeBatch() 被调用之前。
在启用合规检查时，ComplianceGateway::validate() 可能抛出 ComplianceSidecarUnavailableException（必需模式下 sidecar 不可用）或 InvalidArgumentException（未为该 profile 的工具注册校验器）。这两种异常都会在执行之后、结果被构建之前逸出 executeBatch()，因此逐清单结果对调用方丢失。在可选模式下网关改为返回 null，并且该清单被记录为一次合规失败。
当没有任何上游步骤输出包含可识别的 PDF 字节时，管线内的合规交接步骤会失败；它绝不会静默通过。
本模块不执行任何密码学操作；FIPS 模式不适用。

符合性

本模块不作出任何标准符合性主张；它是一个编排层。可选的合规检查会延后到 Enterprise 合规网关及其外部校验器，后者携带其自身的各项参考。默认 profile 为 ComplianceProfile::PdfA4；其他网关 profile 覆盖更多 PDF/A、PDF/UA 与 PAdES 目标。

一份合规报告陈述校验器针对所选 profile 的各项发现。它不认证文档、不保证监管层面充分，也不构成法律建议。判断某个输出是否满足你的义务是你的责任。

开发说明

在生产部署中，并行的工作分派与背压由一个单独的执行 sidecar 处理。PHP 编排器提供批量协调与合规交接逻辑，并由作业工作进程调用，而非由请求处理器直接调用。
PHP 回退路径按顺序执行清单。maxConcurrency 在 sidecar 驱动的部署中限制并发的工作回调；相对于 PHP 工作池对其定规模是运营方的责任。
管线内的合规交接步骤解析器是一个为 inspect 类型步骤注册的内部类型。请通过 BatchPipelineConfig 启用批次末端校验，而非直接为其构造管线步骤。
尽早构造 PipelineManifest 实例。它们的结构性校验在构造函数中运行，因此无效图会快速失败，绝不消耗批量预算。

发布边界

本页仅记录外部可观察的行为与受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀不在范围内。