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⁩ بدلًا من القسمة على الصفر.
فحوصات الحصّة وحساب التجاوز وتقييم التنبيه عمليات في الذاكرة ثابتة الزمن دون دخل/خرج على مسار الفحص ما لم يُجرِه مستودع حالة التنبيه.

حدّ النشر

توثّق هذه الصفحة السلوك القابل للرصد خارجيًّا وسطح واجهة البرمجة العام المدعوم فقط. أما مسارات أسماء النطاقات الداخلية، وأصناف المساعدة، وجداول الآليات، وأسماء ملفات أدلّة التشغيل، وبادئات التذاكر، فخارج النطاق.

احتياطي ⁨Core⁩

‏⁨NextPDF Core⁩ (⁨Apache-2.0⁩) لا يملك سطح فوترة أو حصّة أو تجاوز — لا شيء؛ ولهذه القدرة لا مكافئ في درجة ⁨Core⁩. ولا يقيس ⁨NextPDF⁩ معالجة ⁨Core⁩ ولا يبوّبها بحصّة ولا ينبّه عليها.

احتياطي ⁨Pro⁩

‏⁨NextPDF Pro⁩ لا يملك سطح فوترة أو حصّة أو تجاوز — لا شيء؛ ولهذه القدرة لا مكافئ في درجة ⁨Pro⁩. ويُشحَن سجل الخطط ومدير الحصّة وحاسبة التجاوز وخدمة التنبيه في حزمة nextpdf/enterprise فقط.

ملاحظة حدّ ⁨Enterprise⁩

يُوصَف سجل الخطط، وسياسة التجاوز، ونزع تكرار التنبيهات على مستوى السلوك. ومستودع حالة التنبيه واجهة؛ ويوفّر المضيف الاحتفاظ الدائم، واستراتيجية تخزين حالة التنبيه الداخلية خارج نطاق السطح العام.

حدّ النشر التشغيلي

تُشتقّ قرارات الفوترة من رقم استخدام حالي محصور بالمستأجر يقدّمه المُستدعي. ويملك المُشغِّل تنفيذ مستودع حالة التنبيه، واحتفاظه، وجدول انقلاب فترة الفوترة. ويفرض ⁨NextPDF Enterprise⁩ الحصّة ويصدر التنبيهات لكنه لا يُصادِق المستأجر بنفسه ولا يحتفظ بالاستخدام.

حدّ الامتثال القانوني

لا ينطبق أي قيد لضوابط التصدير على سطح الفوترة. وتُحكَم مُضمَّنات الخطط والحصص والشروط التجارية باتفاقية ترخيصك، لا بالفرض في وقت التشغيل. وهذه الوثيقة ليست رأيًا قانونيًّا أو تعاقديًّا؛ استشِر مستشاريك واتفاقيتك بشأن نطاق الخطّة.