通用

速覽

NextPDF Enterprise 隨附一小組跨 Enterprise 模組重複使用的共用原語。第一個是用於與解析度無關之空間定位的正規化定界框。這些是 value object，不具任何合規、一致性或密碼學行為。

供應與授權

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

Enterprise 套件安裝在 Core 套件旁；這些共用原語由其他 Enterprise 模組於內部消費，並隨套件解析。它們沒有 Core 層級或 Pro 層級的對應。

安裝

composer require nextpdf/enterprise:^3

概念總覽

BoundingBox 是一個不可變的 value object，其四個座標——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 進行建構，會引發一個引數錯誤——請在上游驗證輸入。
• 零面積的框永不重疊；計算交集時請將此納入考量。
• 座標是正規化的，而非像素；請在渲染邊界處轉換。

效能

所有操作都是對四個 float 的常數時間算術。

安全注意事項

BoundingBox 不執行任何 I/O，也不保有任何文件內容。建構子會拒絕超出範圍的幾何，防止退化值傳播到消費端模組。

資料落地與 PII 緩解措施

此模組不保有任何個人資料，也不執行任何持久化或網路 I/O。落地考量不適用。

安全遙測與日誌清洗

框座標與面積是非敏感的幾何，可以安全記錄。

一致性

此模組不實作任何規範性標準，也不做任何一致性聲明。它是一個幾何原語。

FIPS 模式行為

此模組不執行任何密碼學運算；FIPS 模式不適用。

威脅模型

唯一的輸入是四個 float。建構子的範圍與界限驗證即為緩解措施：無效的幾何無法被建構。

行為合約

• BoundingBox 是一個不可變的 value object，其四個座標相對於頁面尺寸正規化到 [0.0, 1.0] 範圍，使其與解析度無關。
• 建構子會驗證每一個座標都在範圍內，且 x + width 與 y + height 不超過 1.0（在一個小的浮點容差內），否則引發一個引數錯誤。
• 它公開 area()、contains() 與 overlaps()；零面積的框依定義永不重疊。
• 此模組不執行任何 I/O、不保有任何文件內容，也不做任何合規或一致性聲明。

發佈邊界

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

Core 回退

Core 回退——無；這是一個僅限 Enterprise 的共用支援原語。它不重複或取代 Core 幾何，也沒有 Core 層級的對應。

Pro 回退

Pro 回退——無；此能力沒有 Pro 層級的對應。共用的 BoundingBox 原語僅隨 nextpdf/enterprise 套件提供。

Enterprise 邊界註記

經驗證的幾何原語以行為層級描述。它是一個僅限 Enterprise、供其他 Enterprise 模組消費的支援介面；除了已記載的合約之外，沒有任何內部子機制。

部署邊界

部署邊界——無適用項；此模組不執行任何持久化、任何網路 I/O，也不保有任何文件內容或個人資料。此介面沒有任何由操作者擁有的資源。

法律合規邊界

此介面不適用任何出口管制限制。此模組不實作任何規範性標準，也不做任何一致性、認證或法規聲明。本文件不是法律意見。

另請參閱

• Validation — 消費共用原語。
• Evidence — 消費共用原語。
• Common — 深入參考 — 共用原語的深入參考。