# تشغيل قياس الاستخدام > إعداد استخدام Nibleaf المحايد عن مزود الفوترة وتسويته والاحتفاظ به وتصديره وحذفه والتراجع عنه دون تفعيل المدفوعات. يفصل 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` المحايدة والنشطة دون اختراع حدود تجارية. تُفحص حالة الخطة وانتهاؤها وأعلام تفعيل الخطة والمقياس قبل منح الاستحقاق. ولا تُستخدم بيانات المؤسسة القديمة إلا كاحتياط محدود عند غياب الربط العلائقي؛ وتبقى البيانات التالفة أو الكبيرة مجهولة. ## التطبيق والتحقق ```bash pnpm db:deploy pnpm analytics:migrate pnpm --filter @nibleaf/usage test pnpm --filter @nibleaf/clickhouse test ``` امنح قارئ التحليلات صلاحية `SELECT` على الحقائق والإسقاطات وحالة التسوية وإثبات التغطية وعلامات الحذف، وامنح الكاتب صلاحيات الإدخال والحذف اللازمة للتسوية وحذف الخصوصية. يجب أن يبقى ClickHouse اختياريًا؛ لا ينبغي أن يوقف تعطله تحرير الوثائق أو عرضها، وتبقى الملخصات جزئية أو غير متاحة بصدق. ## التصدير والتكامل المستقبلي تشتق إجراءات الملخص والاستحقاقات المؤسسة من هوية موثوقة وعضوية المشروع. ويتطلب التصدير دور المالك أو المدير. تعيد الطلبات العابرة للمستأجر استجابة «المشروع غير موجود» المعتادة. يستقبل `UsageBillingProvider` مستقبلًا المجاميع النهائية فقط. تقابل مفاتيح Polar المقترحة مفاتيح Nibleaf بالبادئة `nibleaf_` وبجمع الكمية. هذا توثيق فقط؛ لا ينشئ إعدادًا أو اشتراكًا أو دفعًا لدى Polar. ```text 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 الترحيلين بصورة طبيعية. لا تضف ترحيل التراجع المولّد إلى إصدار الميزة نفسه. أما إذا فشل الترحيل الأصلي، فبعد عكس التطبيق الجزئي استخدم الأمر المدعوم التالي، مع استبدال الاسم باسم مجلد الدمج النهائي عند تغيّره: ```bash 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`. لا تنفذ أي تراجع مع بقاء مستهلكي الاستخدام عاملين. ```sql 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 مفاهيم العرض فقط، لا الحدود التجارية ولا تصدير المحادثات الخام. راجع [الأسعار](https://www.mintlify.com/pricing) و[توثيق التحليلات](https://www.mintlify.com/docs/optimize/analytics) و[واجهة تحليلات البحث](https://www.mintlify.com/docs/api/analytics/searches).