محرك التكاملات

دليل تكاملات Nibleaf هو طبقة اكتشاف ودورة حياة للاتصالات مع المزوّدين الخارجيين. وهو لا يستبدل نماذج المجالات الخاصة بكل مزوّد. تبقى إعدادات Git والتحليلات وبنية النسخة هي المصدر المعتمد في وحداتها الحالية، بينما تستخدم اتصالات Webhook الخاصة بالمشروع دورة الحياة المشتركة والمشفرة.

الملكية ودليل المزوّدين

تسجيل الدخول عبر Google OAuth جزء من مصادقة Nibleaf، ولذلك يقع خارج دليل تكاملات المشروع. تملك الإضافات مفاتيح ميزات المنتج، ويملك الاستخدام القياس، وتملك التكاملات الاتصالات الخارجية. لا يعالج هذا المحرك المدفوعات.

يبقى المزوّد المخطط له غير متاح ولا يعلن أي عملية تغيير حتى يصبح مدعومًا فعليًا. لا تعني إضافة سجل إلى الدليل أن الاتصال يعمل.

العقد العام

تحتوي كل استجابة على بيانات الفئة والقدرات الثابتة وملخص اتصال اختياري. ملخص الاتصال مميّز بحسب المزوّد ومقيّد بقائمة سماح؛ ويعرض الحالة والصحة والمراجعة والإعداد الآمن، ولا يعرض عن بيانات الاعتماد سوى credential.configured. لا يظهر السر أو بصمته أو جسم استجابة المزوّد أو إعداد عشوائي.

تستخدم إجراءات المجال الأفعال list وget وcreate وupdate وactivate وdeactivate وverify وdelete. تنفرد جلسة لوحة التحكم بإنشاء بيانات الاعتماد واستبدالها. يتطلب اختبار Slack أو Zapier المرئي تأكيدًا صريحًا من اللوحة، بينما تحقق Discord وGitHub غير مرئي.

يجب أن يحمل مفتاح API النطاق المحدد المطلوب: integrations:read أو integrations:write أو integrations:verify أو integrations:delete. لا يمنح النطاق القديم * أي صلاحية للتكاملات. يعيد كل إجراء تحميل المفتاح ويتحقق من عدم إلغائه أو انتهاء صلاحيته ويربطه بالمشروع ويطبق التفويض بنفسه. تُعاد محاولة الوصول بين المستأجرين بغلاف «غير موجود» المعتاد.

صادرات الإجراءات الثابتة هي listProjectIntegrations و getProjectIntegration وcreateProjectIntegration و updateProjectIntegration وactivateProjectIntegration و deactivateProjectIntegration وverifyProjectIntegration و createIntegrationDeleteConfirmation وdeleteProjectIntegration. وحدود الطلبات المشتركة هي integrationProviderIdSchema و configurableIntegrationProviderIdSchema وcreateProjectIntegrationBody و updateProjectIntegrationBody وintegrationRevisionBody و verifyProjectIntegrationBody وcreateIntegrationDeleteConfirmationBody و deleteProjectIntegrationBody وintegrationConnectionSummarySchema.

يمكن للعملاء الاعتماد على رموز أخطاء دورة الحياة الثابتة integration:not_found وintegration:provider_unsupported و integration:provider_unavailable وintegration:already_connected و integration:invalid_configuration وintegration:credentials_required و integration:credentials_invalid وintegration:inactive و integration:verification_failed وintegration:rate_limited و integration:idempotency_conflict وintegration:revision_conflict و integration:external_confirmation_required و integration:confirmation_invalid وintegration:confirmation_expired و integration:confirmation_consumed. تُنقّح أعطال قاعدة البيانات أو المزوّد غير المعروفة عند حد الخطأ المعتاد ولا يعاد تصنيفها كإحدى حالات العمل هذه.

يجوز لـMCP عرض list وget وactivate وdeactivate والتحقق غير المرئي والحذف المؤكد فقط، وكلها بلا بيانات اعتماد. لا تقبل أدوات MCP الأسرار ولا تعيدها أو تخزنها. تصدر جلسة Better Auth في لوحة التحكم تأكيد حذف أحادي الاستخدام يمكن ربطه بمفتاح API والمشروع والمزوّد والاتصال والمراجعة. لا يستطيع MCP إصدار التأكيد أو إرسال اختبار مرئي.

الأسرار وإعادة الطلب والتدقيق

اضبط INTEGRATION_CREDENTIAL_ENCRYPTION_KEY مستقلًا يتكون من 32 بايت بترميز base64. يجب ألا يعاد استخدام مفتاح Git ضمنيًا. تستخدم الأسرار أغلفة AES-256-GCM ذات إصدار. تُفصل أغراض بصمات HMAC لمفاتيح منع التكرار ومقارنة الطلبات والتأكيدات. تستخدم الكتابة المفتاح الحالي، وتحاول القراءة أيضًا المفاتيح في INTEGRATION_CREDENTIAL_PREVIOUS_KEYS خلال نافذة التدوير.

يحتفظ سجل منع التكرار بنتيجة منقحة وصارمة حتى انتهاء مدة الاحتفاظ. تعيد إعادة مفتاح قديم نتيجته الأصلية حتى بعد تغييرات لاحقة أو حذف الاتصال. يؤدي استخدام المفتاح مع طلب مختلف إلى integration:idempotency_conflict. لا تُخزّن المفاتيح الخام أو أجسام الطلبات الحاوية للأسرار أو أجسام استجابات المزوّد.

