Enterprise sürüm

Billing — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Enterprise faturalama yüzeyinin derinlemesine referansıdır. Yüzeyin iki katmanı vardır. NextPDF\Enterprise\Billing içindeki faturalama modeli plan katmanlarını, kotaları, aşım politikalarını ve yinelenenleri kaldırılmış kullanım uyarılarını tanımlar. NextPDF\Enterprise\Billing\Substrate içindeki uygulama alt katmanı, bu modeli canlı istek yoluna fail-closed ve eşzamanlılık-güvenli olarak yerleştirir. Giriş noktaları PlanRegistry, QuotaManager, OverageCalculator, BillingAlertService ve QuotaEnforcementGuard’dır. İş akışı düzeyindeki kılavuz için Billing yetenek sayfasına bakın.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile gelir ve Enterprise-katmanı bir lisans zarfıyla etkinleşir. Bu yetkisi olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans alın.

Billing, özellik başına ayrı bir bayrağı olmayan temel bir Enterprise yeteneğidir; Enterprise paketi Core paketinin yanına kurulduğunda kullanılabilir. NextPDF Core (Apache-2.0) ve NextPDF Pro’nun hiçbir plan, kota veya aşım modeli yoktur; bu yüzeyin daha alt katmanda bir karşılığı yoktur. Plan içerikleri, kotalar ve ticari koşullar, çalışma zamanı uygulamasıyla değil, lisans sözleşmesince yönetilir; bu referans bir hukuki veya sözleşmeye dayalı görüş değildir.

Genel API yüzeyi

