Enterprise редакция

Биллинг

Кратко

NextPDF Enterprise отслеживает потребление вычислительных единиц (CU) на каждого арендатора относительно квоты тарифного плана и применяет настраиваемую политику превышения: жёсткая блокировка, блокировка с указанием повтора либо продолжение с оповещением. Он также инициирует дедуплицированные оповещения о потреблении на порогах 80 %, 100 % и превышения бюджета. Эта страница описывает наблюдаемое поведение биллинга и публичный контракт.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без этого права доступа не загружает классы данной возможности. Сравнить редакции и получить лицензию.

Биллинг — это базовая возможность Enterprise без отдельного флага для каждой функции; уровни планов и включённые в них квоты определяются через реестр планов.

Концептуальный обзор

Биллинг измеряет потребление в вычислительных единицах. Каждый арендатор работает по плану; каждый план несёт включённую квоту CU и набор возможностей. Поставляются три уровня плана по умолчанию — Standard, Advanced и High Control — с прогрессивно большими включёнными квотами и прогрессивно более широкими наборами возможностей (более высокие уровни добавляют дополнительные пакеты Intelligence и Privacy). Реестр — это каноническая точка поиска; развёртывание с собственным брендом может сконструировать его с пользовательскими определениями.

Политика превышения решает, что происходит, когда арендатор выходит за пределы своей включённой квоты. Политика жёсткой блокировки немедленно блокирует обработку и несёт семантику HTTP 402. Политика мягкой блокировки блокирует с указанием повтора и несёт HTTP 429. Политика бюджетного оповещения никогда не блокирует — обработка продолжается, а вместо этого инициируются оповещения, неся HTTP 200. Блокирующими являются только жёсткая и мягкая блокировка; менеджер квот вызывает условие превышения квоты только тогда, когда политика блокирует и включённая квота действительно превышена.

Служба оповещений оценивает потребление относительно порогов в порядке возрастания — предупреждение 80 %, предупреждение 100 %, затем превышение бюджета — и каждый тип оповещения инициируется не более одного раза за расчётный период на арендатора. Превышение бюджета требует строгого превышения, а не просто достижения 100 %. Состояние оповещений отслеживается через интерфейс репозитория, поэтому дедупликация сохраняется между запросами, а служба предоставляет понятную операцию для сброса состояния оповещений при смене расчётного периода.

Почему это устроено именно так

Биллинг построен как чистый слой принятия решений, а не система хранения. Проверки квоты, расчёт превышения и оценка оповещений выполняются в памяти относительно PlanDefinition и одного значения текущего потребления, без ввода-вывода на пути проверки. Сохранение находится вне этого решения: состояние дедупликации оповещений достигается только через AlertStateRepositoryInterface, который предоставляет оператор, что оставляет долговечность и границу расчётного периода под контролем хоста. Результат превышения — это небольшое явное перечисление, сопоставляющее каждую политику с фиксированным HTTP-статусом, поэтому решение «блокировать или продолжить» остаётся детерминированным и поддающимся аудиту. Такое разделение позволяет одной и той же поверхности биллинга работать без изменений от одного экземпляра до тарифицируемого многоарендного парка. Проектный контекст: Эксплуатация NextPDF в продакшне.

Публичный программный интерфейс

composer require nextpdf/enterprise:^3

Поддерживаемые точки интеграции — это реестр планов (get, has, defaultRegistry), менеджер квот (checkQuota, remainingQuota, usagePercentage), калькулятор превышения (calculate, возвращающий неизменяемый результат превышения), перечисление политики превышения (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, а не делит на ноль.
Сброс периода — это граница следующего месяца. Момент сброса превышения квоты по умолчанию — первый день следующего календарного месяца в полночь.

Производительность

Проверки квоты, расчёт превышения и оценка оповещений — это операции с постоянным временем в памяти относительно определения плана и предоставленного значения текущего потребления. На пути проверки нет ввода-вывода, если только его не выполняет ваша реализация репозитория состояния оповещений.

Примечания по безопасности

Решения биллинга выводятся из ограниченного арендатором значения текущего потребления, предоставленного вызывающей стороной; идентификация арендатора должна поступать из аутентифицированного контекста, а никогда из предоставленного клиентом ввода. Поверхность биллинга применяет квоту и выдаёт оповещения — она сама не аутентифицирует арендатора.

Соответствие

Результаты политики превышения несут стандартную семантику статуса HTTP: требуется оплата (402) для жёсткой блокировки, слишком много запросов (429) с указанием повтора для мягкой блокировки и успех (200) для бюджетного оповещения, следуя спецификации семантики HTTP IETF (RFC 9110) для классов 402, 429 и 2xx. RFC 9110 не извлекался из корпуса RAG для этой страницы; это сопоставление утверждается на основе объявленных в коде кодов статуса и общеизвестной спецификации семантики HTTP, и помечено здесь как объявленное в коде, а не проверенное по RAG.

Контракт поведения

Потребление измеряется в вычислительных единицах; каждый арендатор работает по плану с включённой квотой CU и набором возможностей.
Политика превышения — одна из жёсткой блокировки (402, блокирующая), мягкой блокировки (429 с указанием повтора, блокирующая) или бюджетного оповещения (200, неблокирующая); условие превышения квоты вызывается только тогда, когда политика блокирует и включённая квота действительно превышена.
Оповещения оцениваются в порядке возрастания (предупреждение 80 %, предупреждение 100 %, превышение бюджета), и каждый тип инициируется не более одного раза за расчётный период на арендатора; превышение бюджета требует строгого превышения.
Неположительная включённая квота сообщает коэффициент потребления 0.0, а не делит на ноль.
Проверки квоты, расчёт превышения и оценка оповещений — это операции с постоянным временем в памяти без ввода-вывода на пути проверки, если только его не выполняет репозиторий состояния оповещений.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов находятся вне области рассмотрения.

Резервный вариант Core

У NextPDF Core (Apache-2.0) нет поверхности биллинга, квот или превышения — никакой; у этой возможности нет эквивалента уровня Core. Обработка в Core не измеряется, не ограничивается квотой и не оповещается со стороны NextPDF.

Резервный вариант Pro

У NextPDF Pro нет поверхности биллинга, квот или превышения — никакой; у этой возможности нет эквивалента уровня Pro. Реестр планов, менеджер квот, калькулятор превышения и служба оповещений поставляются только в пакете nextpdf/enterprise.

Примечание о границе Enterprise

Реестр планов, политика превышения и дедупликация оповещений описаны на уровне поведения. Репозиторий состояния оповещений — это интерфейс; долговечное сохранение предоставляется хостом, а внутренняя стратегия хранения состояния оповещений находится вне области публичной поверхности.

Граница развёртывания

Решения биллинга выводятся из ограниченного арендатором значения текущего потребления, предоставленного вызывающей стороной. Оператор владеет реализацией репозитория состояния оповещений, его сохранением и расписанием смены расчётного периода. NextPDF Enterprise применяет квоту и выдаёт оповещения, но сам не аутентифицирует арендатора и не сохраняет потребление.

Граница юридического соответствия

Никакой барьер экспортного контроля не применяется к поверхности биллинга. Включения в план, квоты и коммерческие условия регулируются вашим лицензионным соглашением, а не применением во время выполнения. Эта документация не является юридическим или договорным заключением; обращайтесь к собственным консультантам и своему соглашению по поводу объёма плана.