تستخدم بصمات الطلب تسلسلًا معياريًا صريحًا ومميّزًا بحسب المزوّد، وتستبعد مفتاح منع التكرار الذي تُحسب بصمته على حدة. تعيد طلبات لوحة التحكم وMCP المتكافئة النتيجة نفسها مهما اختلف ترتيب خصائص الكائن، بينما يؤدي تغيير المزوّد أو المراجعة أو الإعداد أو بيانات الاعتماد إلى تعارض.

تستخدم مراجعة الاتصال مقارنة وتبديلًا ذريين. بعد الاتصال الخارجي، تُحفظ حالة التسليم النهائية وصحة الاتصال ومراجعته وسجل التدقيق في معاملة واحدة. تُسجّل المنافسة مع تحديث آخر وتُعاد بالرمز integration:revision_conflict.

تستخدم سجلات تسليم التحقق مهلة تشغيل محدودة. يمكن استعادة تحقق Discord غير المرئي القديم بأمان. أما اختبار Slack أو Zapier القديم فيُنهى بالنتيجة المنقحة integration:provider_unavailable من دون إعادة إرسال رسالة خارجية، وتتطلب إعادته تأكيدًا جديدًا من لوحة التحكم ومفتاح منع تكرار جديدًا. لا يدّعي Nibleaf ضمان تسليم Webhook الخارجي مرة واحدة بالضبط.

يحتوي سجل التدقيق على projectId وproviderId ثابتين ولا يعتمد على علاقة الاتصال المتغيرة. يمسح حذف الاتصال العلاقة الاختيارية، لكنه يحتفظ بهوية المزوّد وسجل دورة الحياة الخالي من الأسرار. تحتفظ تأكيدات الحذف المستهلكة أيضًا بسجل لا يحوي إلا البصمة بعد مسح علاقة الاتصال. تُستهلك التأكيدات عبر مطالبة ذرية واحدة، لذلك تعيد المحاولات اللاحقة والطلبات المتزامنة الخاسرة integration:confirmation_consumed بعد الحذف. تبقى سجلات التأكيد المستهلكة طوال مدة الاحتفاظ المضبوطة، ثم يحذفها تنظيف محدود على مستوى المشروع. وتُحذف التحديات المنتهية غير المستهلكة عند إنشاء التحدي التالي.

تدوير المفتاح والتراجع

1. أنشئ مفتاح base64 مستقلًا جديدًا من 32 بايت. اجعله قيمة INTEGRATION_CREDENTIAL_ENCRYPTION_KEY وأضف القديم إلى INTEGRATION_CREDENTIAL_PREVIOUS_KEYS.
2. انشر كل نسخ API معًا. تستخدم الكتابات المفتاح الجديد وتظل البيانات القديمة وسجلات منع التكرار والتأكيدات مقروءة.
3. أعد ربط كل Webhook يملكه المشروع لتشفيره بالمفتاح الجديد. احتفظ بالمفتاح القديم حتى تستبدل كل الأسرار وتنتهي أطول مدة منع تكرار وتأكيد.
4. تحقق من الاتصالات ثم أزل المفتاح القديم. للتراجع خلال النافذة، أعد القديم كمفتاح حالي واحتفظ بالجديد ضمن المفاتيح السابقة.

يملك ترحيل التكاملات عمود ApiKey.expiresAt الاختياري بوصفه متطلب مصادقة مشتركًا، ويعتمد عليه ترحيل مستوى تحكم MCP. للتراجع، ألغِ أولًا أي ترحيل MCP تابع، وأوقف تغييرات التكاملات، واحتفظ بأدلة التدقيق المطلوبة، ثم احذف جداول التكاملات بعكس ترتيب المفاتيح الخارجية. لا تحذف ApiKey.expiresAt إلا عند التراجع عن التكاملات قبل الترحيل التابع وبعد التأكد من عدم اعتماد مستهلك آخر عليه. أعد إصدار التطبيق السابق في الخطوة الأخيرة، ولا تحذف البيانات المشفرة قبل اكتمال قرار التراجع.

يوثّق دليل ترحيل الإصدار المجمع ترتيب اعتماد الإصدار كاملًا والفرق بين التراجع في وقت التشغيل والتراجع الهدّام للمخطط.

إضافة مزوّد

1. أضف معرّف المزوّد والبيان والقدرات والتوافر الحقيقي وفرعًا صريحًا في اتحاد الإعداد العام ومدقق إعادة النتيجة.
2. حدد هل يبقى نموذج مجال حالي هو المصدر المعتمد، أم يدير المشغّل المزوّد، أم تناسبه دورة حياة المشروع المشتركة.
3. أضف حدًا خاصًا بالمزوّد. فضّل الحزمة الرسمية، ثم Got عند غياب حزمة مناسبة.
4. عرّف حقول الأسرار للكتابة فقط، وآثار التحقق المرئية، وحدود توقيع Webhook ومنع الإعادة، ورموز الأخطاء الآمنة، وبيانات التدقيق المدرجة في قائمة السماح.
5. أضف اختبارات المستأجر والنطاق المحدد والتنقيح والمراجعة الذرية ومنع التكرار وتدوير المفتاح وRTL والجوال وفشل المزوّد قبل إعلان دعم التغيير.