عناصر واجهة مخصصة

ستتوفر الأدوات المخصصة بدءًا من الإصدار SKOOR 10.0.0.

تُوسّع الأدوات المخصصة (Custom Widgets) منظومة التصور المرئي في SKOOR من خلال السماح للمطورين ببناء مكونات واجهة مستخدم تفاعلية ومصممة خصيصًا تعمل بأمان داخل لوحات معلومات SKOOR. وتجمع هذه الأدوات بين مرونة أطر عمل الويب الحديثة (مثل React أو Vue أو Vanilla JS العادية) وأدوات البناء الحديثة (مثل Vite أو Webpack)، إلى جانب مسارات البيانات المُدارة في SKOOR ومعايير الأمان الصارمة.

دليل البدء السريع

لاستخدام الأدوات المخصصة، ستحتاج إلى بيانات اعتماد سجل SKOOR (SKOOR Registry). تواصل مع support@skoor.com لطلبها.

استخدم الحزمة @skoor/create-custom-widget لإنشاء الهيكل الأولي لمشروع أداة مخصصة جديد في SKOOR بالبنية والتبعيات الموصى بها.

  1. افتح صفحة الحزمة: https://www.npmjs.com/package/@skoor/create-custom-widget

  2. أنشئ هيكل مشروع الأداة: اتبع تعليمات الحزمة لإنشاء مساحة عمل جديدة لأداة مخصصة.

  3. قم بالبناء والاختبار والنشر: نفّذ الأداة، وتحقق من صحتها محليًا، ثم انشرها إلى سجل حزم SKOOR (SKOOR Package Registry) ضمن نطاق العميل المخصص لك.

آلية عمل الأدوات المخصصة

skoor-custom-widget-architecture.svg

تعمل الأدوات المخصصة كحزم معزولة ومستقلة بذاتها يتم توزيعها وإدارتها عبر SKOOR Package Registry المركزي (registry.skoor.com).

  • نقطة الدخول (main): تحدد كل حزمة أداة ملف HTML كنقطة دخول main في package.json. ويتم تحميل جميع الأصول الثابتة المطلوبة (البرامج النصية والأنماط والصور) مباشرةً من السجل.

  • التنفيذ المعزول: تُنفّذ الأدوات داخل إطارات IFRAME معزولة من خلال أصل مخصص وسياسة أمان محتوى (CSP) مقيدة. ويضمن ذلك فصل المستأجرين والأمان وضوابط الحدود الصارمة.

  • طرق الإنشاء: يمكن إنشاء الأدوات المخصصة إما يدويًا بواسطة المهندسين باستخدام أي سير عمل تطوير محلي حديث (مثل Vite أو Webpack أو Vanilla JS) أو توليدها عبر الذكاء الاصطناعي لإنشاء الهياكل الأولية للوحات المعلومات والمكونات الوظيفية بسرعة.

بنية الحزمة واستعلامات البيانات

لضمان بقائها قابلة للنقل بالكامل وخاضعة للتحكم في الإصدارات، تقوم الأدوات المخصصة بتضمين تعريفات البيانات المطلوبة مباشرةً داخل الحزمة ضمن كتلة التكوين skoor:

  • الاستعلامات المضمنة: تتضمن الحزم استعلامات قاعدة البيانات المطلوبة ضمن الخاصية skoor.dataQueryPackage، التي تشير إلى ملف JSON للاستعلامات المُصدّرة. استخدم أداة التصدير في خادم SKOOR MCP لتصدير مجموعة استعلامات مخصصة؛ حيث يتضمن التصدير تلقائيًا التبعيات المطلوبة.

  • جسر لوحة المعلومات (@skoor/dashboard-bridge): تتواصل الأدوات مع منصة SKOOR الأساسية حصريًا عبر مكتبة @skoor/dashboard-bridge الرسمية. يجرّد هذا الجسر الاتصال غير المتزامن (عبر postMessage وPenpal) مما يتيح للأدوات القيام بما يلي:

    • جلب البيانات ديناميكيًا باستخدام dataQuerySelect(...) أو dataSourceSelect(...).

    • قراءة عوامل التصفية العامة للوحة المعلومات وتحديثها (getFilters()، setFilters(...)).

    • مزامنة أنماط المضيف ومتغيرات السمة وعائلات الخطوط وارتفاعات المحتوى تلقائيًا عبر setup().

مثال على تكوين package.json لأداة مخصصة (منشورة ضمن نطاق عميل، مثل @customer-scope/custom-metric-widget):

{
  "name": "@customer-scope/custom-metric-widget",
  "version": "1.0.0",
  "main": "dist/index.html",
  "skoor": {
    "dataQueryPackage": "./data/data-queries.json"
  }
}

التطوير والتكامل مع خادم MCP والنشر

