Enterprise edycja

Rozliczenia

W skrócie

NextPDF Enterprise śledzi zużycie jednostek obliczeniowych (compute unit, CU) na każdego najemcę względem limitu planu i stosuje konfigurowalną politykę przekroczenia: twarda blokada, blokada z wytyczną dotyczącą ponowienia lub kontynuacja z alertem. Wyzwala także zdeduplikowane alerty zużycia przy progach 80%, 100% oraz przekroczenia budżetu. Ta strona opisuje obserwowalne zachowanie rozliczeń oraz publiczny kontrakt.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Rozliczenia są podstawową możliwością edycji Enterprise, bez osobnej flagi dla poszczególnych funkcji; poziomy planów oraz wliczone w nie limity są rozwiązywane przez rejestr planów.

Przegląd koncepcyjny

Rozliczenia mierzą zużycie w jednostkach obliczeniowych. Każdy najemca działa w ramach planu; każdy plan niesie wliczony limit CU oraz zestaw możliwości. Dostarczane są trzy domyślne poziomy planów — Standard, Advanced oraz High Control — z progresywnie większymi wliczonymi limitami i progresywnie szerszymi zestawami możliwości (wyższe poziomy dodają pakiety rozszerzeń Intelligence i Privacy). Rejestr jest kanonicznym źródłem wyszukiwania; wdrożenie typu white-label może skonstruować go z własnymi definicjami.

Polityka przekroczenia decyduje o tym, co dzieje się, gdy najemca przekroczy swój wliczony limit. Polityka twardej blokady (hard-stop) blokuje przetwarzanie natychmiast i niesie semantykę HTTP 402. Polityka miękkiej blokady (soft-stop) blokuje z wytyczną dotyczącą ponowienia i niesie HTTP 429. Polityka alertu budżetowego (budget-alert) nigdy nie blokuje — przetwarzanie jest kontynuowane, a zamiast tego wyzwalane są alerty, niosąc HTTP 200. Tylko hard-stop i soft-stop blokują; menedżer limitów zgłasza warunek przekroczenia limitu wyłącznie wtedy, gdy polityka blokuje, a wliczony limit jest faktycznie przekroczony.

Usługa alertów ocenia zużycie względem progów w kolejności rosnącej — ostrzeżenie 80%, ostrzeżenie 100%, następnie przekroczenie budżetu — a każdy typ alertu wyzwala się co najwyżej raz na okres rozliczeniowy na najemcę. Przekroczenie budżetu wymaga ścisłego przekroczenia, a nie jedynie osiągnięcia 100%. Stan alertów jest śledzony przez interfejs repozytorium, więc deduplikacja przetrwa między żądaniami, a usługa udostępnia czytelną operację resetowania stanu alertów przy przejściu na nowy okres rozliczeniowy.

Dlaczego to działa w ten sposób

Rozliczenia są zbudowane jako czysta warstwa decyzyjna, a nie system przechowywania. Sprawdzanie limitów, obliczenia przekroczenia oraz ocena alertów działają w pamięci względem PlanDefinition oraz jednej wartości bieżącego zużycia, bez operacji wejścia/wyjścia na ścieżce sprawdzania. Trwałość znajduje się poza tą decyzją: stan deduplikacji alertów jest osiągany wyłącznie przez AlertStateRepositoryInterface dostarczony przez operatora, co utrzymuje trwałość oraz granicę okresu rozliczeniowego pod kontrolą hosta. Wynik przekroczenia to małe, jawne wyliczenie mapujące każdą politykę na stały status HTTP, dzięki czemu decyzja o blokowaniu lub kontynuacji pozostaje deterministyczna i audytowalna. To rozdzielenie pozwala tej samej powierzchni rozliczeń działać bez zmian od pojedynczej instancji po mierzoną flotę wielonajemcową. Tło projektowe: Eksploatacja NextPDF w produkcji.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Wspierane punkty integracji to rejestr planów (get, has, defaultRegistry), menedżer limitów (checkQuota, remainingQuota, usagePercentage), kalkulator przekroczenia (calculate, zwracający niemutowalny wynik przekroczenia), wyliczenie polityki przekroczenia (httpStatusCode, isBlocking) oraz usługa alertów rozliczeniowych (evaluate, clearAlerts). Repozytorium stanu alertów jest interfejsem — dostarcz implementację w pamięci na potrzeby testów lub trwałą na potrzeby produkcji.

Przykład kodu — szybki start

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

Przykład kodu — produkcja

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

Przypadki brzegowe i pułapki

Alert budżetowy nigdy nie blokuje. Przy polityce alertu budżetowego checkQuota nie zgłasza wyjątku nawet daleko poza limitem; polegaj na wyzwolonych alertach, a nie na wyjątku.
Przekroczenie budżetu wymaga ścisłego przekroczenia. Osiągnięcie dokładnie 100% wyzwala ostrzeżenie 100%, a nie przekroczenie budżetu; przekroczenie budżetu wymaga zużycia ściśle powyżej wliczonego limitu.
Alerty deduplikują się w obrębie okresu. Każdy typ alertu wyzwala się raz na najemcę na okres rozliczeniowy. Wyczyść stan alertów przy przejściu na nowy okres, w przeciwnym razie alerty nie wyzwolą się ponownie w następnym okresie.
Zerowy lub nieustawiony wliczony limit. Plan z niedodatnim wliczonym limitem raportuje współczynnik zużycia 0,0 zamiast dzielenia przez zero.
Reset okresu przypada na granicę następnego miesiąca. Domyślny moment resetu przekroczenia limitu to pierwszy dzień następnego miesiąca kalendarzowego o północy.

