تشغيل قياس الاستخدام

يفصل Nibleaf استخدام المنتج عن المدفوعات. يحفظ Postgres الخطط وإعداد المقاييس والاستحقاقات ونقاط تحقق التصدير وعلامة تثبت احتمال كتابة حقائق الاستخدام، كما يحفظ صندوق إرسال علائقيًا محدودًا وخاليًا من المحتوى حتى تأكيد الكتابة. ويحفظ ClickHouse الحقائق عالية الحجم والإسقاطات الساعية وإثبات التغطية والعمل المعلق وعلامات الحذف. ولا ينشئ هذا المسار عميلًا أو اشتراكًا أو صفحة دفع أو فاتورة أو عملية تحصيل.

ما الذي يُقاس؟

تأتي القيم الحالية للمقاعد والصفحات المنشورة والنطاقات المخصصة وحجم الملفات من صفوف المنتج الموثوقة. أما حقائق فترة UTC فهي مشاهدات الصفحات العامة واستعلامات البحث وإجابات الذكاء الاصطناعي المكتملة ورموز الإدخال والإخراج المعروفة والمقاطع المضمّنة الجديدة وبايتات مدخلات الفهرسة وعمليات البناء.

لا يحوّل Nibleaf القياس المفقود إلى صفر. يظهر المصدر غير المتاح بالحالة unavailable. وإذا وُجدت إجابة بلا بيانات الرموز، تظهر قراءة الرموز بالحالة partial وبكمية فارغة.

حدود الخصوصية

لا تحتوي حقيقة الاستخدام إلا على نطاق المؤسسة والمشروع المشتق في الخادم ومعرّف الحدث وإصدار العقد وطوابع UTC ومفتاح المقياس والكمية كسلسلة عشرية ورابط التصحيح والمصدر الموثوق. ولا تحتوي على المطالبات أو الإجابات أو عبارات البحث أو تجزئاتها أو محتوى الوثائق أو المتجهات أو أسماء الملفات وروابطها أو الأسرار أو عناوين IP أو وكلاء المستخدم الخام أو معرّفات المستخدم والجلسة أو أسماء المزود والنموذج.

الفترات والمحاولات والتصحيحات والبيانات المتأخرة

• الفترة نصف مفتوحة بتوقيت UTC: [البداية، النهاية المستبعدة).
• تعيد المحاولة استخدام معرّف حتمي، وتزيل قراءات FINAL التكرار قبل الجمع.
• قبل محاولة Redis تُحفظ دفعة UsageEvent v1 المتحققة والخالية من المحتوى مع معرّف مهمة حتمي مرتبط بالمستأجر والمشروع. لذلك يستعيد العامل المجدول كل خمس دقائق فشل الإدراج الصريح أو انتهاء المهلة ذي النتيجة المجهولة، ويعيد محاولة المهمة نفسها عند تعطل ClickHouse دون التراجع عن النشر أو الفهرسة.
• تستخدم المعرّفات الحتمية تخطيط UUIDv8 المخصص وفق RFC 9562 والمشتق من SHA-256 مع فصل الغرض والنطاق، وتُضبط بتات الإصدار والنمط صراحةً. هذا العقد غير المنشور لا يملك معرّفات UUIDv5 تتطلب ترحيلًا.
• التصحيح حدث جديد بكمية موقعة يشير إلى الحدث الأصلي، ولا تعدّل الحقيقة مكانها.
• يُنسب الحدث المتأخر إلى فترته الأصلية عبر occurredAt، ويطلب تسوية فورية، كما يفحص عامل مجدول كل خمس دقائق الفترات المعلقة بعد الأعطال أو إعادة التشغيل.
• تنتقل الكميات كسلاسل عشرية لتجنب فقدان دقة أعداد JSON. يجب أن تلائم كل حقيقة عددًا صحيحًا موقعًا ذا 64 بت، بينما تستخدم التجميعات والملخصات وسجلات المزود ونقاط التحقق المجال الدقيق الأوسع Decimal(38,0). يُرفض التجاوز بدل التضييق أو الالتفاف أو التقريب.

لا يُقرأ المجموع التاريخي إلا لفترة شهر UTC مغلق كاملة مع إثبات تغطية مطابق. ولا تتحول الصفوف أو المقاييس المفقودة إلى صفر. وتظهر الفترات التاريخية الجزئية أو العابرة لحد الاحتفاظ بالحقائق الخام بالحالة غير المتاحة.

