Enterprise 版本

Document E-Filing — 深度参考

概览

EFilingOptimizer 在一次固定顺序的处理中为电子法院申报准备 PDF：清理、线性化、按尺寸拆分。
EFilingProfile 编码辖区约束。内置工厂涵盖 US PACER、EU e-Justice 和 Taiwan Judicial Yuan。
SizeAwareSplitter 通过“先验证后纠正”的再拆分强制执行每个分段的字节上限。
输出是一种交付产物。它不得再次进入签名或归档管线。
本模块不执行任何密码学操作，也不发起任何对外网络调用。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）一同交付，并通过 Enterprise 级授权信封激活。没有该授权的部署不会加载此能力的类。比较版本并获取授权。

nextpdf/enterprise 包的边界对这一接口面进行门控；不存在单独的逐功能能力代码。没有任何 Core 或 Pro 版本提供电子申报优化器。

公共 API 接口面

composer require nextpdf/enterprise:^3

符号	参数	默认行为	返回	抛出或失败于	说明
`EFilingOptimizer::optimize()`	`string $pdfData`, `?EFilingProfile $profile = null`	配置文件默认为 `EFilingProfile::pacer()`；按固定顺序运行清理、线性化、按尺寸拆分	`EFilingResult`	当超限输入不是有效的 PDF 时，拆分步骤抛出 `InvalidArgumentException`；清理与线性化失败降级为警告	输出是一种交付产物
`EFilingProfile::__construct()`	`$name`, `$maxFileSizeBytes = 26_214_400`, `$flattenForms = true`, `$removeJavaScript = true`, `$imageQuality = 75`, `$linearize = true`, `$compressObjectStreams = true`	不可变的辖区配置文件	`EFilingProfile`	不抛出	为没有内置工厂的门户提供自定义上限
`EFilingProfile::pacer()`	无	25 MiB 上限，图像质量 75	`EFilingProfile`	不抛出	US PACER
`EFilingProfile::euJustice()`	无	10 MiB 上限，图像质量 70	`EFilingProfile`	不抛出	EU e-Justice Portal
`EFilingProfile::taiwan()`	无	10 MiB 上限，图像质量 70	`EFilingProfile`	不抛出	Taiwan Judicial Yuan
`SizeAwareSplitter::splitByMaxSize()`	`string $pdfData`, `int $maxBytes`	输入合适时为单一分段；否则估算、验证、再拆分	`list<EFilingSegment>`	当超限输入缺少 `%PDF` 头时抛出 `InvalidArgumentException`	低于上限的输入不经验证即作为一个分段返回
`EFilingResult::isSplit()`	无	存在多个分段时为 `true`	`bool`	不抛出	—
`EFilingResult::segmentCount()`	无	分段总数	`int`	不抛出	—
`EFilingResult::compressionRatio()`	无	`optimizedTotalSize / originalSize`	`float`	不抛出；原始输入为空时为 `0.0`	越低越好
`EFilingSegment`	`$pdfData`, `$pageRange`, `$sizeBytes`, `$segmentIndex`	不可变的输出分段	值对象	不抛出	页面范围字符串，例如 `1-25` 或 `all`

public function optimize(string $pdfData, ?EFilingProfile $profile = null): EFilingResult

public function __construct(
    public string $name,
    public int $maxFileSizeBytes = 26_214_400,
    public bool $flattenForms = true,
    public bool $removeJavaScript = true,
    public int $imageQuality = 75,
    public bool $linearize = true,
    public bool $compressObjectStreams = true,
) {}

public static function pacer(): self
public static function euJustice(): self
public static function taiwan(): self

public function splitByMaxSize(string $pdfData, int $maxBytes): array

public function __construct(
    public array $segments,
    public int $originalSize,
    public int $optimizedTotalSize,
    public array $optimizations = [],
    public array $warnings = [],
) {}

public function isSplit(): bool
public function segmentCount(): int
public function compressionRatio(): float

行为契约

