Enterprise 版本

Common — 深度参考

概览

本页是 NextPDF\Enterprise\Common 命名空间的深度参考。该命名空间仅发布一个公共符号：BoundingBox 值对象。它是一个不可变的归一化矩形，用于在页面上进行与分辨率无关的空间定位。Enterprise Intelligence 与 Privacy 接口面借助它来表示表格单元格几何、实体位置与涂黑区域。本模块不执行任何 I/O、不持有任何文档内容，也不涉及任何密码学。若需工作流指引，请先阅读 Common 能力页。

可用性与授权

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

该基础原语本身不执行任何授权门控；门控发生在使用它的 Enterprise 接口面上。此类没有 Core 层级或 Pro 层级的对等物。它仅随 nextpdf/enterprise 包发行，既不重复也不替代 Core 的几何类型。

公共 API 接口面

符号	参数	默认行为	返回	抛出或失败于	备注
`BoundingBox::__construct`	`float $x`、`float $y`、`float $width`、`float $height`	先对照 `[0.0, 1.0]` 校验每个值，再校验两个边缘之和	`BoundingBox`	当某个值越界或某个边缘之和超过 `1.0 + 1e-9` 时抛出 `InvalidArgumentException`	四个值均成为 `public readonly` 属性
`BoundingBox::area`	无	将 `width` 乘以 `height`	`float`	未声明任何异常	对退化盒子返回 `0.0`
`BoundingBox::contains`	`self $other`	检测 `$other` 是否完全位于此盒子内部	`bool`	未声明任何异常	右边缘与下边缘容许 `+1e-9`；左边缘与上边缘按精确比较
`BoundingBox::overlaps`	`self $other`	检测是否存在严格的矩形相交	`bool`	未声明任何异常	任一侧为零面积操作数时返回 `false`

入口签名

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

行为契约

坐标模型

四个值均为页面尺寸的分数，归一化到 [0.0, 1.0] 区间。
x 定位盒子的左边缘，y 定位上边缘。x + width 与 y + height 界定右边缘与下边缘。
归一化使每个操作都与分辨率无关。同一个盒子在任意渲染尺寸或 DPI 下都指向相同的页面区域。

构造

构造函数是唯一的校验点。落在 [0.0, 1.0] 之外的坐标会抛出 InvalidArgumentException；错误消息会指明出问题的分量及收到的值。
边缘之和超过 1.0 + 1e-9 会抛出 InvalidArgumentException；错误消息会报告两个操作数及其和。1e-9 容差用于吸收上游归一化运算带来的浮点舍入。
已构造的实例是不可变的。此类为 final readonly，因此写入属性会引发 PHP Error，且该类无法被继承。

谓词

area() 返回 width * height。这是一次没有副作用的纯计算。
当另一个盒子完全位于此盒子内部时，contains() 返回 true。右边缘与下边缘的比较带有 +1e-9 容差；左边缘与上边缘的比较为精确比较。每个盒子都包含自身，且零面积盒子可以被包含。
overlaps() 在发生严格矩形相交时返回 true。四个边缘的比较均为严格比较，不带任何容差。若任一操作数面积为零，结果为 false。
因此包含并不意味着重叠：位于另一盒子内部的退化盒子会被包含，但永远不会重叠。
任何方法都不执行 I/O、持久化、网络访问或日志记录，也都不持有文档内容或个人数据。此接口面没有任何运营方拥有的资源。

使用方

各 Enterprise 模块共享此基础原语，而非各自定义模块级的几何。在 Intelligence 中，TableExtractor 的输出在 TableCell 与 KeyValuePair 值上携带它。在 Privacy 中，PiiEntity、RedactionFinding 与 ZoneRedaction 借助它来定位内容，RedactionEngine 则使用这些位置。这些接口面的契约记录在各自的参考页上。

边界情形与失败模式

分量越界。 四个值中任何一个低于 0.0 或高于 1.0，都会在构造时抛出 InvalidArgumentException。INF 与 -INF 会被同一守卫拒绝。
边缘之和溢出。 x + width 或 y + height 超过 1.0 + 1e-9 会抛出 InvalidArgumentException。落在 1e-9 容差之内的和可成功构造。
NAN 输入。 范围守卫使用有序比较，而任何与 NAN 的有序比较都为 false，因此 NAN 分量不会被拒绝。此类实例报告 NAN 面积，并从两个谓词都返回 false。请在构造前清洗上游的浮点数据源。
零面积盒子。 宽度或高度为零的盒子永远不会与任何对象重叠，包括其自身。但它仍可被非退化盒子包含。请在相交逻辑中考虑这种不对称性。
仅边缘相接的盒子。 仅共享一条边或一个角的两个盒子不会重叠；相交检测为严格判定。
包含容差的不对称性。 内盒子的左边缘或上边缘只要越出外盒子任意量，包含判定即失败；只有右边缘与下边缘享有 1e-9 的宽容。
FIPS 模式。 本模块不执行任何密码学操作；FIPS 模式不会改变其行为。

符合性

本模块未实现任何规范性标准，也不作出任何符合性主张。它是一个经过校验的几何基础原语。使用它的各功能所涉及的 PDF 坐标空间语义记录在这些功能各自的页面上。NextPDF 不持有任何认证，也不授予任何认证；支持不等于符合性，符合性不等于认证。此接口面不适用任何出口管制限制，本参考亦不构成法律意见。

开发说明

此类自 nextpdf/enterprise 2.2.0 起可用；其公共接口面在 3.1.0 中保持不变。
请在构造前将页面空间的绝对坐标转换为相对于页面的分数。此类校验的是范围，而非语义；它无法识别一个看似合理但实则错误的区域。
实例是普通值对象，构造成本低廉。请勿对其进行池化或缓存。
两个坐标相同的实例在宽松相等（==）下判定为相等；严格恒等（===）会将它们区分开。在测试中请优先使用坐标比较。
若需布尔谓词之外的几何计算，请从公共属性推导边缘：右边缘 x + width，下边缘 y + height。
在测试容差边界时，请在边缘之和守卫以及包含判定的右/下边缘比较上，分别探测 1e-9 的两侧。

发布边界

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