تفحص الملخصات نقاط التحقق المعلقة الفعلية والمتقاطعة مع الفترة المطلوبة. يظهر العمل الحديث partial، وإذا بقي أكثر من 24 ساعة يظهر unavailable ولا يتحول إلى صفر مكتمل. تُحذف إيصالات العمل المكتمل بعد 24 ساعة، ولا تُحذف الإيصالات المعلقة تلقائيًا.

الحدود إرشادية في هذا الإصدار

لا يُستخدم ClickHouse كبوابة تزامن. تحفظ الواجهة سلوك المقياس المكوّن observe أو warn أو block، لكنها تعيد enforcement=advisory ولا تمنع أي عملية منتج في هذا الإصدار. يتطلب الإنفاذ مستقبلًا دورة حجز واعتماد وتحرير وتسوية ذرية مرتبطة بكل نقطة دخول قابلة للمنع. لذلك لا يتضمن هذا الإصدار نموذج حجز غير مستخدمًا يوحي بإنفاذ غير موجود.

لا يوجد عمدًا إجراء reserveProjectUsage في هذا الإصدار؛ فالاسم غير الموصول سيوحي خطأً بإنفاذ ذري. البديل الثابت في الإصدار الأول هو getProjectUsageSummary لحالة المقاييس الإرشادية، وgetProjectEntitlements وcheckProjectEntitlement لفحص القدرات العامة، وresolveProjectCapability لإجراءات المنتج الداخلية المصرح بها مسبقًا.

دلالات اللقطة وتجهيز الخطة

• يحسب editor_seat الأعضاء النشطين غير المعلقين.
• يقرأ published_page أحدث نشر READY له لقطة ثابتة، وإلا تبقى القيمة مجهولة.
• يحسب custom_domain النطاقات المتحققة ذات TLS النشط فقط.
• يجمع asset_storage_byte أحجام الملفات المخزنة بدقة.

تستدعي كل معاملة تنشئ مؤسسة assignDefaultUsagePlan، ويربط الترحيل المؤسسات الحالية بخطة free المحايدة والنشطة دون اختراع حدود تجارية. تُفحص حالة الخطة وانتهاؤها وأعلام تفعيل الخطة والمقياس قبل منح الاستحقاق. ولا تُستخدم بيانات المؤسسة القديمة إلا كاحتياط محدود عند غياب الربط العلائقي؛ وتبقى البيانات التالفة أو الكبيرة مجهولة.

التطبيق والتحقق

pnpm db:deploy
pnpm analytics:migrate
pnpm --filter @nibleaf/usage test
pnpm --filter @nibleaf/clickhouse test

امنح قارئ التحليلات صلاحية SELECT على الحقائق والإسقاطات وحالة التسوية وإثبات التغطية وعلامات الحذف، وامنح الكاتب صلاحيات الإدخال والحذف اللازمة للتسوية وحذف الخصوصية. يجب أن يبقى ClickHouse اختياريًا؛ لا ينبغي أن يوقف تعطله تحرير الوثائق أو عرضها، وتبقى الملخصات جزئية أو غير متاحة بصدق.

التصدير والتكامل المستقبلي

تشتق إجراءات الملخص والاستحقاقات المؤسسة من هوية موثوقة وعضوية المشروع. ويتطلب التصدير دور المالك أو المدير. تعيد الطلبات العابرة للمستأجر استجابة «المشروع غير موجود» المعتادة.

يستقبل UsageBillingProvider مستقبلًا المجاميع النهائية فقط. تقابل مفاتيح Polar المقترحة مفاتيح Nibleaf بالبادئة nibleaf_ وبجمع الكمية. هذا توثيق فقط؛ لا ينشئ إعدادًا أو اشتراكًا أو دفعًا لدى Polar.

tenantId, meterKey, periodStart, periodEndExclusive,
quantity, reconciliationId

تُخزّن كمية UsageProviderCheckpoint في Postgres بالنوع numeric(38,0) وتبقى سلسلة معيارية في حدود المزود والواجهة. ينشئ ترحيل ClickHouse رقم 3 غير المنشور كمية usage_hourly بالنوع Decimal(38,0)، بينما تبقى كمية usage_events بالنوع Int64، وبذلك لا تضيق التجميعات عندما تشترك عدة حقائق قصوى في ساعة واحدة.

حذف الخصوصية والتراجع

