بستهٔ راه‌حل

شناسهٔ شِما: solution-package@1 شِمای قابل‌خواندن توسط ماشین: solution-package.schema.json

بازنمایی مرجع و متنی یک راه‌حل خروجی‌گرفته‌شده. بستهٔ راه‌حل واحد ارتقای میان محیط‌هاست: با خروجی گرفتن از یک راه‌حل در محیط مبدأ تولید و با وارد کردن آن در محیط مقصد مصرف می‌شود. بسته خودتوصیف است — هم مانیفست (اینکه راه‌حل چه اجزایی را دربردارد) و هم تعریف‌های مرجعِ جاسازی‌شدهٔ هر جزء Model-Driven را حمل می‌کند، تا یک وارد کردن، موجودیت‌ها، فرم‌ها، نماها و گام‌های افزونهٔ واقعی را از نو بسازد، نه ارجاع‌هایی معلق.

اعتبارسنجی برای هر مبدأیی به شکل یکسان اعمال می‌شود: بسته‌ای که ابزار خروجی گرفتن ساخته، یا یک فراخوانی 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	خیر	کنترل‌های سفارشی نهفته (§۲۸)، که هر یک تمام بایگانی ساختش را با کدگذاری 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 اختیاری است تا بسته‌ای که پیش از سفر کردن برنامه‌ها تولید شده همچنان اعتبارسنجی و وارد شود.

seedData (اختیاری) تنها فهرستی است که ورودی‌هایش رکورد هستند نه تعریف: به ازای هر جدول یک سند seed-data@1 — با نام منطقی جدول در هر دو جایگاه logicalName و entity — که رکوردهایی را نگه می‌دارد که نمای داده‌های اولیهٔ جدول هنگام خروجی گرفتن برگردانده است. درون‌ریزی آن را پس از همه‌چیز می‌سازد و هر رکورد را بر اساس id از مسیر عادی نوشتن رکورد درج یا به‌روز می‌کند، فقط ستون‌هایی را که رکورد حمل می‌کند می‌نویسد و هرگز چیزی حذف نمی‌کند؛ رکوردی که مقصد رد کند رد می‌شود و در جزئیات وضعیت درون‌ریزی نام برده می‌شود. ببینید ارسال داده‌های اولیه همراه راه‌حل.

فیلد	نوع	اجباری	یادداشت‌ها
logicalName	string	بله	نام منطقی جزء.
entity	string	بله	نام منطقی موجودیت مالک (برای یک موجودیت، نام خودش).
json	string	بله	تعریف JSON مرجع جزء (یک تعریف موجودیت، فرم، نما، یا پوشش گام افزونه — هرکدام هنگام ساخت واقعی در برابر شِمای خودش اعتبارسنجی می‌شود).
isDefault	boolean	خیر	برای فرم‌ها/نماها: اینکه آیا این پیش‌فرض موجودیت است.

یک مسیر اعتبارسنجی. بار json هر جزء جاسازی‌شده توسط این شِمای بسته دوباره اعتبارسنجی نمی‌شود؛ در عوض هرکدام همچنان که ساخته می‌شود در برابر شِمای منتشرشدهٔ خودش اعتبارسنجی می‌گردد (برای نمونه تعریف موجودیت Model-Driven، فرم، نما، گام افزونه) — همان وارسی‌ای که یک ذخیرهٔ طراح انجام می‌دهد.

نمونه

{
  "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 خودش را حمل می‌کند تا خط لوله بتواند نسخه‌ای را که پشتیبانی نمی‌کند رد کند.