حزمة الحل

معرّف المخطط: solution-package@1 المخطط القابل للقراءة آليًا: solution-package.schema.json

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

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

الشكل

الحزمة كائن JSON يضم هذه الأعضاء:

الحقل	النوع	مطلوب	ملاحظات
formatVersion	integer	نعم	إصدار صيغة الحزمة. وهو حاليًا 1.
publisherName	string	نعم	الاسم المعروض للناشر المالك.
publisherPrefix	string	نعم	بادئة الناشر القصيرة بأحرف صغيرة (مثل par). ويُعاد إنشاؤها عند الاستيراد إن لم تكن موجودة في المستأجر الهدف.
solutionName	string	نعم	اسم الحل.
version	string	نعم	إصدار دلالي بصيغة major.minor.patch (مثل 1.0.0).
description	string | null	لا	وصف اختياري للحل.
requires	مصفوفة أو null	لا	الحلول التي بُني عليها هذا الحل: { solutionName, minVersion? }. تُفحص في البيئة الهدف قبل كتابة أي شيء؛ غياب أحدها أو قِدمه يرفض الاستيراد.
components	array	نعم	البيان: مدخل واحد لكل عنصر (النوع + الاسم المنطقي).
modelComponents	object	نعم	التعريفات المرجعية المضمَّنة، مجمَّعة حسب النوع.
customApps	array | null	لا	بيانات التطبيقات المخصصة المضمَّنة. وهي اختيارية كي تبقى الحزم المُنتَجة قبل وجود التطبيقات المخصصة صالحة؛ ويجري التحقق من كل عنصر إضافيًا مقابل custom-app-manifest@1 عند التجسيد.
webResources	array | null	لا	موارد الويب المضمَّنة (القسم 6.15): ملفات تطبيق مخزَّنة في قاعدة البيانات، ويحمل كل منها محتواه content (نص UTF-8 للأنواع النصية، وBase64 للثنائية). وهي اختيارية كي تبقى الحزم الأقدم صالحة؛ ويُعاد التحقق من بيانات كل عنصر الوصفية مقابل web-resource-manifest@1 ويُفحص تجزئة محتواه عند التجسيد.
customControls	array | null	لا	عناصر تحكّم مخصّصة مضمَّنة (§28)، يحمل كل منها أرشيف بنائه كاملًا مرمَّزًا بـ Base64، فينتقل كود العنصر مع الحل بدل جلبه من مضيف خارجي. ويُتحقق من مانيفست كل عنصر إضافةً إلى ذلك مقابل custom-control-manifest@1 عند التحقيق، ومن أرشيفه مقابل contentHash المعلن — وهي اللحظة التي يثبت فيها أن الكود الذي رُوجع هو الكود الذي يعمل.

عنصر البيان (components[])

الحقل	النوع	مطلوب	ملاحظات
componentType	string	نعم	واحد من Entity، Form، View، App، CustomApp، CustomControl، Process، Report، WebResource، PolicyDefinition، SecurityRole، SavedQuery، Dashboard، BusinessRule، Script. (App هو خريطة تنقّل تطبيق مبني على النموذج، وCustomApp تطبيق React مكتوب يدويًا.)
logicalName	string	نعم	مسبوق ببادئة الناشر؛ بأحرف صغيرة، ويسمح بـ _ و. و/ و- لأسماء موارد الويب الشبيهة بالمسارات (مثل par_invoice، par_/dashboard/app.js).
componentReferenceId	string | null	لا	معرّف العنصر ضمن نظامه الفرعي، إن وُجد.

التعريفات المضمَّنة (modelComponents)

كائن يضم مصفوفات من مدخلات تعريف العناصر — entities وforms وviews وpluginSteps، إضافةً إلى apps الاختيارية (تطبيقات Model-Driven Apps). ويحمل الترتيب دلالة الاعتماديات: تُجسَّد الجداول أولًا، ثم النماذج والعروض وخطوات الإضافة، ثم التطبيقات (التي يشير تنقّلها إلى الجداول بالاسم المنطقي). وapps اختيارية كي تبقى الحزمة المُنتَجة قبل أن تنتقل التطبيقات صالحة وقابلة للاستيراد.