يضع الحذف أولًا سياجًا في Postgres تحت قفل صف المؤسسة نفسه المستخدم لإنشاء إيصالات الإدخال. تُرفض الدفعات الجديدة، ويُسمح للدفعات المعلقة الموجودة بالاكتمال، ويعيد الحذف تعارضًا قابلًا للمحاولة حتى تصريفها. بعدها يكتب علامة الحذف ويحذف الحقائق والإسقاطات وحالة التسوية وإثبات التغطية ويطابِر حذف البحث ويحوّل نقاط التحقق إلى deletion_pending. ويستخدم حذف الحساب في Better Auth المسار نفسه بدل حذف المؤسسة مباشرة. تستبعد الاستعلامات والعامل علامتي حذف الاستخدام والتحليلات، وتُرفض أحداث التحليلات العادية وصفوف عبارات البحث الحساسة بعد وضع العلامة. ويغلق قفل Postgres الاستشاري المشترك/الحصري السباق بين الإدخال الجاري وسياج الحذف، فلا تعيد مهمة متأخرة إحياء التحليلات الخام. ترشيح علامة ClickHouse حماية إضافية، أما سياج الكتابة الاستشاري في Postgres فهو حد التسلسل لكل إدخال إنتاجي. تُكتب علامة Postgres قبل إدخال ClickHouse، لذلك لا يسمح وضع disabled بتجاوز حذف حقائق قديمة. قد تؤدي العلامة الاحتياطية إلى محاولة حذف آمنة، ولا تؤدي إلى ادعاء خاطئ بعدم وجود حقائق. يبقى التصدير المقبول لدى مزود خارجي التزام تسوية منفصلًا.

للتراجع: عطّل ANALYTICS_MODE عند تعطل ClickHouse، وأوقف الخطة لسحب الاستحقاقات؛ فالحدود إرشادية أصلًا. أنهِ نقاط التحقق واحفظ علامات الحذف قبل إسقاط جداول التغطية والحالة والإسقاطات والحقائق ثم العلامات. أزل جداول Postgres بترتيب المراجع بعد إرجاع المستهلكين. لا يحذف تراجع وقت التشغيل حقائق الاستخدام، لكن تراجع المخطط الطارئ يحذفها، لذلك احفظ الدليل المطلوب أولًا.

لا ينفذ Prisma ترحيلات عكسية تلقائيًا، ولا يكتب rollback.sql مباشرةً في جدول Prisma الخاص _prisma_migrations. إذا نجح الترحيل الأصلي، انسخ عبارات التراجع المراجعة إلى ترحيل تقدمي جديد ذي طابع زمني لاحق ضمن إصدار التراجع، ثم شغّل pnpm db:deploy كي يسجل Prisma الترحيلين بصورة طبيعية. لا تضف ترحيل التراجع المولّد إلى إصدار الميزة نفسه. أما إذا فشل الترحيل الأصلي، فبعد عكس التطبيق الجزئي استخدم الأمر المدعوم التالي، مع استبدال الاسم باسم مجلد الدمج النهائي عند تغيّره:

pnpm --filter @nibleaf/database exec prisma migrate resolve --rolled-back 20260823210000_usage_metering

لا تستخدم --rolled-back مع ترحيل ناجح؛ أعاد الاختبار الحقيقي خطأ Prisma P3012 لهذه المحاولة، ثم نجح عند نشر العبارات كترحيل تقدمي جديد: أزيلت جداول الاستخدام الثمانية، وبقيت المؤسسة التجريبية، وسُجل الترحيلان كمكتملين.

مشغل ترحيل ClickHouse تقدمي فقط؛ بعد حفظ الدليل المطلوب أسقط صراحةً جداول usage_reconciliation_coverage ثم usage_reconciliation_state ثم usage_hourly ثم usage_events وأخيرًا usage_deletion_tombstones. لا تنفذ أي تراجع مع بقاء مستهلكي الاستخدام عاملين.

DROP TABLE IF EXISTS usage_reconciliation_coverage;
DROP TABLE IF EXISTS usage_reconciliation_state;
DROP TABLE IF EXISTS usage_hourly;
DROP TABLE IF EXISTS usage_events;
DROP TABLE IF EXISTS usage_deletion_tombstones;
DROP TABLE IF EXISTS analytics_deletion_tombstones;

البحث الحالي

رُوجع التصميم مقابل صفحات Mintlify العامة في 2026-08-23. تفصل Mintlify حاليًا المقاعد واستحقاقات الميزات عن أرصدة الذكاء الاصطناعي الشهرية، وتعرض تحليلات الزيارات والبحث والمساعد مع تأخير قصير وتصدير حسب الفترة. أخذ Nibleaf مفاهيم العرض فقط، لا الحدود التجارية ولا تصدير المحادثات الخام. راجع الأسعار وتوثيق التحليلات وواجهة تحليلات البحث.