Tüm semboller NextPDF\Enterprise\Billing altında yer alır. substrate olarak işaretlenen satırlar NextPDF\Enterprise\Billing\Substrate altında yer alır. TenantContext, NextPDF\Enterprise\SaaS içindeki kimliği doğrulanmış kiracı türüdür.

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
`SaaSPlan` (enum)	—	String tabanlı plan katmanları: `standard`, `advanced`, `high_control`	—	Fırlatmaz	`label()` görünen adı döndürür
`PlanDefinition::__construct`	`SaaSPlan $plan`, `float $includedCuQuota`, `list<CapabilityCode> $capabilities`, `non-empty-string $priceTier`, `bool $intelligencePackIncluded`, `bool $privacyPackIncluded`	Değişmez plan değer nesnesi; girdileri verildiği gibi saklar	Yeni örnek	Fırlatmaz	`final readonly`; yükseltilmiş genel özellikler
`PlanDefinition::includesCapability`	`CapabilityCode $capability`	Katı kimlik üyelik denetimi	`bool`	Fırlatmaz	—
`PlanRegistry::__construct`	`list<PlanDefinition> $definitions`	Tanımları katmana göre indeksler; katman başına son tanım kazanır	Yeni kayıt defteri	Fırlatmaz	Testler ve beyaz-etiket plan kümeleri için
`PlanRegistry::get`	`SaaSPlan $plan`	Kanonik plan araması	`PlanDefinition`	Plan kayıtlı olmadığında `InvalidArgumentException`	—
`PlanRegistry::has`	`SaaSPlan $plan`	Kayıt yoklaması	`bool`	Fırlatmaz	—
`PlanRegistry::defaultRegistry` (static)	—	Üretim varsayılanları: Standard 1,000 CU; Advanced 5,000 CU artı Intelligence Pack; High Control 20,000 CU artı Intelligence ve Privacy Pack	`PlanRegistry`	Fırlatmaz	Sözleşme koşulları özel tanımlar gerektirmedikçe kullanın
`OveragePolicy` (enum)	—	`hard_stop`, `soft_stop`, `budget_alert`	—	Fırlatmaz	`httpStatusCode()` 402 / 429 / 200 eşler; `isBlocking()` yalnızca hard ve soft stop için doğrudur
`QuotaManager::__construct`	`PlanRegistry $planRegistry`, `OveragePolicy $overagePolicy`	Kayıt defterini tek bir politikaya bağlar	Yeni örnek	Fırlatmaz	—
`QuotaManager::checkQuota`	`TenantContext $tenant`, `SaaSPlan $plan`, `float $currentCu`	Kotada veya altında ya da engellemesiz bir politika altında sessizce döner	`void`	Engellemeli bir politika altında katı aşımda `QuotaExceededException`; kayıtlı olmayan bir planda kayıt defterinden `InvalidArgumentException`	`resetsAt` = sonraki ayın ilk günü, gece yarısı UTC
`QuotaManager::remainingQuota`	`SaaSPlan $plan`, `float $currentCu`	Saf okuma; asla engellemez	`float`	Kayıt defteri `InvalidArgumentException`	Aşımda negatif
`QuotaManager::usagePercentage`	`SaaSPlan $plan`, `float $currentCu`	Saf okuma; asla engellemez	`float`	Kayıt defteri `InvalidArgumentException`	İçerilen kota pozitif olmadığında `0.0`; aşımda `1.0` üzerinde
`OverageCalculator::calculate`	`PlanDefinition $plan`, `float $currentCu`	Değişmez bir aşım anlık görüntüsü hesaplar	`OverageResult`	Fırlatmaz	`final readonly`, durumsuz
`OverageResult`	`includedCu`, `usedCu`, `overageCu`, `usageRatio`, `isOverage`	Değişmez hesaplama sonucu	—	Fırlatmaz	`overageCu = max(0, used - included)`; `isOverage` katı aşım gerektirir
`BillingAlertType` (enum)	—	`quota_warning_80`, `quota_warning_100`, `budget_exceeded`, `monthly_cap_reached`	—	Fırlatmaz	`threshold()` 0.8 / 1.0 / 1.0 / 1.0; `severity()` warning / critical / critical / critical
`BillingAlertService::__construct`	`AlertStateRepositoryInterface $alertState`	Yinelenenlerin kaldırılması deposunu bağlar	Yeni örnek	Fırlatmaz	—
`BillingAlertService::evaluate`	`TenantContext $tenant`, `SaaSPlan $plan`, `PlanDefinition $planDef`, `float $currentCu`	Henüz tetiklenmemiş uyarıları artan eşik sırasına göre tetikler ve kaydeder	`list<BillingAlertType>`	Plan/tanım uyumsuzluğunda `InvalidArgumentException`	Yineleme-kaldırma anahtarı: kiracı, tür, UTC `YYYY-MM` dönemi
`BillingAlertService::clearAlerts`	`TenantContext $tenant`	Kiracının mevcut UTC dönemi için tetiklenmiş-durumunu temizler	`void`	Depo-tanımlı başarısızlıklar yayılır	Aynı dönem içinde uyarıları yeniden kurar
`AlertStateRepositoryInterface`	`hasAlertFired()`, `markAlertFired()`, `clearForPeriod()`	Dayanıklı uyarı-yineleme-kaldırma kalıcılık sözleşmesi	Yönteme göre	Uygulama-tanımlı	Operatör, yinelemeler genelindeki dayanıklılığa sahiptir
`InMemoryAlertStateRepository`	—	Dizi tabanlı tetiklenmiş-durum	Arabirime göre	Fırlatmaz	Yalnızca tek-istek yaşam döngüleri ve testler
`QuotaExceededException`	Readonly `currentCu`, `limitCu`, `resetsAt`, `tenantId`, `isSaaS`	Dağıtım-moduna duyarlı kota reddi	—	Fırlatılabilir olanın kendisi	`httpStatusCode()` 402 SaaS / 403 on-prem; `specCode()` `SPEC-BILLING-003` / `SPEC-LIC-001`; `toErrorEnvelope()` yapılandırılmış bir hata gövdesi verir
`DeploymentMode` (enum)	—	`saas`, `self_hosted_oss`, `local_development`	—	Fırlatmaz	Substrate. `enforcesQuota()` yalnızca `Saas` için doğrudur; devre-dışı bırakma her zaman açıktır
`QuotaEnforcementGuard::__construct`	`DeploymentMode`, `PlanResolverInterface`, `QuotaManager`, `UsageCounterStoreInterface`	Canlı kota geçidini birleştirir	Yeni örnek	Fırlatmaz	Substrate. `final readonly`
`QuotaEnforcementGuard::enforce`	`?TenantContext $tenant`, `non-empty-string $featureKey`, `float $amount = 1.0`	Atomik rezervasyonla fail-closed kota geçidi	`QuotaDecision` (yalnızca izin verilen sonuçlar)	Aşağıdaki ret taksonomisine bakın	Substrate. Kiracı kimlik doğrulamasından sonra, faturalandırılabilir işleyiciden önce monte edin
`PlanResolverInterface::resolve`	`TenantContext $tenant`	Bir kiracıyı planına ve özellik başına politikalarına çözer	`ResolvedPlan`	`NoPlanForTenantException`	Substrate. Bilinmeyen kiracılar için varsayılan-plan yedeği bir kusurdur
`RegistryPlanResolver`	`array<non-empty-string, ResolvedPlan> $plansByTenant`	Harita tabanlı çözümleyici	`ResolvedPlan`	Eşlenmemiş kiracılar için `NoPlanForTenantException`	Substrate. Yapısı gereği fail-closed
`ResolvedPlan::policyFor`	`non-empty-string $featureKey`	Çözülen planda politika araması	`?QuotaPolicy`	Fırlatmaz	Substrate. `null` bilinmeyen özellik demektir; koruma bunu reddeder
`QuotaPolicy`	`non-empty-string $featureKey`, `float $limit`, `OveragePolicy $overagePolicy`	Özellik başına sınır ve ihlal politikası	—	Fırlatmaz	Substrate. `UNLIMITED = -1.0`; `0.0` sınırı sıfır izin demektir, sınırsız değil; `isUnlimited()`, `isBlocking()`
`QuotaDecision`	Statik `bypassed()`, `unlimited()`, `consumed()`	İzin-verilen-sonuç değer nesnesi	`QuotaDecision`	Fırlatmaz	Substrate. `isAllowed()` her zaman doğrudur; bunun yerine her ret fırlatır
`UsageCounter`	Satır anlık görüntüsü: kiracı, özellik, dönem sınırları, `used`, `limit`, `updatedAt`	Değişmez kullanım satırı	—	Fırlatmaz	Substrate. `remaining()` negatif olabilir; `wouldExceed()` katıdır
`UsageCounterStoreInterface::get`	Kiracı, özellik, dönem sınırları, `float $limit`	Kullanım satırını okur, yoksa `used = 0` ile oluşturur	`UsageCounter`	`UsageStoreUnavailableException`	Substrate. Arka uç başarısızlığında asla falsy bir değer döndürmez
`UsageCounterStoreInterface::tryConsume`	Kiracı, özellik, dönem sınırları, `float $amount`, `float $limit`	Sınır içinde atomik karşılaştır-ve-ayarla rezervasyonu	`?UsageCounter` (rezervasyon sınırı ihlal edecekse `null`)	`UsageStoreUnavailableException`	Substrate. Destekleyen depoya karşı tek bir atomik işlem olmalıdır
`InMemoryUsageCounterStore`	—	Depo sözleşmesinin süreç-içi referans uygulaması	Arabirime göre	Arabirime göre	Substrate. Yalnızca tek süreç; atomiklik değişmezini belgeler
`QuotaEnforcementException` (abstract)	—	Her substrate reddinin temel türü	—	Fırlatılabilir ailesinin kendisi	Substrate. Her alt tür `httpStatusCode()` bildirir

