Enterprise エディション

請求

概要

NextPDF Enterprise は、テナントごとにコンピュートユニット (CU) の使用量をプランクォータに対して追跡し、構成可能な超過ポリシーを適用します。ハードに遮断する、再試行ガイダンスとともに遮断する、または継続してアラートを発する、のいずれかです。さらに、80%、100%、および予算超過のしきい値で、重複排除された使用量アラートを発します。このページでは、観測可能な課金の挙動と公開コントラクトを説明します。

提供状況とライセンス

この機能は NextPDF Enterprise (nextpdf/enterprise) で提供され、Enterprise ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得。

課金は基本的な Enterprise の機能であり、機能ごとの個別フラグはありません。プランティアとそれぞれに含まれるクォータは、プランレジストリを通じて解決されます。

概念の概要

課金は、消費量をコンピュートユニットで測定します。各テナントはプランの下で動作します。各プランは、含まれる CU クォータと機能セットを持ちます。デフォルトで 3 つのプランティア — Standard、Advanced、High Control — が同梱され、含まれるクォータが段階的に大きくなり、機能セットも段階的に広がります (上位ティアは Intelligence と Privacy のアドオンパックを追加します)。レジストリが正規のルックアップです。ホワイトラベルのデプロイメントでは、カスタム定義でこれを構築できます。

超過ポリシーは、テナントが含まれるクォータを超えたときに何が起こるかを決定します。ハードストップポリシーは、処理を即座に遮断し、HTTP 402 のセマンティクスを持ちます。ソフトストップポリシーは、再試行ガイダンスとともに遮断し、HTTP 429 を持ちます。予算アラートポリシーは決して遮断しません — 処理は継続し、代わりにアラートが発せられ、HTTP 200 を持ちます。遮断するのはハードストップとソフトストップのみです。クォータマネージャーは、ポリシーが遮断し、かつ含まれるクォータが実際に超過された場合にのみ、クォータ超過の状態を発生させます。

アラートサービスは、使用量をしきい値に対して昇順で評価します — 80% 警告、100% 警告、次に予算超過 — そして各アラートタイプは、テナントごとに請求期間ごとに最大 1 回発せられます。予算超過には、単に 100% に達するだけでなく、厳密な超過が必要です。アラート状態はリポジトリインターフェースを通じて追跡されるため、重複排除はリクエストをまたいで維持され、サービスは請求期間のロールオーバー時にアラート状態をリセットする明確な操作を公開します。

なぜこの仕組みなのか

課金は、ストレージシステムではなく、純粋な決定レイヤーとして構築されています。クォータチェック、超過計算、およびアラート評価は、PlanDefinition と 1 つの現在使用量の値に対してインメモリで実行され、チェックパス上に I/O はありません。永続化はその決定の外側にあります。アラートの重複排除状態には、オペレーターが提供する AlertStateRepositoryInterface を通じてのみ到達し、これにより耐久性と請求期間の境界がホストの管理下に保たれます。超過の結果は、各ポリシーを固定の HTTP ステータスにマッピングする小さく明示的な enum であるため、遮断するか継続するかの決定は決定論的で監査可能なままです。この分離により、同じ課金サーフェスを単一インスタンスから計測型のマルチテナントフリートまで変更なしで動作させられます。設計の背景: 本番環境での NextPDF の運用。

公開 API サーフェス

composer require nextpdf/enterprise:^3

サポートされる統合ポイントは、プランレジストリ (get、has、defaultRegistry)、クォータマネージャー (checkQuota、remainingQuota、usagePercentage)、超過計算機 (calculate。不変の超過結果を返す)、超過ポリシー enum (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% 警告が発せられます。予算超過には、含まれるクォータを厳密に上回る使用量が必要です。
アラートは期間ごとに重複排除されます。 各アラートタイプは、テナントごとに請求期間ごとに 1 回発せられます。期間のロールオーバー時にアラート状態をクリアしないと、次の期間にアラートが再発しません。
含まれるクォータがゼロまたは未設定の場合。 含まれるクォータが正でないプランは、ゼロ除算ではなく 0.0 の使用率を報告します。
期間リセットは翌月の境界です。 デフォルトのクォータ超過リセット時刻は、翌暦月の初日の午前 0 時です。

パフォーマンス

クォータチェック、超過計算、およびアラート評価は、プラン定義と提供された現在使用量の値に対する、定数時間のインメモリ操作です。アラート状態リポジトリの実装が I/O を実行しない限り、チェックパス上に I/O はありません。

セキュリティに関する注意

課金の判断は、呼び出し元が提供するテナントスコープの現在使用量の値から導出されます。テナント ID は、認証されたコンテキストから取得しなければならず、クライアントが提供する入力から取得してはなりません。課金サーフェスはクォータを強制してアラートを発しますが、テナント自体の認証は行いません。

適合性

超過ポリシーの結果は、標準的な HTTP ステータスのセマンティクスを持ちます。ハードストップには payment-required (402)、ソフトストップには再試行ガイダンスを伴う too-many-requests (429)、予算アラートには success (200) であり、402、429、および 2xx クラスについて IETF HTTP セマンティクス仕様 (RFC 9110) に従います。RFC 9110 はこのページのために RAG コーパスから取得していません。このマッピングは、コードで宣言されたステータスコードと、よく知られた HTTP セマンティクス仕様から主張されたものであり、RAG 検証済みではなくコード宣言済みとしてここに記載します。

挙動コントラクト

消費量はコンピュートユニットで測定されます。各テナントは、含まれる CU クォータと機能セットを持つプランの下で動作します。
超過ポリシーは、ハードストップ (402、遮断)、ソフトストップ (429、再試行ガイダンス付き、遮断)、または予算アラート (200、非遮断) のいずれかです。クォータ超過の状態は、ポリシーが遮断し、かつ含まれるクォータが実際に超過された場合にのみ発生します。
アラートは昇順 (80% 警告、100% 警告、予算超過) で評価され、各タイプはテナントごとに請求期間ごとに最大 1 回発せられます。予算超過には厳密な超過が必要です。
正でない含まれるクォータは、ゼロ除算ではなく 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 はクォータを強制してアラートを発しますが、テナント自体の認証や使用量の永続化は行いません。

法令遵守の境界

課金サーフェスには輸出管理の制限は適用されません。プランに含まれる内容、クォータ、および商業条件は、実行時の強制ではなく、お客様のライセンス契約によって定められます。このドキュメントは法的または契約上の見解ではありません。プランの範囲については、ご自身の助言者およびお客様の契約をご確認ください。