Enterprise edizione

Fatturazione

In sintesi

NextPDF Enterprise tiene traccia dell’utilizzo di compute unit (CU) per ciascun tenant rispetto a una quota di piano e applica una politica di superamento configurabile: blocco rigido, blocco con indicazioni di ripetizione oppure continuazione con avviso. Genera inoltre avvisi di utilizzo deduplicati alle soglie dell’80%, del 100% e di superamento del budget. Questa pagina descrive il comportamento di fatturazione osservabile e il contratto pubblico.

Disponibilità e licenze

Questa capacità è distribuita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Una distribuzione priva di tale titolarità non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

La fatturazione è una capacità di base di Enterprise senza alcun flag separato per funzionalità; i tier dei piani e le rispettive quote incluse si risolvono tramite il registro dei piani.

Panoramica concettuale

La fatturazione misura il consumo in compute unit. Ogni tenant opera sotto un piano; ogni piano comprende una quota di CU inclusa e un insieme di capacità. Sono distribuiti tre tier di piano predefiniti — Standard, Advanced e High Control — con quote incluse progressivamente più ampie e insiemi di capacità progressivamente più estesi (i tier superiori aggiungono i pacchetti aggiuntivi Intelligence e Privacy). Il registro è il riferimento canonico; una distribuzione white-label può costruirlo con definizioni personalizzate.

La politica di superamento decide cosa accade quando un tenant supera la propria quota inclusa. Una politica di blocco rigido blocca immediatamente l’elaborazione e ha semantica HTTP 402. Una politica di blocco morbido blocca con indicazioni di ripetizione e ha semantica HTTP 429. Una politica di avviso di budget non blocca mai — l’elaborazione prosegue e vengono invece generati avvisi, con semantica HTTP 200. Solo il blocco rigido e il blocco morbido sono bloccanti; il gestore delle quote solleva una condizione di quota superata solo quando la politica blocca e la quota inclusa è effettivamente superata.

Il servizio di avvisi valuta l’utilizzo rispetto alle soglie in ordine crescente — avviso all’80%, avviso al 100%, quindi superamento del budget — e ciascun tipo di avviso viene generato al più una volta per periodo di fatturazione per ciascun tenant. Il superamento del budget richiede un superamento stretto, non il semplice raggiungimento del 100%. Lo stato degli avvisi è tracciato tramite un’interfaccia di repository, così la deduplicazione persiste tra le richieste, e il servizio espone un’operazione chiara per ripristinare lo stato degli avvisi al cambio del periodo di fatturazione.

Perché funziona così

La fatturazione è costruita come un puro livello decisionale, non come un sistema di archiviazione. I controlli delle quote, il calcolo del superamento e la valutazione degli avvisi vengono eseguiti in memoria rispetto a una PlanDefinition e a un singolo dato di utilizzo corrente, senza alcun I/O sul percorso di controllo. La persistenza si colloca al di fuori di tale decisione: lo stato di deduplicazione degli avvisi è raggiunto solo tramite l’AlertStateRepositoryInterface fornita dall’operatore, il che mantiene la durabilità e il confine del periodo di fatturazione sotto il controllo dell’host. L’esito del superamento è un piccolo enum esplicito che mappa ciascuna politica a uno stato HTTP fisso, così la decisione di bloccare o proseguire rimane deterministica e verificabile. Questa separazione consente alla stessa superficie di fatturazione di funzionare invariata da una singola istanza a una flotta multi-tenant misurata. Contesto progettuale: Utilizzare NextPDF in produzione.

Superficie API pubblica

composer require nextpdf/enterprise:^3

I punti di integrazione supportati sono il registro dei piani (get, has, defaultRegistry), il gestore delle quote (checkQuota, remainingQuota, usagePercentage), il calcolatore del superamento (calculate, che restituisce un risultato di superamento immutabile), l’enum della politica di superamento (httpStatusCode, isBlocking) e il servizio di avvisi di fatturazione (evaluate, clearAlerts). Il repository dello stato degli avvisi è un’interfaccia — fornire un’implementazione in memoria per i test o una durevole per la produzione.

Esempio di codice — avvio rapido

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

Esempio di codice — produzione

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);
}

Casi limite e insidie

L’avviso di budget non blocca mai. Con una politica di avviso di budget checkQuota non solleva eccezioni nemmeno ben oltre la quota; affidarsi agli avvisi generati, non a un’eccezione.
Il superamento del budget richiede un superamento stretto. Raggiungere esattamente il 100% genera l’avviso al 100%, non il superamento del budget; il superamento del budget richiede un utilizzo strettamente superiore alla quota inclusa.
Gli avvisi si deduplicano per periodo. Ciascun tipo di avviso viene generato una volta per tenant per periodo di fatturazione. Ripristinare lo stato degli avvisi al cambio del periodo, altrimenti gli avvisi non si rigenerano nel periodo successivo.
Quota inclusa pari a zero o non impostata. Un piano con una quota inclusa non positiva riporta un rapporto di utilizzo pari a 0.0 anziché dividere per zero.
Il ripristino del periodo coincide con il confine del mese successivo. L’istante di ripristino predefinito della condizione di quota superata è il primo giorno del mese di calendario successivo a mezzanotte.

