> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# تعبيرات المعرّفات والترقيم

> أنشئ معرّفات كيان تسلسلية وأرقام مراجع للنماذج بصورة حتمية مع الجذور والدوال ورموز التاريخ المتاحة في كل سياق.

## استخدم تعبيرات الترقيم للهوية لا للسياسة

تنشئ تعبيرات المعرّف التسلسلي ورقم النموذج شكلاً مقروءاً لرقم خصصه KayanOS مسبقاً. وهي مناسبة لمراجع مثل `CSR-2026-00042` وليست بديلاً عن حالة أو صلاحية أو اعتماد أو قرار تدقيق.

توجد الدالتان المحجوزتان في [دوال المعرّفات والترقيم](/ar/reference/expressions/helpers/serial). لا تفترض توفرهما في حقل محسوب عادي.

![إعداد حقل المعرّف التسلسلي في KayanOS لطلب خدمة مواطن، ويظهر مساحة الاسم والتنسيق وإعدادات التسلسل.](https://kayanos.app/docs-images/ar/reference/expressions-serial-and-numbering.png)

## سياق معرّف الكيان التسلسلي

تتلقى تعبيرات مساحة الاسم:

| الجذر                                        | المعنى                                     |
| -------------------------------------------- | ------------------------------------------ |
| `$` و`$record`                               | بيانات السجل الذي سيخصص له المعرّف.        |
| `$organizationId` و`$entityKey` و`$fieldKey` | معرّفات نطاق ثابتة.                        |
| `$timezone`                                  | `UTC` أو المنطقة الزمنية المضبوطة للمنظمة. |
| `$now`                                       | قيمة Date في وقت التخصيص.                  |

تضيف تعبيرات التنسيق `$namespace` و`$sequence`، و`$sequence` نص. تحدد مساحة الاسم سلسلة العد، بينما يحدد التنسيق طريقة عرض الرقم المخصص.

```jexl theme={null}
// مساحة الاسم
$organizationId + ":" + $entityKey + ":" + $fieldKey

// التنسيق
"CSR-" + serialDate("yyyy", $now, $timezone) + "-" + serialPad($sequence, 5)
```

## سياق ترقيم النموذج

يستخدم ترقيم النموذج جذوراً مختلفة: `$` و`$record` و`$savedState` و`$variables` و`$fields` و`$organizationId` و`$formId` و`$formVersionId` و`$sessionId` و`$codePrefix` و`$profile` و`$status` و`$initiatorId` و`$initiatorType` و`$publicUserId` و`$preview` و`$timezone` و`$now`. وتضيف تعبيرات التنسيق `$namespace` و`$sequence`.

```jexl theme={null}
$codePrefix + "-" + serialDate("yyyy", $now, $timezone) + "-" + serialPad($sequence, 4)
```

لا تنقل تعبير معرّف الكيان إلى ترقيم النموذج من دون تغيير جذوره. فترقيم النموذج يملك `$formId`، بينما يملك معرّف الكيان `$entityKey` و`$fieldKey`.

## الدالتان

```jexl theme={null}
serialPad($sequence, 5)             // 00042
serialPad($sequence, 5, "X")        // XXX42
serialDate("yyyy-MM", $now, $timezone)
```

تفهم `serialDate` الرموز `yyyy` و`yy` و`MM` و`dd` فقط. وهي تختلف عمداً عن `dateFormat` العامة التي تستخدم `YYYY` و`DD` ورموزاً أخرى. يعيد التاريخ غير الصالح نصاً فارغاً؛ لذلك اختبر المرجع النهائي المعروض لا الدالة منفردة فقط.

## قواعد التصميم الحتمي

* حافظ على ثبات مساحة الاسم؛ فتغييرها يغير سلسلة العد.
* استخدم `$sequence` و`$namespace` ومفاتيح النطاق الثابتة والساعة المضبوطة. لا تستخدم `random` أو`shuffle` أو`sample` أو حقلاً يتغير بعد التخصيص.
* استخدم تنسيقاً مقروءاً ومحدود الطول.
* اختبر أول قيمة وقيمة تتجاوز عرض الحشو وحد السنة وأي وضع إدخال/طلب يدوي مسموح.
* تعامل مع المعرّف المعروض كمرجع قابل للتتبع، ولا تعدله لمجرد تحسين شكل شاشة.

## أنماط شائعة

| الحاجة                   | المثال                                                                         |
| ------------------------ | ------------------------------------------------------------------------------ |
| سلسلة واحدة لكل حقل كيان | `$organizationId + ":" + $entityKey + ":" + $fieldKey`                         |
| سلسلة لكل فئة خدمة       | `$organizationId + ":" + $.service_category`                                   |
| طلب مواطن مسبوق بالسنة   | `"CSR-" + serialDate("yyyy", $now, $timezone) + "-" + serialPad($sequence, 5)` |
| مرجع نموذج مطبوع قصير    | `$codePrefix + "-" + serialPad($sequence, 4)`                                  |

استخدم نمط الفئة فقط عندما تقبل سياسة الخدمة صراحة سلسلة مستقلة لكل قيمة فئة مخزنة. لا تعد التسمية التي أعيدت تسميتها قيمة فئة ثابتة.

## استكشاف الأخطاء

| العرض                          | افحص                                                                   |
| ------------------------------ | ---------------------------------------------------------------------- |
| تنسيق فارغ                     | هل يعيد كل فرع نصاً وهل تستقبل `serialDate` تاريخاً صالحاً؟            |
| إعادة تسلسل غير متوقعة         | هل تغيرت مساحة الاسم أو هل تحتوي حقلاً متغيراً؟                        |
| سنة/شهر خاطئ                   | هل `$timezone` مضبوط كما يلزم، وهل تستخدم الرموز الصغيرة `yyyy` و`dd`؟ |
| الدالة غير موجودة في حقل محسوب | هي محجوزة لسياق الترقيم؛ استخدم الدوال العامة فقط حيث تكون مدعومة.     |

## أدلة ذات صلة

* [المعرّفات التسلسلية](/ar/build/serial-ids)
* [سياقات وتوافر التعبيرات](/ar/reference/expressions/contexts)
* [دوال التاريخ والوقت](/ar/reference/expressions/helpers/date)