Enterprise 에디션

결제

한눈에 보기

NextPDF Enterprise는 테넌트별 컴퓨트 유닛(CU) 사용량을 플랜 할당량 대비 추적하고, 구성 가능한 초과 사용 정책을 적용합니다. 하드 차단, 재시도 안내와 함께 차단, 또는 계속 진행하며 경고를 발송하는 정책입니다. 또한 80%, 100%, 예산 초과 임계값에서 중복이 제거된 사용량 경고를 발송합니다. 이 페이지는 관찰 가능한 청구 동작과 공개 계약을 설명합니다.

가용성 및 라이선스

이 기능은 NextPDF Enterprise(nextpdf/enterprise)로 제공되며 Enterprise 계층 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스를 받으십시오.

Billing은 별도의 기능별 플래그가 없는 기본 Enterprise 기능입니다. 플랜 계층과 그에 포함된 할당량은 플랜 레지스트리를 통해 확인됩니다.

개념 개요

Billing은 소비를 컴퓨트 유닛 단위로 측정합니다. 각 테넌트는 하나의 플랜으로 실행되며, 각 플랜은 포함된 CU 할당량과 기능 집합을 갖습니다. 세 가지 기본 플랜 계층 — Standard, Advanced, High Control —이 제공되며, 점진적으로 더 큰 포함 할당량과 점진적으로 더 넓은 기능 집합을 갖습니다(상위 계층은 Intelligence 및 Privacy 애드온 팩을 추가합니다). 레지스트리는 정규 조회처입니다. 화이트 라벨 배포는 사용자 정의 정의로 이를 구성할 수 있습니다.

초과 사용 정책은 테넌트가 포함된 할당량을 넘어설 때 무슨 일이 일어나는지 결정합니다. 하드 차단(hard-stop) 정책은 처리를 즉시 차단하고 HTTP 402 시맨틱을 갖습니다. 소프트 차단(soft-stop) 정책은 재시도 안내와 함께 차단하고 HTTP 429를 갖습니다. 예산 경고(budget-alert) 정책은 결코 차단하지 않습니다 — 처리가 계속되고 대신 경고가 발송되며, HTTP 200을 갖습니다. 하드 차단과 소프트 차단만 차단형입니다. 할당량 관리자는 정책이 차단형이고 포함된 할당량이 실제로 초과될 때에만 할당량 초과 조건을 발생시킵니다.

경고 서비스는 사용량을 임계값에 대해 오름차순으로 평가합니다 — 80% 경고, 100% 경고, 그다음 예산 초과 — 그리고 각 경고 유형은 테넌트별 청구 기간당 최대 한 번 발송됩니다. 예산 초과는 단순히 100%에 도달하는 것이 아니라 엄격한 초과 사용을 요구합니다. 경고 상태는 리포지토리 인터페이스를 통해 추적되므로, 중복 제거가 요청 전반에 걸쳐 유지되며, 서비스는 청구 기간 전환 시 경고 상태를 재설정하는 명확한 작업을 노출합니다.

이렇게 작동하는 이유

Billing은 저장 시스템이 아니라 순수한 결정 계층으로 구축되었습니다. 할당량 검사, 초과 사용 계산, 경고 평가는 PlanDefinition과 하나의 현재 사용량 수치에 대해 인메모리로 실행되며, 검사 경로에는 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% 경고가 발송됩니다. 예산 초과는 포함된 할당량을 엄격하게 초과하는 사용량을 요구합니다.
경고는 기간당 중복이 제거됩니다. 각 경고 유형은 테넌트별 청구 기간당 한 번 발송됩니다. 기간 전환 시 경고 상태를 지우십시오. 그렇지 않으면 다음 기간에 경고가 다시 발송되지 않습니다.
포함된 할당량이 0이거나 설정되지 않은 경우. 포함된 할당량이 양수가 아닌 플랜은 0으로 나누는 대신 사용 비율 0.0을 보고합니다.
기간 재설정은 다음 달 경계입니다. 기본 할당량 초과 재설정 시점은 다음 달력 월의 첫째 날 자정입니다.

성능

할당량 검사, 초과 사용 계산, 경고 평가는 플랜 정의와 제공된 현재 사용량 수치에 대한 상수 시간 인메모리 작업입니다. 경고 상태 리포지토리 구현이 I/O를 수행하지 않는 한, 검사 경로에는 I/O가 없습니다.

보안 참고

청구 결정은 호출자가 제공한 테넌트 범위의 현재 사용량 수치에서 파생됩니다. 테넌트 신원은 클라이언트가 제공한 입력이 아니라 반드시 인증된 컨텍스트에서 와야 합니다. 청구 표면은 할당량을 강제하고 경고를 방출합니다 — 그 자체가 테넌트를 인증하지는 않습니다.

적합성

초과 사용 정책 결과는 표준 HTTP 상태 시맨틱을 갖습니다. 하드 차단은 결제 필요(402), 소프트 차단은 재시도 안내가 있는 너무 많은 요청(429), 예산 경고는 성공(200)이며, 402, 429, 2xx 클래스에 대해 IETF HTTP 시맨틱 명세(RFC 9110)를 따릅니다. RFC 9110은 이 페이지를 위해 RAG 코퍼스에서 검색되지 않았습니다. 이 매핑은 코드에 선언된 상태 코드와 잘 알려진 HTTP 시맨틱 명세로부터 단언되며, RAG로 검증된 것이 아니라 코드에 선언된 것으로 여기에 표시됩니다.

동작 계약

소비는 컴퓨트 유닛 단위로 측정됩니다. 각 테넌트는 포함된 CU 할당량과 기능 집합을 갖는 플랜으로 실행됩니다.
초과 사용 정책은 하드 차단(402, 차단형), 소프트 차단(재시도 안내가 있는 429, 차단형), 또는 예산 경고(200, 비차단형) 중 하나입니다. 할당량 초과 조건은 정책이 차단형이고 포함된 할당량이 실제로 초과될 때에만 발생합니다.
경고는 오름차순(80% 경고, 100% 경고, 예산 초과)으로 평가되며, 각 유형은 테넌트별 청구 기간당 최대 한 번 발송됩니다. 예산 초과는 엄격한 초과 사용을 요구합니다.
양수가 아닌 포함 할당량은 0으로 나누는 대신 사용 비율 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는 할당량을 강제하고 경고를 방출하지만, 그 자체가 테넌트를 인증하거나 사용량을 지속하지는 않습니다.

법률 준수 경계

청구 표면에는 수출 통제 제한이 적용되지 않습니다. 플랜 포함 항목, 할당량, 상업적 약관은 런타임 강제가 아니라 귀하의 라이선스 계약에 의해 규율됩니다. 이 문서는 법률 또는 계약 의견이 아닙니다. 플랜 범위에 대해서는 자체 자문 및 귀하의 계약을 참조하십시오.