تعريف الجدول المبني على البيانات

معرّف المخطط: 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	لا	الاسم المنطقي للحقل الذي يظهر نصًّا ثانويًّا للسجل — السطر الثاني الأصغر تحت اسمه حيثما تُسرد السجلات بلا شبكة، كلوح البحث (§6.13.5). ويجب أن يسمّي حقلًا في fields ليس هو الحقل الأساسي ولا عمود ملف/صورة.
hierarchyParentField	string | null	لا	الاسم المنطقي لحقل البحث الذي يجعل هذا الجدول هرميًّا — الحقل الذي يحمل أب كل سجل ويشير إلى هذا الجدول نفسه (الفئة الأب لفئة، الوحدة الأعلى لوحدة). ويجب أن يسمّي حقلًا في fields من نوع Lookup يكون targetEntity له هذا الجدول. لا يمنح شيئًا ولا يفرض شيئًا: يظل الجدول يُرسم كشبكة حتى تُداخل طريقةُ عرضٍ سجلاتِه. وفائدته أن الهرمية خاصية البيانات لا خاصية طريقة عرض واحدة — فالمستوى الأعلى في طريقة عرض شجرية يأخذ ارتباطه منه.
personField	string	null	لا
constraints	array	لا	قواعد تفرضها قاعدة البيانات لا التطبيق (انظر أدناه) — عمود فريد، أو فترة لا يجوز أن تتداخل مع أخرى في النطاق نفسه.
fields	array	نعم	تعريف حقل واحد أو أكثر (انظر أدناه).
relationships	array	لا	علاقات واحد-إلى-متعدد مدعومة بحقول بحث.
isAuditEnabled	boolean	لا	يفعّل تدقيق التغييرات للجدول (القسم 6.5). القيمة الافتراضية false.
states	array	لا	الحالات التي يمكن أن يكون فيها سجل من هذا الجدول (§6.14) — دورة حياته. انظر أدناه. وهي غائبة في وثيقة كُتبت قبل وجود الحالات، وبذلك يميّز المستورِد ذلك عن جدول لا حالات له.
reasons	array	لا	الأسباب، ينتمي كل واحد منها إلى حالة واحدة بالضبط. انظر أدناه.
statusValueBase	integer	لا	أرضية المدى الذي تُرقَّم منه خيارات الحالة والسبب المضافة في هذا الجدول — أساس قيمة الخيار للناشر المالك (§6.14). أما فعّال/غير فعّال المزروعان فيقعان خارجه عند 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 (من 1 إلى 4000).
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. وتُرفَع البايتات إلى نقطة نهاية الملف الخاصة بالحقل لا عبر واجهة السجل، وتُقدَّم بصلاحية قراءة السجل نفسه. وأيّ المخزنين يحمل الملف يقرره حجمه، لا إعداد يختاره الصانع.

العلاقة

الحقل	النوع	مطلوب	ملاحظات
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) بدلًا من تعديل هذا الإصدار.