EFilingOptimizer::optimize() 针对输入字节运行一条固定顺序的管线。第一步在设置了 removeJavaScript 时移除活动内容。它委托给“内容解除与重构”引擎，采用面向申报的策略：移除 JavaScript、命名 JavaScript、启动动作、表单提交以及数据导入动作；保留 URI 动作（allowUriActions），因为申报文件可能携带合法链接；将增量更新扁平化为单个修订版本（flattenIncrementalUpdates）。第二步在设置了 linearize 时，通过 Core 的 NextPDF\Writer\Linearizer 对已清理的字节进行线性化。第三步通过 SizeAwareSplitter 强制执行配置文件的 maxFileSizeBytes。

拆分器根据平均页面尺寸估算每个分段的页数，进行拆分，然后对照上限验证每个产出的分段。任何仍跨越多页的超限分段都会被递归再拆分，每一轮将其自身的页面跨度减半，直到每个子分段都合适或仅剩单页。有界的再拆分深度可防止病态的不收敛。输出索引会被重新规范化，以保持连续且从零开始。

optimize() 消费三个配置文件字段：maxFileSizeBytes、removeJavaScript 和 linearize。flattenForms、imageQuality 和 compressObjectStreams 字段是已声明的配置文件约束，optimize() 在 3.1.0 中并不据其执行。

电子申报输出是一种交付产物，而非一种文档生命周期状态。一份经过优化或拆分的 PDF 对于传输而言是终态，且不得再次进入签名或归档管线；重新处理会破坏哈希链与证据完整性。

本模块按所配置的方式为电子法院/政府申报准备格式。它不保证任何法院、登记机构、审裁机构或申报门户会予以受理。内置配置文件的上限将常见的公开约束作为一种便利进行编码，而非来自各门户的实时数据源；门户规则因辖区而异且会变更。对照目标登记机构的现行规则进行核验是申报方的责任。

处理在进程内本地完成。向法院、登记机构或申报门户的传输位于本模块之外。

边界情形与失败模式

输入等于或低于上限：单个分段，页面范围为 all；拆分步骤不改动字节。
清理被拒绝（例如无法解析的输入）：记录警告 CDR sanitization rejected: <reason>，管线继续使用原始字节。
清理通过但未发现威胁：字节仍会被重建后的 PDF 替换，并记录一条优化条目以标记该次干净的处理。
线性化失败：记录警告 Linearization skipped: <message>，管线继续使用未线性化的字节。
单页超过上限：确实无法再分，作为一个超限分段原样返回。此情形不记录警告；在申报前请对照配置文件上限比较每个分段的 sizeBytes。
达到再拆分深度上限：超限分段原样通过，而不进入循环。
compressionRatio() 在原始输入为空时返回 0.0。
本模块不执行任何密码学操作；FIPS 模式不适用。

符合性

行为	参考	状态
线性化输出组织（首页数据位于文件起始处）	ISO 32000-2:2020 Annex F / Annex G	依其构建
关联文件关系语义	ISO 19005-3:2012 §6.7.8	在适用载体处予以遵循
内嵌文件载体要求	ISO 19005-4:2020 Annex A	在适用载体处予以遵循

线性化以线性化 PDF 组织为目标，将显示首页所需的全部数据置于文件起始处，以实现高效的增量访问。

这些行描述的是依所引用条款构建的能力。支持不等于符合性，符合性也不等于认证；NextPDF 不持有任何认证。本页的任何陈述都不保证任何申报门户会予以受理。

本页标记为 export_control_class: legal-review-required。NextPDF 不提供法律建议。申报规则因辖区而异且会变更；满足这些规则是申报方的责任。请咨询法律顾问以及目标登记机构的现行指引。

开发说明

use NextPDF\Enterprise\Document\EFiling\EFilingOptimizer;
use NextPDF\Enterprise\Document\EFiling\EFilingProfile;

$optimizer = new EFilingOptimizer();
$result = $optimizer->optimize($pdfBytes, EFilingProfile::euJustice());

foreach ($result->segments as $segment) {
    // Persist $segment->pdfData; confirm $segment->sizeBytes fits the cap.
}

在申报前检查 $result->warnings。被拒绝的清理或被跳过的线性化会在此处显现，而不是作为异常抛出。
先对源文档进行签名和归档；然后再优化一份副本用于交付。切勿对已优化的分段重新签名、重新盖章或归档。
对照配置文件上限验证每个分段的 sizeBytes。一个无法再分的超限页面会悄无声息地进入输出。
对于没有内置工厂的门户，请使用该门户公布的上限构造一个自定义 EFilingProfile。

发布边界

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