تعریف موجودیت Model-Driven

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

بازنمایی مرجع و متنی یک موجودیت در Model-Driven Apps. این همان منبع حقیقتی است که یک موجودیت در برابر آن اعتبارسنجی می‌شود — همان تعریفی که طراح تولید می‌کند، یک فراخوانی API ارسال می‌کند، یک دستیار هوش مصنوعی می‌سازد، و یک وارد کردن راه‌حل حمل می‌کند. اعتبارسنجی برای هر مبدأیی به شکل یکسان اعمال می‌شود، پس فایلی دست‌نویس یا تولیدشده که با این شِما سازگار باشد، وارد کردنش بی‌خطر است.

شکل

یک تعریف، یک شیء JSON با این اعضا است:

فیلد	نوع	اجباری	یادداشت‌ها
logicalName	string	بله	پیشوند ناشر در ابتدا، با snake-case کوچک (مثلاً par_invoice).
displayName	string	بله	برچسب مفرد (مثلاً Invoice).
displayCollectionName	string	بله	برچسب جمع (مثلاً Invoices).
icon	string	خیر	کلید آیکون از مجموعه آیکون‌های گزیدهٔ پلتفرم، که در ناوبری یک برنامه کنار جدول نمایش داده می‌شود (بخش 4.4). برای نشانِ پیش‌فرض آن را حذف کنید.
publisherPrefix	string	بله	پیشوند کوتاه و کوچک (مثلاً par).
primaryField	string	بله	نام منطقی فیلد اصلی (نام)؛ باید در fields بیاید.
primaryImage	string	خیر	نام منطقی تصویر رکورد (بخش ۶.۱۶) — تصویری که کنار رکورد در شبکه‌ها و جستجوهای رکورد نشان داده می‌شود. باید فیلدی از نوع Image در fields را نام ببرد. برای جدولی بدون تصویر، آن را نیاورید.
secondaryField	string | null	خیر	نام منطقی فیلدی که همچون متن ثانویهٔ رکورد نشان داده می‌شود — خط دوم کوچک‌تر زیر نامش، هر جا رکوردها بدون جدول فهرست می‌شوند، مانند تابلوی جستجو (§۶٫۱۳٫۵). باید فیلدی در fields را نام ببرد که نه فیلد اصلی است و نه ستون فایل/تصویر.
hierarchyParentField	string | null	خیر	نام منطقی ارجاعی (Lookup) که این جدول را سلسله‌مراتبی می‌کند — فیلدی که والد هر رکورد را نگه می‌دارد و به همین جدول بازمی‌گردد (دستهٔ والدِ یک دسته، واحد بالادستِ یک واحد). باید فیلدی در fields از نوع Lookup را نام ببرد که targetEntity آن همین جدول باشد. چیزی را اعطا و چیزی را الزام نمی‌کند: جدول تا وقتی نمایی رکوردهایش را تودرتو نکند همچنان به‌صورت جدول رسم می‌شود. کارش این است که سلسله‌مراتبی‌بودن ویژگیِ داده است نه یک نما — سطح بالای نمای درختی پیوند فرزندش را از آن می‌گیرد.
personField	string	null	خیر
constraints	array	خیر	قواعدی که پایگاه‌داده اعمال می‌کند، نه برنامه (پایین‌تر ببینید) — یک ستون یکتا، یا بازه‌ای که نباید با بازهٔ دیگری در همان دامنه هم‌پوشانی داشته باشد.
fields	array	بله	یک یا چند تعریف فیلد (پایین‌تر را ببینید).
relationships	array	خیر	ارتباط‌های یک‌به‌چند که فیلدهای جستجوی رکورد پشتوانهٔ آن‌ها هستند.
isAuditEnabled	boolean	خیر	ممیزی تغییرات را برای موجودیت فعال می‌کند (بخش 6.5). پیش‌فرض false است.
states	array	خیر	وضعیت‌هایی که یک رکورد این جدول می‌تواند در آن باشد (§۶٫۱۴) — چرخهٔ زندگی‌اش. پایین‌تر ببینید. در سندی که پیش از پیدایش وضعیت‌ها نوشته شده نیست، و همین است که واردکننده با آن جدولی را که هیچ ندارد بازمی‌شناسد.
reasons	array	خیر	دلیل‌ها، که هر یک تنها به یک وضعیت تعلق دارد. پایین‌تر ببینید.
statusValueBase	integer	خیر	کف بازه‌ای که گزینه‌های وضعیت و دلیلِ افزودهٔ این جدول از آن شماره می‌گیرند — پایهٔ مقدارِ گزینهٔ ناشر مالک (§۶٫۱۴). فعال/غیرفعالِ کاشته‌شده بیرون آن، روی 0 و 1 می‌نشینند: هر جدولی آن‌ها را دارد و همه‌جا یک معنا دارند، پس به فضای‌نام نیازی ندارند.
nextStatusValue	integer	خیر	نشانهٔ بیشینهٔ وضعیت جدول — مقدار بعدی که خواهد داد. ذخیره می‌شود نه استنتاج از گزینه‌ها، به همان دلیلی که برای یک مجموعه‌گزینه: شمارهٔ گزینهٔ برداشته‌شده بازنشسته می‌شود، و استنتاج دوباره آن را به گزینهٔ تازه می‌دهد در حالی که رکوردها هنوز ممکن است نگهش داشته باشند.

فیلد