Wydajność

Sprawdzanie limitów, obliczanie przekroczenia oraz ocena alertów to operacje o stałym czasie, wykonywane w pamięci względem definicji planu oraz dostarczonej wartości bieżącego zużycia. Na ścieżce sprawdzania nie ma żadnych operacji wejścia/wyjścia, o ile nie wykonuje ich Twoja implementacja repozytorium stanu alertów.

Uwagi dotyczące bezpieczeństwa

Decyzje rozliczeniowe są wyprowadzane z wartości bieżącego zużycia w zakresie danego najemcy, dostarczonej przez wywołującego; tożsamość najemcy musi pochodzić z uwierzytelnionego kontekstu, nigdy z danych dostarczonych przez klienta. Powierzchnia rozliczeń egzekwuje limity i emituje alerty — sama nie uwierzytelnia najemcy.

Zgodność ze standardami

Wyniki polityki przekroczenia niosą standardową semantykę statusu HTTP: wymagana płatność (402) dla twardej blokady, zbyt wiele żądań (429) z wytyczną dotyczącą ponowienia dla miękkiej blokady oraz sukces (200) dla alertu budżetowego, zgodnie ze specyfikacją semantyki HTTP organizacji IETF (RFC 9110) dla klas 402, 429 oraz 2xx. RFC 9110 nie zostało pobrane z korpusu RAG dla tej strony; to przyporządkowanie jest twierdzone na podstawie kodów statusu zadeklarowanych w kodzie oraz powszechnie znanej specyfikacji semantyki HTTP i oznaczone tutaj jako zadeklarowane w kodzie, a nie zweryfikowane przez RAG.

Kontrakt zachowania

Zużycie jest mierzone w jednostkach obliczeniowych; każdy najemca działa w ramach planu z wliczonym limitem CU oraz zestawem możliwości.
Polityka przekroczenia to jedna z: twarda blokada (402, blokująca), miękka blokada (429 z wytyczną dotyczącą ponowienia, blokująca) lub alert budżetowy (200, nieblokujący); warunek przekroczenia limitu jest zgłaszany wyłącznie wtedy, gdy polityka blokuje, a wliczony limit jest faktycznie przekroczony.
Alerty są oceniane w kolejności rosnącej (ostrzeżenie 80%, ostrzeżenie 100%, przekroczenie budżetu), a każdy typ wyzwala się co najwyżej raz na okres rozliczeniowy na najemcę; przekroczenie budżetu wymaga ścisłego przekroczenia.
Niedodatni wliczony limit raportuje współczynnik zużycia 0,0 zamiast dzielenia przez zero.
Sprawdzanie limitów, obliczanie przekroczenia oraz ocena alertów to operacje o stałym czasie wykonywane w pamięci, bez operacji wejścia/wyjścia na ścieżce sprawdzania, o ile nie wykonuje ich repozytorium stanu alertów.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie awaryjne w Core

NextPDF Core (Apache-2.0) nie ma żadnej powierzchni rozliczeń, limitów ani przekroczeń — żadnej; ta możliwość nie ma odpowiednika na poziomie Core. Przetwarzanie w Core nie jest mierzone, objęte limitem ani alertowane przez NextPDF.

Rozwiązanie awaryjne w Pro

NextPDF Pro nie ma żadnej powierzchni rozliczeń, limitów ani przekroczeń — żadnej; ta możliwość nie ma odpowiednika na poziomie Pro. Rejestr planów, menedżer limitów, kalkulator przekroczenia oraz usługa alertów są dostarczane wyłącznie w pakiecie nextpdf/enterprise.

Uwaga o granicy Enterprise

Rejestr planów, polityka przekroczenia oraz deduplikacja alertów są opisane na poziomie zachowania. Repozytorium stanu alertów jest interfejsem; trwałe przechowywanie jest dostarczane przez hosta, a wewnętrzna strategia przechowywania stanu alertów jest poza zakresem powierzchni publicznej.

Granica wdrożenia

Decyzje rozliczeniowe są wyprowadzane z wartości bieżącego zużycia w zakresie danego najemcy, dostarczonej przez wywołującego. Operator jest właścicielem implementacji repozytorium stanu alertów, jego trwałego przechowywania oraz harmonogramu przejścia na nowy okres rozliczeniowy. NextPDF Enterprise egzekwuje limity i emituje alerty, ale sam nie uwierzytelnia najemcy ani nie przechowuje danych o zużyciu.

Granica zgodności prawnej

Do powierzchni rozliczeń nie ma zastosowania żadne ograniczenie kontroli eksportu. Wliczenia w plany, limity oraz warunki komercyjne są regulowane Twoją umową licencyjną, a nie egzekwowaniem w czasie wykonania. Niniejsza dokumentacja nie stanowi opinii prawnej ani umownej; w sprawie zakresu planu skonsultuj się z własnymi doradcami oraz ze swoją umową.