通用

概览

NextPDF Enterprise 提供一小组在各 Enterprise 模块之间复用的共享原语。第一个是用于分辨率无关空间定位的归一化包围盒。它们是值对象，没有任何合规、符合性或密码学行为。

可用性与授权

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

Enterprise 包安装在 Core 包旁边；这些共享原语被其他 Enterprise 模块在内部使用，并随该包一同解析。它们在 Core 层级或 Pro 层级都没有等价物。

安装

composer require nextpdf/enterprise:^3

概念总览

BoundingBox 是一个不可变值对象，其四个坐标——x、y、width、height——相对于页面尺寸被归一化到 [0.0, 1.0] 范围。由于坐标已归一化，该盒是分辨率无关的，可以在那些就页面几何进行推理的 Enterprise 模块之间复用。构造函数会校验每个坐标都在范围之内，且 x + width 与 y + height 不超过 1.0（在一个微小的浮点容差之内），否则抛出一个参数错误。

它暴露 area()、contains(self $other) 与 overlaps(self $other)。零面积盒（退化的点或线）按定义不能重叠。

本模块断言了什么

本模块提供经过校验的几何原语。它不作任何合规或符合性主张，且不执行 I/O。

层级边界

Common 是一个仅限 Enterprise 的支持接口，供其他 Enterprise 模块消费。它既不重复也不替代 Core 几何；它提供那些 Enterprise 模块共享的、经过校验的小型原语。

为何如此设计

承重的决策是把每个坐标归一化到 [0.0, 1.0] 范围，并在构造函数中对其校验。归一化坐标使该盒分辨率无关，因此一个只描述一次的区域在任何页面尺寸或渲染缩放下都保持正确。故障关闭式的构造意味着无效或溢出的盒无法存在：构造函数会拒绝它，而不是钳制或猜测。因此，消费方 Enterprise 模块从不重新检查它们收到的几何，因为一个已构造的盒已知有效。不可变性使得一个共享的盒可以在各模块之间安全传递，无需防御性拷贝。 设计背景：一个拒绝猜测的 API。

API 接口

类	职责
BoundingBox	不可变的归一化盒；area()、contains()、overlaps()。

代码示例 — 快速开始

use NextPDF\Enterprise\Common\BoundingBox;

$box = new BoundingBox(0.1, 0.1, 0.5, 0.2);
$inside = $box->contains(new BoundingBox(0.2, 0.15, 0.1, 0.02));

代码示例 — 生产

$region = new BoundingBox($x, $y, $w, $h); // throws on out-of-range input

if ($region->overlaps($redactionZone)) {
    $logger->info('common.overlap', ['area' => $region->area()]);
}

边界情况与注意事项

• 用任何处于 [0.0, 1.0] 之外的坐标，或用 x + width / y + height 超过 1.0 的值进行构造，会抛出一个参数错误——请在上游校验输入。
• 零面积盒从不重叠；在计算交集时请把这一点考虑进去。
• 坐标是归一化的，而非像素；请在渲染边界处转换。

性能

所有操作都是对四个浮点数的恒定时间算术运算。

安全说明

BoundingBox 不执行 I/O，也不持有任何文档内容。构造函数会拒绝超范围的几何，防止退化的值传播进消费它的模块。

数据驻留与 PII 缓解

本模块不持有任何个人数据，也不执行任何持久化或网络 I/O。驻留方面的考量不适用。

安全遥测与日志清洗

盒坐标与面积是非敏感的几何，可以安全地记录。

符合性

本模块不实现任何规范性标准，也不作任何符合性主张。它是一个几何原语。

FIPS 模式行为

本模块不执行任何密码学运算；FIPS 模式不适用。

威胁模型

唯一的输入是四个浮点数。构造函数的范围与边界校验就是缓解措施：无效的几何无法被构造出来。

行为契约

• BoundingBox 是一个不可变值对象，其四个坐标相对于页面尺寸被归一化到 [0.0, 1.0] 范围，使其分辨率无关。
• 构造函数会校验每个坐标都在范围之内，且 x + width 与 y + height 不超过 1.0（在一个微小的浮点容差之内），否则抛出一个参数错误。
• 它暴露 area()、contains() 与 overlaps()；零面积盒按定义从不重叠。
• 本模块不执行 I/O、不持有任何文档内容，也不作任何合规或符合性主张。

发布边界

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

Core 回退

Core 回退——无；这是一个仅限 Enterprise 的共享支持原语。它既不重复也不替代 Core 几何，且在 Core 层级没有等价物。

Pro 回退

Pro 回退——无；此能力在 Pro 层级没有等价物。共享的 BoundingBox 原语仅随 nextpdf/enterprise 包发行。

Enterprise 边界说明

经过校验的几何原语在行为层面进行描述。它是一个仅限 Enterprise 的支持接口，供其他 Enterprise 模块消费；除已记录的契约之外，没有任何内部子机制。

部署边界

部署边界——无适用项；本模块不执行持久化、不执行网络 I/O，也不持有任何文档内容或个人数据。此接口没有任何由操作方负责的资源。

法务合规边界

没有任何出口管制限制适用于此接口。本模块不实现任何规范性标准，也不作任何符合性、认证或监管主张。本文档不是法律意见。

另请参阅

• Validation —— 消费共享原语。
• Evidence —— 消费共享原语。
• Common — 深度参考 —— 共享原语的深度参考。