Prestazioni

I controlli delle quote, il calcolo del superamento e la valutazione degli avvisi sono operazioni in memoria a tempo costante, eseguite rispetto a una definizione di piano e al dato di utilizzo corrente fornito. Non vi è alcun I/O sul percorso di controllo a meno che l’implementazione del proprio repository dello stato degli avvisi non ne esegua.

Note di sicurezza

Le decisioni di fatturazione sono derivate da un dato di utilizzo corrente con ambito di tenant fornito dal chiamante; l’identità del tenant deve provenire dal contesto autenticato, mai da input fornito dal client. La superficie di fatturazione applica le quote ed emette avvisi — non autentica essa stessa il tenant.

Conformità

Gli esiti della politica di superamento trasportano una semantica di stato HTTP standard: pagamento richiesto (402) per il blocco rigido, troppe richieste (429) con indicazioni di ripetizione per il blocco morbido e successo (200) per l’avviso di budget, in conformità alla specifica della semantica HTTP IETF (RFC 9110) per le classi 402, 429 e 2xx. RFC 9110 non è stato recuperato dal corpus RAG per questa pagina; questa mappatura è asserita a partire dai codici di stato dichiarati nel codice e dalla nota specifica della semantica HTTP, indicata qui come dichiarata nel codice anziché verificata da RAG.

Contratto di comportamento

Il consumo è misurato in compute unit; ogni tenant opera sotto un piano con una quota di CU inclusa e un insieme di capacità.
La politica di superamento è una tra blocco rigido (402, bloccante), blocco morbido (429 con indicazioni di ripetizione, bloccante) o avviso di budget (200, non bloccante); una condizione di quota superata viene sollevata solo quando la politica blocca e la quota inclusa è effettivamente superata.
Gli avvisi vengono valutati in ordine crescente (avviso all’80%, avviso al 100%, superamento del budget) e ciascun tipo viene generato al più una volta per periodo di fatturazione per ciascun tenant; il superamento del budget richiede un superamento stretto.
Una quota inclusa non positiva riporta un rapporto di utilizzo pari a 0.0 anziché dividere per zero.
I controlli delle quote, il calcolo del superamento e la valutazione degli avvisi sono operazioni in memoria a tempo costante senza alcun I/O sul percorso di controllo a meno che il repository dello stato degli avvisi non ne esegua.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi di file di runbook e i prefissi di ticket sono fuori ambito.

Fallback di Core

NextPDF Core (Apache-2.0) non dispone di alcuna superficie di fatturazione, quota o superamento — nessuna; questa capacità non ha un equivalente a livello Core. L’elaborazione di Core non è misurata, soggetta a gate di quota o oggetto di avvisi da parte di NextPDF.

Fallback di Pro

NextPDF Pro non dispone di alcuna superficie di fatturazione, quota o superamento — nessuna; questa capacità non ha un equivalente a livello Pro. Il registro dei piani, il gestore delle quote, il calcolatore del superamento e il servizio di avvisi sono inclusi esclusivamente nel pacchetto nextpdf/enterprise.

Nota sul confine Enterprise

Il registro dei piani, la politica di superamento e la deduplicazione degli avvisi sono descritti a livello di comportamento. Il repository dello stato degli avvisi è un’interfaccia; la persistenza durevole è fornita dall’host, e la strategia interna di archiviazione dello stato degli avvisi è fuori ambito per la superficie pubblica.

Confine di distribuzione

Le decisioni di fatturazione sono derivate da un dato di utilizzo corrente con ambito di tenant fornito dal chiamante. L’operatore è responsabile dell’implementazione del repository dello stato degli avvisi, della sua persistenza e della pianificazione del cambio del periodo di fatturazione. NextPDF Enterprise applica le quote ed emette avvisi ma non autentica essa stessa il tenant né persiste l’utilizzo.

Confine di conformità legale

Nessuna restrizione di controllo delle esportazioni si applica alla superficie di fatturazione. Le inclusioni dei piani, le quote e i termini commerciali sono disciplinati dal proprio contratto di licenza, non da un’applicazione in fase di esecuzione. Questa documentazione non è un parere legale o contrattuale; consultare i propri consulenti e il proprio contratto per l’ambito dei piani.