Enterprise 版本

计费

概览

NextPDF Enterprise 按租户跟踪计算单元（CU）用量，并对照计划配额，应用一项可配置的超额策略：硬停、带重试指引地阻断，或继续并告警。它还会在 80%、100% 与超预算阈值处触发去重后的用量告警。本页描述可观察的计费行为与公开契约。

可用性与授权

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

计费是一项基础 Enterprise 能力，没有单独的按功能标志；计划层级及其所含配额通过计划注册表解析。

概念总览

计费以计算单元来衡量消耗。每个租户在一个计划下运行；每个计划都带有一份所含 CU 配额与一组能力集。系统自带三个默认计划层级——Standard、Advanced 与 High Control——所含配额逐级增大，能力集也逐级更广（更高层级会增加 Intelligence 与 Privacy 附加包）。注册表是权威查找；白标部署可以用自定义定义来构造它。

超额策略决定当某租户超过其所含配额时会发生什么。硬停策略立即阻断处理，并携带 HTTP 402 语义。软停策略带重试指引地阻断，并携带 HTTP 429。预算告警策略从不阻断——处理继续进行，转而触发告警，携带 HTTP 200。只有硬停与软停是阻断性的；只有在策略阻断且所含配额确实被超过时，配额管理器才会抛出超额配额状况。

告警服务按升序对照各阈值评估用量——80% 警告、100% 警告，然后是超预算——并且每种告警类型在每个计费周期、每个租户最多触发一次。超预算需要严格超额，而不仅仅是达到 100%。告警状态通过一个仓库接口跟踪，因此去重能跨请求保持，且该服务暴露了一个清晰的操作，用于在计费周期滚动时重置告警状态。

为何如此设计

计费被构建为一个纯粹的决策层，而非存储系统。配额检查、超额计算与告警评估都在内存中对照一份 PlanDefinition 与一个当前用量数字运行，检查路径上没有 I/O。持久化位于该决策之外：告警去重状态只能通过操作方提供的 AlertStateRepositoryInterface 触达，这使得持久性与计费周期边界都由宿主掌控。超额结果是一个小而显式的枚举，将每种策略映射到一个固定的 HTTP 状态码，因此“阻断或继续”的决策保持确定且可审计。这种分离让同一个计费接口从单实例到计量式多租户集群都能不加改动地运行。设计背景：在生产环境中运营 NextPDF。

公开 API 接口

composer require nextpdf/enterprise:^3

受支持的集成点是计划注册表（get、has、defaultRegistry）、配额管理器（checkQuota、remainingQuota、usagePercentage）、超额计算器（calculate，返回一个不可变的超额结果）、超额策略枚举（httpStatusCode、isBlocking），以及计费告警服务（evaluate、clearAlerts）。告警状态仓库是一个接口——为测试提供一个内存实现，或为生产提供一个持久化实现。

代码示例 — 快速开始

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，否则检查路径上没有 I/O。

安全说明

计费决策派生自调用方提供的、按租户作用域的当前用量数字；租户身份必须来自经过认证的上下文，绝不能来自客户端提供的输入。计费接口强制执行配额并发出告警——它本身并不认证租户。

符合性

超额策略结果携带标准 HTTP 状态语义：硬停为需要付款（402），软停为请求过多（429）并附带重试指引，预算告警为成功（200），遵循 IETF HTTP 语义规范（RFC 9110）中关于 402、429 与 2xx 类别的规定。本页未从 RAG 语料库检索 RFC 9110；此映射由代码声明的状态码与广为人知的 HTTP 语义规范断言而来，此处标记为代码声明，而非经 RAG 验证。

行为契约

消耗以计算单元来衡量；每个租户在一个带所含 CU 配额与能力集的计划下运行。
超额策略是硬停（402，阻断）、软停（429 并附带重试指引，阻断），或预算告警（200，非阻断）三者之一；只有在策略阻断且所含配额确实被超过时，才会抛出超额配额状况。
告警按升序评估（80% 警告、100% 警告、超预算），且每种类型在每个计费周期、每个租户最多触发一次；超预算需要严格超额。
一个非正数的所含配额会报告 0.0 的用量比率，而不是除以零。
配额检查、超额计算与告警评估都是恒定时间的内存运算，检查路径上没有 I/O，除非告警状态仓库执行 I/O。

发布边界

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

Core 回退

NextPDF Core（Apache-2.0）没有任何计费、配额或超额接口——一项都没有；此能力在 Core 层级没有等价物。Core 处理不会被 NextPDF 计量、配额门控或告警。

Pro 回退

NextPDF Pro 没有任何计费、配额或超额接口——一项都没有；此能力在 Pro 层级没有等价物。计划注册表、配额管理器、超额计算器与告警服务仅随 nextpdf/enterprise 包发行。

Enterprise 边界说明

计划注册表、超额策略与告警去重均在行为层面进行描述。告警状态仓库是一个接口；持久化由宿主提供，内部告警状态存储策略不属于公开接口范围。

部署边界

计费决策派生自调用方提供的、按租户作用域的当前用量数字。操作方负责告警状态仓库实现、其持久化，以及计费周期滚动排程。NextPDF Enterprise 强制执行配额并发出告警，但它本身并不认证租户，也不持久化用量。

法务合规边界

计费接口不适用任何出口管制限制。计划包含项、配额与商业条款受你的授权协议约束，而非由运行时强制执行。本文档不是法律或合同意见；计划范围请咨询你自己的顾问并查阅你的协议。