Enterprise 版本

計費

速覽

NextPDF Enterprise 會依照方案配額，逐租戶追蹤運算單位（CU）用量，並套用一項可設定的超量原則：硬性封鎖、附重試指引地封鎖，或繼續執行並發出警示。它也會在 80%、100% 與超出預算的門檻上，發出去重後的用量警示。本頁描述可觀察的計費行為與公開合約。

供應情況與授權

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

計費是 Enterprise 的一項基礎能力，沒有另外的逐功能旗標；方案層級及其內含配額透過方案登錄解析。

概念總覽

計費以運算單位衡量消耗量。每個租戶在一個方案下執行；每個方案承載一個內含的 CU 配額與一組能力集合。內建三種預設方案層級——Standard、Advanced 與 High Control——具備逐級加大的內含配額，以及逐級擴展的能力集合（較高層級會加入 Intelligence 與 Privacy 附加套件）。登錄是規範的查找來源；白標部署可以用自訂定義來建構它。

超量原則決定當租戶超出其內含配額時會發生什麼。硬性停止（hard-stop）原則會立即封鎖處理，並承載 HTTP 402 語意。軟性停止（soft-stop）原則會附重試指引地封鎖，並承載 HTTP 429。預算警示（budget-alert）原則永不封鎖——處理會繼續，改為發出警示，並承載 HTTP 200。只有硬性停止與軟性停止屬於封鎖性；唯有當原則封鎖且內含配額確實被超出時，配額管理器才會引發超出配額的狀況。

警示服務會依升冪評估用量是否觸及門檻——80% 警告、100% 警告，然後是超出預算——而每一種警示類型在每個計費週期、每個租戶最多只觸發一次。超出預算需要嚴格超量，而不只是觸及 100%。警示狀態透過一個 repository 介面追蹤，因此去重能跨請求保留，而服務也公開一個明確的操作，在計費週期換期時重置警示狀態。

為何如此設計

計費被建構為一個純粹的決策層，而非儲存系統。配額檢查、超量計算與警示評估都在記憶體中，針對一個 PlanDefinition 與一個當前用量數字執行，檢查路徑上沒有任何 I/O。持久化位於該決策之外：警示去重狀態僅能透過操作者提供的 AlertStateRepositoryInterface 觸及，這讓耐久性與計費週期邊界維持在主機掌控之下。超量結果是一個小型且明確的 enum，將每一項原則對應到一個固定的 HTTP 狀態，因此封鎖或繼續的決策維持確定且可稽核。這種分離讓同一個計費介面，能從單一實例到計量式多租戶叢集都原封不動地運行。設計背景：在正式環境中運行 NextPDF。

公開 API 介面

composer require nextpdf/enterprise:^3

受支援的整合點為：方案登錄（get、has、defaultRegistry）、配額管理器（checkQuota、remainingQuota、usagePercentage）、超量計算器（calculate，回傳一個不可變的超量結果）、超量原則 enum（httpStatusCode、isBlocking），以及計費警示服務（evaluate、clearAlerts）。警示狀態 repository 是一個介面——測試時提供記憶體內實作，正式環境則提供持久化實作。

程式碼範例——快速上手

use NextPDF\Enterprise\Billing\OverageCalculator;
use NextPDF\Enterprise\Billing\PlanRegistry;
use NextPDF\Enterprise\Billing\SaaSPlan;

$plan   = PlanRegistry::defaultRegistry()->get(SaaSPlan::Standard);
$result = (new OverageCalculator())->calculate($plan, currentCu: 1_250.0);

$result->isOverage;   // true — 1,250 CU against a 1,000 CU included quota
$result->overageCu;   // 250.0
$result->usageRatio;  // 1.25

程式碼範例——正式環境

use NextPDF\Enterprise\Billing\OveragePolicy;
use NextPDF\Enterprise\Billing\QuotaExceededException;
use NextPDF\Enterprise\Billing\QuotaManager;

$manager = new QuotaManager($registry, OveragePolicy::SoftStop);

