Enterprise phiên bản

Lập hóa đơn

Tổng quan nhanh

NextPDF Enterprise theo dõi mức sử dụng compute unit (CU) theo từng tenant so với một hạn mức gói và áp dụng một chính sách vượt mức có thể cấu hình: chặn cứng, chặn kèm hướng dẫn thử lại, hoặc tiếp tục và cảnh báo. Nó cũng phát ra các cảnh báo sử dụng đã khử trùng lặp tại các ngưỡng 80%, 100%, và vượt ngân sách. Trang này mô tả hành vi lập hóa đơn có thể quan sát được và hợp đồng công khai.

Tình trạng khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt với một license envelope bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận giấy phép.

Lập hóa đơn là một năng lực Enterprise cơ sở không có cờ riêng theo từng tính năng; các bậc gói và hạn mức đi kèm của chúng được phân giải thông qua sổ đăng ký gói.

Tổng quan khái niệm

Lập hóa đơn đo lường mức tiêu thụ bằng compute unit. Mỗi tenant chạy dưới một gói; mỗi gói mang theo một hạn mức CU đi kèm và một bộ năng lực. Có ba bậc gói mặc định đi kèm — Standard, Advanced, và High Control — với hạn mức đi kèm lớn dần và bộ năng lực rộng dần (các bậc cao hơn bổ sung các gói tiện ích Intelligence và Privacy). Sổ đăng ký là điểm tra cứu chính tắc; một triển khai white-label có thể dựng nó với các định nghĩa tùy chỉnh.

Chính sách vượt mức quyết định điều gì xảy ra khi một tenant vượt qua hạn mức đi kèm của nó. Một chính sách chặn cứng chặn việc xử lý ngay lập tức và mang ngữ nghĩa HTTP 402. Một chính sách chặn mềm chặn kèm hướng dẫn thử lại và mang ngữ nghĩa HTTP 429. Một chính sách cảnh báo ngân sách không bao giờ chặn — việc xử lý tiếp tục và cảnh báo được phát ra thay thế, mang ngữ nghĩa HTTP 200. Chỉ chặn cứng và chặn mềm là chặn; trình quản lý hạn mức chỉ phát sinh một điều kiện vượt hạn mức khi chính sách chặn và hạn mức đi kèm thực sự bị vượt.

Dịch vụ cảnh báo đánh giá mức sử dụng so với các ngưỡng theo thứ tự tăng dần — cảnh báo 80%, cảnh báo 100%, rồi vượt ngân sách — và mỗi loại cảnh báo phát ra nhiều nhất một lần cho mỗi kỳ lập hóa đơn của mỗi tenant. Vượt ngân sách yêu cầu vượt mức nghiêm ngặt, không chỉ là chạm 100%. Trạng thái cảnh báo được theo dõi thông qua một repository interface, nên việc khử trùng lặp tồn tại qua các yêu cầu, và dịch vụ phơi bày một thao tác rõ ràng để đặt lại trạng thái cảnh báo khi chuyển sang kỳ lập hóa đơn mới.

Vì sao nó hoạt động theo cách này

Lập hóa đơn được xây dựng như một lớp quyết định thuần túy, không phải một hệ thống lưu trữ. Các lần kiểm tra hạn mức, phép tính vượt mức, và đánh giá cảnh báo chạy trong bộ nhớ so với một PlanDefinition và một con số sử dụng hiện tại, không có I/O trên đường kiểm tra. Việc lưu trữ bền vững nằm ngoài quyết định đó: trạng thái khử trùng lặp cảnh báo chỉ được tiếp cận thông qua AlertStateRepositoryInterface mà một người vận hành cung cấp, điều này giữ tính bền vững và ranh giới kỳ lập hóa đơn dưới sự kiểm soát của máy chủ. Kết quả vượt mức là một enum tường minh nhỏ ánh xạ mỗi chính sách tới một mã trạng thái HTTP cố định, nên quyết định chặn-hay-tiếp-tục vẫn mang tính xác định và có thể kiểm toán. Sự tách biệt đó cho phép cùng một bề mặt lập hóa đơn chạy không đổi từ một instance đơn lẻ tới một đội tàu multi-tenant có đo lường. Bối cảnh thiết kế: Vận hành NextPDF trong sản phẩm.

Bề mặt API công khai

composer require nextpdf/enterprise:^3

Các điểm tích hợp được hỗ trợ là sổ đăng ký gói (get, has, defaultRegistry), trình quản lý hạn mức (checkQuota, remainingQuota, usagePercentage), trình tính vượt mức (calculate, trả về một kết quả vượt mức bất biến), enum chính sách vượt mức (httpStatusCode, isBlocking), và dịch vụ cảnh báo lập hóa đơn (evaluate, clearAlerts). Repository trạng thái cảnh báo là một interface — hãy cung cấp một bản triển khai trong bộ nhớ cho kiểm thử hoặc một bản bền vững cho sản phẩm.

Mẫu mã — bắt đầu nhanh

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

Mẫu mã — sản phẩm

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

Trường hợp biên & điều cần lưu ý