public function checkQuota(TenantContext $tenant, SaaSPlan $plan, float $currentCu): void

public function evaluate(
    TenantContext $tenant,
    SaaSPlan $plan,
    PlanDefinition $planDef,
    float $currentCu,
): array

public function enforce(?TenantContext $tenant, string $featureKey, float $amount = 1.0): QuotaDecision

public function tryConsume(
    string $tenantId,
    string $featureKey,
    DateTimeImmutable $periodStart,
    DateTimeImmutable $periodEnd,
    float $amount,
    float $limit,
): ?UsageCounter;

QuotaEnforcementGuard::enforce ret taksonomisi

İstisna	HTTP durumu	Şu durumda yükseltilir
`MissingTenantContextException`	401	Kimliği doğrulanmış kiracı bağlamı olmayan SaaS modu
`NoPlanForTenantException`	402	Çözümleyici, kiracıya atanmış bir plan bulamaz
`UnknownFeatureException`	402	Çözülen plan, özellik anahtarı için hiçbir politika tanımlamaz
`UsageStoreUnavailableException`	503	Kullanım deposu okunamaz veya atomik olarak güncellenemez; pozitif olmayan bir `$amount` için de yükseltilir
`QuotaExceededException`	402 (SaaS) / 403 (on-prem)	Engelleyen bir politikanın kotası aşılır ya da eşzamanlı bir rezervasyon son boşluğu tüketir

Davranış sözleşmesi