try {
    $manager->checkQuota($tenant, SaaSPlan::Advanced, $currentCu);
} catch (QuotaExceededException $e) {
    // SoftStop → answer with 429 + Retry-After up to the reset instant.
    return $this->retryAfter($e->resetsAt);
}

foreach ($alertService->evaluate($tenant, $plan, $planDef, $currentCu) as $alert) {
    $this->notify($tenant, $alert->severity(), $alert);
}

邊界案例與陷阱

預算警示永不封鎖。 在預算警示原則下，即使遠超配額，checkQuota 也不會引發；請依賴已觸發的警示，而非例外。
超出預算需要嚴格超量。 剛好觸及 100% 會觸發 100% 警告，而非超出預算；超出預算需要用量嚴格高於內含配額。
警示以每週期去重。 每一種警示類型在每個租戶、每個計費週期觸發一次。請在週期換期時清除警示狀態，否則警示在下個週期不會重新觸發。
內含配額為零或未設定。 內含配額為非正值的方案，會回報 0.0 的用量比率，而非除以零。
週期重置為下一個月份邊界。 預設的超出配額重置瞬時，為次月第一天的午夜。

效能

配額檢查、超量計算與警示評估，都是針對方案定義與所提供當前用量數字的常數時間、記憶體內運算。檢查路徑上沒有任何 I/O，除非你的警示狀態 repository 實作執行了 I/O。

安全注意事項

計費決策由呼叫端提供、以租戶為範圍的當前用量數字推導而來；租戶身分必須來自已驗證的情境，絕不可來自用戶端提供的輸入。計費介面強制配額並發出警示——它本身不驗證租戶。

一致性

超量原則的結果承載標準 HTTP 狀態語意：硬性停止為 payment-required（402）、軟性停止為附重試指引的 too-many-requests（429），以及預算警示為 success（200），遵循 IETF HTTP 語意規格（RFC 9110）中 402、429 與 2xx 類別。本頁並未從 RAG 語料庫取得 RFC 9110；此對應是依程式碼宣告的狀態碼與眾所周知的 HTTP 語意規格而主張，此處標記為程式碼宣告而非 RAG 驗證。

行為合約

消耗以運算單位衡量；每個租戶在一個帶有內含 CU 配額與能力集合的方案下執行。
超量原則為硬性停止（402，封鎖性）、軟性停止（429 附重試指引，封鎖性），或預算警示（200，非封鎖性）三者之一；唯有當原則封鎖且內含配額確實被超出時，才會引發超出配額的狀況。
警示依升冪評估（80% 警告、100% 警告、超出預算），且每一種在每個租戶、每個計費週期最多觸發一次；超出預算需要嚴格超量。
非正值的內含配額會回報 0.0 的用量比率，而非除以零。
配額檢查、超量計算與警示評估是常數時間的記憶體內運算，檢查路徑上沒有任何 I/O，除非警示狀態 repository 執行了 I/O。

發布邊界

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

Core 回退

NextPDF Core（Apache-2.0）沒有任何計費、配額或超量介面——一個都沒有；此能力沒有 Core 層級的對應。Core 的處理不會被 NextPDF 計量、配額閘控或警示。

Pro 回退

NextPDF Pro 沒有任何計費、配額或超量介面——一個都沒有；此能力沒有 Pro 層級的對應。方案登錄、配額管理器、超量計算器與警示服務僅隨 nextpdf/enterprise 套件提供。

Enterprise 邊界註記

方案登錄、超量原則，以及警示去重以行為層級描述。警示狀態 repository 是一個介面；持久化由主機提供，而內部的警示狀態儲存策略不在公開介面範圍內。

部署邊界

計費決策由呼叫端提供、以租戶為範圍的當前用量數字推導而來。操作者負責警示狀態 repository 的實作、其持久化，以及計費週期換期排程。NextPDF Enterprise 強制配額並發出警示，但它本身不驗證租戶，也不持久化用量。

法律合規邊界

計費介面不適用任何出口管制限制。方案內容、配額與商業條款受你的授權合約規範，而非由執行階段強制。本文件不是法律或合約意見；關於方案範圍，請諮詢你自己的顧問與你的合約。