Cảnh báo ngân sách không bao giờ chặn. Dưới một chính sách cảnh báo ngân sách, checkQuota không phát sinh ngay cả khi đã vượt xa hạn mức; hãy dựa vào các cảnh báo được phát ra, không phải vào một ngoại lệ.
Vượt ngân sách cần vượt mức nghiêm ngặt. Chạm đúng 100% sẽ phát ra cảnh báo 100%, không phải vượt ngân sách; vượt ngân sách yêu cầu mức sử dụng vượt nghiêm ngặt trên hạn mức đi kèm.
Cảnh báo khử trùng lặp theo từng kỳ. Mỗi loại cảnh báo phát ra một lần cho mỗi tenant trong mỗi kỳ lập hóa đơn. Hãy xóa trạng thái cảnh báo khi chuyển kỳ, nếu không cảnh báo sẽ không phát lại trong kỳ tiếp theo.
Hạn mức đi kèm bằng không hoặc chưa đặt. Một gói có hạn mức đi kèm không dương sẽ báo cáo tỷ lệ sử dụng 0.0 thay vì chia cho không.
Đặt lại kỳ là ranh giới tháng tiếp theo. Thời điểm đặt lại vượt hạn mức mặc định là ngày đầu tiên của tháng dương lịch tiếp theo lúc nửa đêm.

Hiệu năng

Các lần kiểm tra hạn mức, tính vượt mức, và đánh giá cảnh báo là các thao tác thời gian hằng số, trong bộ nhớ, so với một định nghĩa gói và con số sử dụng hiện tại được cung cấp. Không có I/O nào trên đường kiểm tra trừ khi bản triển khai repository trạng thái cảnh báo của bạn thực hiện I/O.

Lưu ý bảo mật

Các quyết định lập hóa đơn được suy dẫn từ một con số sử dụng hiện tại được giới hạn theo tenant do bên gọi cung cấp; danh tính tenant phải đến từ bối cảnh đã được xác thực, không bao giờ từ đầu vào do client cung cấp. Bề mặt lập hóa đơn thực thi hạn mức và phát ra cảnh báo — bản thân nó không xác thực tenant.

Tính phù hợp

Các kết quả của chính sách vượt mức mang ngữ nghĩa mã trạng thái HTTP tiêu chuẩn: payment-required (402) cho chặn cứng, too-many-requests (429) kèm hướng dẫn thử lại cho chặn mềm, và success (200) cho cảnh báo ngân sách, theo đặc tả ngữ nghĩa HTTP của IETF (RFC 9110) cho các lớp 402, 429, và 2xx. RFC 9110 không được truy xuất từ kho ngữ liệu RAG cho trang này; ánh xạ này được khẳng định từ các mã trạng thái khai báo trong mã và đặc tả ngữ nghĩa HTTP nổi tiếng, được đánh dấu ở đây là khai báo-trong-mã thay vì RAG-verified.

Hợp đồng hành vi

Mức tiêu thụ được đo bằng compute unit; mỗi tenant chạy dưới một gói có hạn mức CU đi kèm và một bộ năng lực.
Chính sách vượt mức là một trong chặn cứng (402, chặn), chặn mềm (429 kèm hướng dẫn thử lại, chặn), hoặc cảnh báo ngân sách (200, không chặn); một điều kiện vượt hạn mức chỉ được phát sinh khi chính sách chặn và hạn mức đi kèm thực sự bị vượt.
Cảnh báo đánh giá theo thứ tự tăng dần (cảnh báo 80%, cảnh báo 100%, vượt ngân sách) và mỗi loại phát ra nhiều nhất một lần cho mỗi kỳ lập hóa đơn của mỗi tenant; vượt ngân sách yêu cầu vượt mức nghiêm ngặt.
Một hạn mức đi kèm không dương sẽ báo cáo tỷ lệ sử dụng 0.0 thay vì chia cho không.
Các lần kiểm tra hạn mức, tính vượt mức, và đánh giá cảnh báo là các thao tác thời gian hằng số trong bộ nhớ, không có I/O trên đường kiểm tra trừ khi repository trạng thái cảnh báo thực hiện I/O.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Phương án dự phòng Core

NextPDF Core (Apache-2.0) không có bề mặt lập hóa đơn, hạn mức, hay vượt mức nào — hoàn toàn không; năng lực này không có phương án tương đương ở bậc Core. Việc xử lý của Core không bị đo lường, không bị giới hạn theo hạn mức, hay được cảnh báo bởi NextPDF.

Phương án dự phòng Pro

NextPDF Pro không có bề mặt lập hóa đơn, hạn mức, hay vượt mức nào — hoàn toàn không; năng lực này không có phương án tương đương ở bậc Pro. Sổ đăng ký gói, trình quản lý hạn mức, trình tính vượt mức, và dịch vụ cảnh báo chỉ đi kèm trong gói nextpdf/enterprise.

Lưu ý về ranh giới Enterprise

Sổ đăng ký gói, chính sách vượt mức, và việc khử trùng lặp cảnh báo được mô tả ở mức hành vi. Repository trạng thái cảnh báo là một interface; việc lưu trữ bền vững do máy chủ cung cấp, và chiến lược lưu trữ trạng thái cảnh báo nội bộ nằm ngoài phạm vi của bề mặt công khai.

Ranh giới triển khai

Các quyết định lập hóa đơn được suy dẫn từ một con số sử dụng hiện tại được giới hạn theo tenant do bên gọi cung cấp. Người vận hành sở hữu bản triển khai repository trạng thái cảnh báo, việc lưu trữ bền vững của nó, và lịch chuyển kỳ lập hóa đơn. NextPDF Enterprise thực thi hạn mức và phát ra cảnh báo nhưng bản thân nó không xác thực tenant hay lưu trữ bền vững mức sử dụng.

Ranh giới tuân thủ pháp lý

Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt lập hóa đơn. Các phần đi kèm của gói, hạn mức, và điều khoản thương mại được điều chỉnh bởi thỏa thuận giấy phép của bạn, không phải bởi việc thực thi lúc chạy. Tài liệu này không phải là một ý kiến pháp lý hay hợp đồng; hãy tham vấn các cố vấn của riêng bạn và thỏa thuận của bạn về phạm vi gói.