Varsayılan kayıt defteri, artan CU kotaları ve yetenek kümeleriyle üç katman sunar (Standard / Advanced / High Control). Kayıtlı olmayan bir plan isteği açık bir InvalidArgumentException ile başarısız olur.
QuotaManager::checkQuota() yalnızca her iki koşul da geçerli olduğunda yükseltir: politika engelleyendir ve mevcut kullanım içerilen kotanın kesinlikle üzerindedir. Bir bütçe-uyarısı politikası asla yükseltmez; aşım, uyarılar aracılığıyla bildirilir.
remainingQuota() ve usagePercentage() saf okumalardır ve asla engellemez. Kalan kota aşımda negatife düşer; kullanım yüzdesi aşımda 1.0’ı aşar.
Uyarılar artan eşik sırasına göre değerlendirilir: %80 uyarı, %100 uyarı (kritik), ardından bütçe-aşıldı (kritik). Bütçe-aşıldı, katı aşıma göre geçitlenir; tam olarak %100’deki kullanım, bütçe-aşıldıyı değil %100 uyarısını tetikler.
Her uyarı türü, faturalama dönemi başına kiracı başına en fazla bir kez tetiklenir. Tetiklenmiş-durum AlertStateRepositoryInterface aracılığıyla kaydedilir; böylece yinelenenlerin kaldırılması, seçilen uygulama kadar dayanıklıdır.
Yineleme-kaldırma anahtarı, UTC YYYY-MM dönemini gömer. Bu nedenle yeni bir takvim ayı, her uyarı türünü otomatik olarak yeniden kurar; devredilme yeniden-kurulması için hiçbir temizleme çağrısı gerekmez. clearAlerts() mevcut dönemi temizler; bu da uyarıları dönem ortasında, örneğin bir plan yükseltmesinden sonra yeniden kurar.
evaluate() içindeki bir plan-uyumsuzluğu koruması, sağlanan plan ve plan tanımının uyuşmadığı bir çağrıyı reddeder; bu, kiracının planından farklı bir katmandan gelen bir tanıma karşı korur.
Tüm dönem aritmetiği UTC’ye sabitlenmiştir. Kota-aşıldı sıfırlama anı, bir sonraki takvim ayının ilk günü gece yarısı UTC’dir; bir soft-stop yanıtı bunu yeniden-deneme ufku olarak duyurmalıdır.
QuotaEnforcementGuard, SaaS modunda fail-closed’dur. Eksik kiracı, eksik plan, bilinmeyen özellik, depo kesintisi ve kota ihlali; hepsi reddeder; hiçbir şey örtük bir izne düşmez. SaaS olmayan dağıtımlar, korumayı SaaS olmayan bir DeploymentMode ile oluşturarak devre dışı bırakır.
Engelleyen politikalar, kullanımı atomik bir karşılaştır-ve-ayarla olan UsageCounterStoreInterface::tryConsume aracılığıyla rezerve eder. Eşzamanlı istekler, kullanımı topluca sınırın ötesine itemez; ön denetim geçmiş olsa bile yarışı kaybeden QuotaExceededException alır.
Bir bütçe-uyarısı politikası altında koruma, tüketimi mümkün-olan-en-iyi biçimde kaydeder ve asla reddetmez; yumuşak tavanı aşan bir rezervasyon yine de satırı sınırda kaydeder.
QuotaExceededException dağıtım-moduna duyarlıdır: SaaS retleri, SPEC-BILLING-003 spesifikasyon koduyla HTTP 402’ye eşlenir ve yeniden-denenebilir olarak işaretlenir; on-prem retleri, SPEC-LIC-001 ile HTTP 403’e eşlenir.
Kitaplık, HTTP yanıtlarını kendisi yaymaz. Bildirilen durum kodları, fırlatılan bir reddi bir yanıta eşleyen ve faturalandırılabilir işleyiciyi çağırmaması gereken kenar katmanı için sözleşmedir.

Uç durumlar ve başarısızlık modları