seedData (اختيارية) هي القائمة الوحيدة التي مدخلاتها صفوف لا تعريفات: وثيقة seed-data@1 واحدة لكل جدول — الاسم المنطقي للجدول في الخانتين logicalName وentity — تحمل الصفوف التي أعادها عرض البيانات الأولية للجدول عند التصدير. يجسّدها الاستيراد آخر كل شيء ويدرج أو يحدّث كل صف بحسب id عبر مسار كتابة السجلات المعتاد، كاتبًا الأعمدة التي يحملها الصف فقط ودون حذف أي شيء؛ والصف الذي يرفضه الهدف يُتخطى ويُسمّى في تفاصيل حالة الاستيراد. انظر شحن البيانات الأولية مع الحل.

الحقل	النوع	مطلوب	ملاحظات
logicalName	string	نعم	الاسم المنطقي للعنصر.
entity	string	نعم	الاسم المنطقي للجدول المالك (وهو اسم الجدول نفسه، في حالة الجدول).
json	string	نعم	تعريف العنصر المرجعي بصيغة JSON (تعريف جدول أو نموذج أو عرض أو غلاف خطوة إضافة — ويجري التحقق من كل منها مقابل مخططه الخاص عند التجسيد).
isDefault	boolean	لا	للنماذج والعروض: ما إذا كان هذا هو الافتراضي للجدول.

مسار تحقق واحد. لا يُعاد التحقق من الحمولة json لكل عنصر مضمَّن عبر مخطط الحزمة هذا؛ بل يجري التحقق من كل منها مقابل مخططه المنشور الخاص (مثل تعريف الجدول المبني على البيانات، والنموذج، والعرض، وخطوة الإضافة) عند تجسيده — وهو الفحص نفسه الذي يجريه الحفظ في المصمّم.

مثال

{
  "formatVersion": 1,
  "publisherName": "Parsware",
  "publisherPrefix": "par",
  "solutionName": "Sales",
  "version": "1.0.0",
  "description": "Core sales entities.",
  "components": [
    { "componentType": "Entity", "logicalName": "par_invoice" },
    { "componentType": "Form", "logicalName": "par_invoice_main" }
  ],
  "modelComponents": {
    "entities": [
      { "logicalName": "par_invoice", "entity": "par_invoice", "json": "{ ...entity definition... }" }
    ],
    "forms": [
      { "logicalName": "par_invoice_main", "entity": "par_invoice", "json": "{ ...form definition... }", "isDefault": true }
    ],
    "views": [],
    "pluginSteps": []
  }
}

كيف تُستخدم

• التصدير يقرأ البيان والتعريفات الحقيقية من بيئة مصدر، منتجًا حزمة عند GET /solutions/{id}/export?sourceEnvironmentId=….
• الاستيراد يتحقق من الحزمة مقابل هذا المخطط، ويحلّ الاعتماديات (فكل نموذج أو عرض أو خطوة إضافة يجب أن يستهدف جدولًا مضمَّنًا في الحزمة)، ويجتاز أي بوابة موافقة، ثم يجسّد العناصر داخل المخطط المعزول للبيئة الهدف — عند POST /solution-imports.

الإصدارات

تُحفظ إصدارات المخططات القديمة إلى جانب الجديدة كي تستمر الحلول المنشورة سلفًا في اجتياز التحقق بعد تطور المخطط. وعند الحاجة إلى تغيير كاسر، يُنشر إصدار جديد (solution-package@2) بدلًا من تعديل هذا الإصدار؛ وتحمل الحزمة formatVersion الخاص بها كي يتمكن خط الأنابيب من رفض إصدار لا يدعمه.