لتطوير الأدوات المخصصة ونشرها بكفاءة، يمكنك ربط مساعدي البرمجة بالذكاء الاصطناعي لديك مباشرةً بنسخة SKOOR الخاصة بك باستخدام خادم بروتوكول سياق النموذج (MCP) المدمج.

استخدام خادم SKOOR MCP (الاسترجاع والإنشاء والتحديث والتصدير)

يتيح خادم SKOOR MCP لعملاء نماذج اللغة الكبيرة (LLM) الخارجيين (مثل Cursor أو Cline) استرجاع وإنشاء وتحرير وتصدير تعريفات الجداول واستعلامات البيانات مباشرةً من نسخة SKOOR الخاصة بك:

  • الاسترجاع: الاستعلام عن مخططات قواعد البيانات وبنى الجداول وتعريفات استعلامات البيانات الموجودة لفهم نماذج البيانات المتاحة.

  • الإنشاء: توليد استعلامات بيانات جديدة تلقائيًا وبناء تعريفات الأدوات استنادًا إلى مواصفاتك الدقيقة.

  • التحديث / التحرير: تحسين الاستعلامات بشكل تكراري، أو ضبط التجميعات، أو تعديل المعاملات مباشرةً داخل بيئة التطوير الخاصة بك مع التحقق الكامل من المخطط.

  • التصدير: تصدير حزم استعلامات البيانات إلى تنسيق JSON باستخدام أداة التصدير في خادم MCP. ضع الاستعلامات الخاصة بالأداة في مجموعة مخصصة، وقم بتصدير تلك المجموعة، وسيتضمن التصدير تلقائيًا التبعيات المطلوبة.

قم بتكوين عميل MCP الخاص بك (على سبيل المثال، في إعدادات مشروعك أو الإعدادات العامة) باستخدام قالب تكوين HTTP التالي:

{
  "servers": {
    "skoor-mcp": {
      "type": "http",
      "url": "https://<your-skoor-instance>/skoor-webservice/mcp",
      "headers": {
        "Authorization": "Basic <your-base64-encoded-credentials>"
      }
    }
  },
  "inputs": []
}

إعداد السجل والنشر

  1. تكوين السجل: أنشئ ملف .npmrc في جذر مشروعك يحتوي على نقطة نهاية سجل SKOOR الخاص:

    registry=https://registry.skoor.com
  2. المصادقة: سجّل الدخول إلى السجل باستخدام بيانات الاعتماد المقدمة من SKOOR:

    npm login --registry=https://registry.skoor.com
  3. نطاقات العملاء: يجب دائمًا نشر الحزم ضمن نطاق العميل المخصص لك (على سبيل المثال، @customer-scope/my-widget).

الأمان وقيود الشبكة وسياسة أمان المحتوى (CSP)

لحماية سيادة بيانات المؤسسة ومنع تسرب البيانات غير المصرح به إلى جهات خارجية، تفرض SKOOR سياسات أمان صارمة على الأدوات المخصصة:

  • العزل الافتراضي: يُحظر الاتصال بالشبكات الخارجية من داخل الأداة حظرًا تامًا ويُمنع افتراضيًا عبر سياسة أمان محتوى (CSP) متحفظة.

  • استثناءات CSP: إذا كانت الأداة تتطلب صراحةً الاتصال بنقاط نهاية خارجية (مثل واجهات برمجة التطبيقات العامة أو مستودعات الجهات الخارجية)، فيمكن التصريح عن الاستثناءات ضمن قسم skoor.csp في package.json:

{
  "skoor": {
    "csp": {
      "connect-src": [
        "https://api.external-service.com"
      ]
    }
  }
}
  • إقرار المستخدم: عندما تطلب الأداة أصول شبكة إضافية عبر تكوين CSP الخاص بها، تعرض المنصة للمسؤولين أو المستخدمين مربع حوار للتأكيد من أجل التفويض الصريح للوصول إلى البيانات الصادرة.

دورة الحياة: التثبيت والنشر في لوحة المعلومات

يتبع نشر الأداة المخصصة واستخدامها دورة حياة إدارية وتشغيلية واضحة:

  1. النشر: يقوم المطورون ببناء الحزمة ذات الإصدار المحدد ونشرها إلى سجل حزم SKOOR الخاص (registry.skoor.com).

  2. التثبيت: ينتقل المسؤولون إلى SKOOR Settings، ويحددون قسم إدارة Custom Widgets، ويثبتون الحزمة المطلوبة من السجل الخاص.

  3. التكامل مع لوحة المعلومات: بمجرد التثبيت، تصبح الأداة المخصصة متاحة في WYSIWYG Dashboard Builder، حيث يمكن للمستخدمين وضعها في لوحات المعلومات، وتكوين معاملات العرض الخاصة بها، وربطها بعوامل التصفية العامة للوحة المعلومات.