Pozitif olmayan içerilen kota. usagePercentage(), evaluate() ve OverageCalculator::calculate(), sıfıra bölmek yerine 0.0 kullanım oranı verir. Eşik uyarıları o zaman yalnızca orandan asla tetiklenmez.
Bütçe-uyarısı artı büyük aşım. Yönetici ve koruma, her ikisi de izin-verilen sonuçlar döndürür. Bir istisnanın yokluğunu kota içinde olmanın kanıtı olarak ele almayın; OverageResult’a veya uyarı akışına başvurun.
Tam olarak sınırda. currentCu == includedCuQuota durumunda checkQuota() geçer. BudgetExceeded katı aşım gerektirir. UsageCounter::wouldExceed() de katıdır.
MonthlyCapReached. Enum bu dördüncü uyarı türünü bildirir, ancak BillingAlertService::evaluate() bunu asla yaymaz; aday listesi yalnızca üç eşik uyarısını kapsar. Bu, bu modülün dışındaki üst-sınır-izleyen yayıcılar için ayrılmıştır.
Yinelenen katman tanımları. PlanRegistry, katman değerine göre indeksler; bir katman için son tanım, öncekileri sessizce değiştirir. Kayıt defterlerini yinelenenleri kaldırılmış bir listeden oluşturun.
Sıfır izin karşısında sınırsız. 0.0 değerinde bir QuotaPolicy sınırı, dönemdeki her tüketimin aşım olduğu anlamına gelir. Ölçümü yalnızca negatif UNLIMITED nöbetçisi devre dışı bırakır; isUnlimited() asla engellemez.
Pozitif olmayan rezervasyon miktarı. enforce(), pozitif olmayan bir $amount’ı UsageStoreUnavailableException (503) ile fail-closed reddeder. Bu, bir depo kesintisi değil, bir çağıran kusurudur.
Depo kesintisi. Herhangi bir okuma veya rezervasyon başarısızlığı UsageStoreUnavailableException olarak ortaya çıkar ve reddeder. Koruma, ölçer kapalıyken asla ölçülmemiş işe izin vermez.
Bellek-içi uygulamalar. InMemoryAlertStateRepository ve InMemoryUsageCounterStore yalnızca tek bir PHP süreci içinde doğrudur. Çok-kopyalı dağıtımlar, gerçek atomikliğe sahip bir veri deposuyla desteklenen uygulamalar sağlamalıdır; oku-sonra-yaz bir depo, yük altında kota-aşımına izin veren bir kusurdur.
FIPS modu. Billing kendine ait hiçbir kriptografik işlem yapmaz ve hiçbir FIPS’e özgü davranışı yoktur. Tükettiği kiracı kimliği, FIPS duruşu SaaS yüzeyiyle belgelenen, kimliği doğrulanmış bir bağlamdan kaynaklanmalıdır.

Uygunluk

İddia	Standart	Madde
402 durum kodu gelecekte kullanılmak üzere ayrılmıştır; kendine ait hiçbir normatif istek anlam bilimi taşımaz.	RFC 9110	§15.5.3
429, istemcinin belirli bir zaman diliminde çok fazla istek gönderdiğini gösterir (“hız sınırlama”).	RFC 6585	§4
Retry-After, kullanıcı aracısının bir takip isteği yapmadan önce ne kadar beklemesi gerektiğini gösterir.	RFC 9110	§10.2.3

Tüm maddeler başka sözcüklerle ifade edilmiştir; NextPDF normatif metni yeniden üretmez. NextPDF, bu yüzey için hiçbir HTTP-protokolü uygunluk veya sertifikasyon iddiasında bulunmaz. OveragePolicy::httpStatusCode() tarafından bildirilen 402 / 429 / 200 eşlemesi ve korumanın 401 / 402 / 503 ret kodları, yukarıdaki maddelerle uyumlu bir ürün kuralıdır: RFC 9110, 402’yi ayırır, bu nedenle buradaki ödeme-reddi kullanımı, IETF-tanımlı bir anlam bilimi değil, yaygın sektör kuralıdır. Soft-stop yeniden-deneme ufku (resetsAt), bir kenar katmanının Retry-After yönlendirmesi olarak sunması gereken değerdir. Gerçek HTTP yanıtlarını, başlıkları ve önbelleğe alma davranışını yaymak, barındıran uygulamanın sorumluluğundadır.

Geliştirme notları

Modeli PlanRegistry::defaultRegistry(), bir OveragePolicy ve bir QuotaManager’dan oluşturun; uyarı için dayanıklı bir AlertStateRepositoryInterface uygulamasıyla BillingAlertService ekleyin.
QuotaEnforcementGuard’ı istek işlem hattında kiracı kimlik doğrulamasından sonra ve faturalandırılabilir işleyiciden önce monte edin. QuotaEnforcementException’ı ve faturalama QuotaExceededException’ını kenarda yakalayın ve httpStatusCode()’u yanıta eşleyin.
Bu modüldeki plan tanımları, faturalama için tek doğru kaynaktır; dağıtımınızda başka bir yerde paralel bir faturalama tanımı tutmayın.
Bellek-içi uygulamalar, tüm yüzeyi G/Ç olmadan birim-test edilebilir kılar. Önerilen sınır testleri: tam olarak kotadaki kullanım, bir birim üzerinde, 0.8 ve 1.0’daki oran eşikleri, plan-uyumsuzluğu koruması, CAS yarışı (son boşluk birimine karşı iki rezervasyon) ve depo-kesintisi reddi.
Çekirdek model sınıfları @since 2.2.0 taşır; alt katman @since 2.3.0 taşır. Mevcut paket hattı 3.1.0’dır.
Operatör; uyarı-durumu deposu ve kullanım-deposu uygulamalarına, bunların yinelemeler genelindeki dayanıklılığına ve clearAlerts() aracılığıyla dönem-ortası herhangi bir uyarı yeniden-kurulmasına sahiptir.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.