فیلد	نوع	اجباری	یادداشت‌ها
logicalName	string	بله	snake-case کوچک.
displayName	string	بله
dataType	string	بله	یکی از Text، MultilineText، Integer، Decimal، Boolean، DateTime، Lookup، PolymorphicLookup، File، Image، OptionSet، State، Reason.
isRequired	boolean	خیر
isPrimary	boolean	خیر	برای تنها فیلد اصلی، مقدار true.
maxLength	integer	خیر	برای Text (۱ تا ۴۰۰۰).
precision, scale	integer	خیر	برای Decimal (scale ≤ precision ≤ 38).
targetEntity	string	مشروط	وقتی dataType برابر Lookup است اجباری است؛ نام منطقی موجودیت ارجاع‌شده.
targetEntities	string[]	مشروط	وقتی dataType برابر PolymorphicLookup است اجباری است؛ جدول‌هایی که یک مقدار می‌تواند به آن‌ها ارجاع دهد، به ترتیب انتخابگر. حداقل دو تا، بدون تکرار.
isAuditExcluded	boolean	خیر	وقتی موجودیت ممیزی می‌شود، فیلد را از ممیزی تغییرات کنار می‌گذارد (بخش 6.5). پیش‌فرض false است.

فیلدهای File / Image به‌صورت یک ستون متنی تأمین می‌شوند که ارجاعی همراه با نام انبار را نگه می‌دارد — recordfile:<id> برای فایلی که در شمای خود محیط می‌ماند، یا objectstore:<key> برای فایلی که آن‌قدر بزرگ بوده که به Object Storage سرریز کرده است. بایت‌ها به‌جای نوشته‌شدن از راه API رکورد، به نقطهٔ پایانی فایلِ همان فیلد بارگذاری می‌شوند و با همان مجوز خود رکورد بازگردانده می‌شوند. اینکه کدام‌یک از دو انبار فایل را نگه می‌دارد با اندازهٔ آن تعیین می‌شود و نه با تنظیمی که سازنده انتخاب کند.

ارتباط

فیلد	نوع	اجباری	یادداشت‌ها
logicalName	string	بله	snake-case کوچک.
type	string	بله	OneToMany.
referencedEntity	string	بله	سمت «یک».
referencingEntity	string	بله	سمت «چند» (که جستجوی رکورد را حمل می‌کند).
lookupField	string	بله	فیلد جستجوی رکورد روی موجودیت ارجاع‌دهنده که پشتوانهٔ ارتباط است.

وضعیت و دلیل

وضعیت جایی است که رکورد در چرخهٔ زندگی‌اش ایستاده؛ دلیل می‌گوید کدام گونه از آن وضعیت است. این‌ها با جدول سفر می‌کنند، چون بخشی از آن‌اند که سازنده طراحی کرده است.

🔴 این‌ها مجموعه‌گزینه نیستند. «فعال» روی یک فاکتور و «فعال» روی یک مخاطب یک گزینه نیستند، و مدل‌کردنشان همچون یک فهرست مشترک باعث می‌شد تغییر نام یکی، دیگری را هم تغییر نام دهد.

وضعیت:

فیلد	نوع	الزامی	یادداشت
value	integer	بله	مقدار ذخیره‌شده، که در گذر از ورود حفظ می‌شود: رکوردهای محیط مبدأ پیشاپیش آن را نگه داشته‌اند، پس Dev و Test باید بر سر معنایش هم‌داستان باشند.
displayName	string	بله	برچسب.
color	string	خیر	رنگی که نشانش با آن کشیده می‌شود.
icon	string	خیر	نگارهٔ روی نشانش.
defaultReason	integer	خیر	اینکه رکوردی که وارد این وضعیت می‌شود کدام دلیل این وضعیت را بگیرد. نبودش یعنی نخستین دلیل، و همین است که این تنظیم را اختیاری می‌کند.

دلیل:

فیلد	نوع	الزامی	یادداشت
state	integer	بله	value وضعیتی که این دلیل به آن تعلق دارد. کلیدش مقدار است نه شناسهٔ سطر، چون مقدار همان چیزی است که رکورد ذخیره می‌کند و از برون‌برد جان به‌در می‌برد.
value	integer	بله	مقدار ذخیره‌شده.
displayName	string	بله	برچسب.
color · icon	string	خیر	مانند وضعیت.

دربرگیرندگی همان نکته است: «برنده» و «بازنده» هر دو دلیل‌هایی‌اند که یک معامله غیرفعال است، و پیشنهاد دادنشان وقتی فعال است بی‌معنا خواهد بود.

نمونه

{
  "logicalName": "par_invoice",
  "displayName": "Invoice",
  "displayCollectionName": "Invoices",
  "publisherPrefix": "par",
  "primaryField": "par_name",
  "fields": [
    { "logicalName": "par_name", "displayName": "Name", "dataType": "Text", "isPrimary": true, "isRequired": true, "maxLength": 200 },
    { "logicalName": "par_total", "displayName": "Total", "dataType": "Decimal", "precision": 18, "scale": 2 },
    { "logicalName": "par_account", "displayName": "Account", "dataType": "Lookup", "targetEntity": "par_account" }
  ],
  "relationships": [
    { "logicalName": "par_account_invoices", "type": "OneToMany", "referencedEntity": "par_account", "referencingEntity": "par_invoice", "lookupField": "par_account" }
  ]
}

نسخه‌گذاری

نسخه‌های قدیمی‌تر شِما کنار نسخه‌های تازه نگه داشته می‌شوند تا راه‌حل‌هایی که از پیش مستقر شده‌اند، پس از تحول شِما همچنان اعتبارسنجی شوند. وقتی تغییری شکننده لازم باشد، به جای ویرایش این نسخه، نسخهٔ تازه‌ای (model-driven-entity@2) منتشر می‌شود.