> ## 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`. وهو يختلف عن معرّف السجل الداخلي وعن الرقم الذي قد يورده نظام خارجي. تساعد قاعدة ترقيم جيدة على العثور على الطلب وذكره في خطاب ومتابعته أثناء المراجعة من دون أن يبتكر الموظفون أرقاماً يدوياً.

يشرح هذا الدليل حقل الكيان من نوع `serial_id`: الرقم نفسه، ونطاق التسلسل، والتعبير الذي يعرضه، والطرق المحدودة لتعيينه أو تغييره، والضوابط التي تحمي القيم الصادرة النشطة من التصادم مع الاحتفاظ بتاريخ التغيير. استخدم مفتاح الحقل الثابت داخل أي تعبير؛ عنوان الحقل المترجم ليس مفتاحاً للتعبير.

تعرض لقطة أداة الإنشاء الآتية إعداداً فعلياً لمعرّف تسلسلي في كيان **طلب خدمة مواطن**، بما فيه الإصدار التلقائي وسياسة الإدخال اليدوي وتعبيرا النطاق والتنسيق ورقم البداية والمنطقة الزمنية.

![إعدادات المعرّف التسلسلي في KayanOS لكيان طلب خدمة مواطن.](https://kayanos.app/docs-images/ar/build/serial-ids.png)

## متى تستخدمه

استخدم المعرّف التسلسلي عندما يحتاج السجل إلى مرجع ثابت يستطيع الناس تكراره بأمان عبر مسار العمل. من أمثلته رقم طلب خدمة مواطن، أو رقم ترخيص، أو مرجع معاينة، أو تذكرة صيانة، أو رقم قرار، أو رقم خطاب صادر. ضع الحقل في أعلى تخطيط السجل، واستخدمه في البحث والمستندات والإشعارات والمحادثات بين فرق العمل.

اختر حقلاً آخر عندما يكون للقيمة غرض مختلف:

| الحاجة                                | الحقل الأنسب        | السبب                                                          |
| ------------------------------------- | ------------------- | -------------------------------------------------------------- |
| مفتاح السجل الداخلي في قاعدة البيانات | معرّف السجل النظامي | ليس مرجعاً عاماً منسقاً للعرض على الناس.                       |
| رقم يقدمه المواطن أو نظام خارجي       | نص                  | يبقى المرجع الخارجي منفصلاً عن الرقم الذي يصدره KayanOS.       |
| تصنيف خدمة أو نوع ترخيص               | اختيار أو حالة      | يجب أن تحمل القائمة المضبوطة معنى المسار بدلاً من رقم التسلسل. |
| قيمة مشتقة من مبالغ أو تواريخ         | حقل محسوب           | الحساب يفسر نتيجة، أما الرقم التسلسلي فهو هوية صادرة.          |

ابدأ بحقل تسلسلي واحد لهوية عمل واحدة. لا تستخدم الحقل نفسه لرقم الاستلام ورقم شهادة نهائية إلا إذا كانا بالفعل الرقم ذاته طوال دورة الحياة. وإذا احتاج القرار اللاحق إلى رقم قانوني أو مرجع مستند خاص به، فأنشئ حقلاً أو كياناً مستقلاً واربط السجلين.

تحتفظ الخدمة بكل قيمة صادرة كسجل إصدار. إذا أعيدت محاولة الإصدار نفسه، يستخدم النظام مفتاح تكرار آمن كي يعيد القيمة ذاتها. يرتبط العداد بالمؤسسة والنطاق، ويحمي قيد سجلات الإصدار النشطة القيمة المعروضة من التصادم مع سجل نشط آخر في المؤسسة والنطاق نفسيهما. ولقيمة التسلسل المخزنة قيد منفصل في النطاق نفسه. هذه حماية من سباق إصدار حي أو إعادة طلب، وليست سبباً لجعل التنسيق غامضاً. عندما يستبدل تغيير صريح سجل إصدار، تبقى قيمته المعروضة القديمة في التاريخ لكنها لا تعود تشغل قيد القيمة المعروضة النشطة، ولذلك قد يسمح التخزين باستخدام النص التاريخي مرة أخرى. راجع سجل الإصدار للتتبع، وضع سياسة بشرية تمنع إعادة الاستخدام إذا كانت الخدمة تشترط ذلك.

## الإعداد

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

### نمط الإصدار

| النمط                  | ما الذي يحدث                                                                                                                     | الاستخدام المناسب                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `automatic`            | يُخصص رقم عند إنشاء سجل وقيمة الحقل فارغة.                                                                                       | استقبال اعتيادي يجب أن يمنح كل طلب مرجعاً فوراً.     |
| `request`              | يمكن أن يبقى الحقل فارغاً عند الإنشاء، ثم يطلب إجراء تحديث مصرّح به إصدار الرقم لاحقاً.                                          | مسار لا يصدر المرجع إلا بعد قبول أو مراجعة.          |
| `automatic_or_request` | تتاح الطريقتان. لكن القيمة الفارغة في مسار الإنشاء المعتاد تحصل على رقم تلقائياً، ولا يصلح طلب الإصدار إلا ما دام السجل بلا رقم. | مسار يملك أكثر من طريقة استلام، بعد اختبار كل طريقة. |

لا يعني النمط الهجين أن المستخدم سيختار الطريقة في كل مرة. في مسار الإنشاء المعتاد يُصدر الرقم للقيمة الفارغة لأن الإعداد يشمل التوليد التلقائي. ولا ينشئ إجراء الإصدار عند الطلب رقماً ثانياً لحقل سبق تعيينه.

### الإدخال اليدوي والتغيير اللاحق

سياسة الإدخال اليدوي ضيقة عمداً:

| السياسة      | المعنى                                                                                                                                         |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `blank_only` | يمكن للموظف إدخال قيمة غير فارغة فقط قبل أن يحصل السجل على رقم، مع بقاء فحص صلاحية الإنشاء أو التحديث ومنع التكرار مقابل سجلات الإصدار النشطة. |
| `never`      | لا يسمح مسار التعيين العادي بتسجيل قيمة يدوية.                                                                                                 |

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

### تعبيرا النطاق والتنسيق

يحدد النطاق السجلات التي تشترك في عداد واحد وفي نطاق حماية من تصادم القيم المعروضة النشطة. التعبير الافتراضي يجمع المؤسسة ومفتاح الكيان ومفتاح الحقل:

```jexl theme={null}
$organizationId + ':' + $entityKey + ':' + $fieldKey
```

إذا كانت المؤسسة `org-1` والكيان `citizen_service_requests` والحقل `request_reference` فستكون النتيجة `org-1:citizen_service_requests:request_reference`. تحدد المؤسسة والنطاق عداداً واحداً. تمنع قاعدة البيانات إسناد قيمة معروضة موجودة لدى سجل إصدار حالي غير مستبدل إلى سجل حالي آخر في هذا النطاق، كما تمنع إعادة استخدام قيمة تسلسل مخزنة فيه. لكن ذلك ليس سجلاً عالمياً دائماً للنص المعروض: بعد أن يستبدل تغيير صريح سجل إصدار يمكن للتخزين إعادة استخدام النص التاريخي. احتفظ بالإعداد الافتراضي عندما يحتاج كل حقل كيان إلى سلسلة مستقلة. لا تشارك نطاقاً بين حقول إلا عندما تكون السلسلة المشتركة مقصودة ومعتمدة، وراجع كل تنسيق بحثاً عن تصادم بين السجلات النشطة، وراجع سجل الإصدار قبل اعتبار مرجع معروض فريداً تاريخياً.

يحوّل تعبير التنسيق التسلسل التالي إلى المرجع المرئي. التنسيق الافتراضي هو `$sequence`. ويمكن أن يكون التنسيق الواضح لطلب خدمة عامة كما يلي:

```jexl theme={null}
'CSR-' + serialDate('yyyy', $now, $timezone) + '-' + serialPad($sequence, 5)
```

إذا كان التسلسل `42` في سنة 2026 فالنتيجة المتوقعة هي `CSR-2026-00042`. تضيف الدالة `serialPad(value, width, char?)` أصفاراً إلى اليسار ما لم تحدد محرف حشو واحداً آخر. وتنسق `serialDate(format, value?, timezone?)` التاريخ باستخدام `yyyy` و`yy` و`MM` و`dd`؛ وسيطها الثاني هو القيمة المراد تنسيقها ووسيطها الثالث المنطقة الزمنية. استخدم ترتيب الوسائط المبين هنا كما هو.

يعمل التعبيران ضمن سياق يعرف السجل:

| المتغير أو الدالة                            | متاح في         | الاستخدام                                 |
| -------------------------------------------- | --------------- | ----------------------------------------- |
| `$` و`$record`                               | النطاق والتنسيق | بيانات السجل الحالي.                      |
| `$organizationId` و`$entityKey` و`$fieldKey` | النطاق والتنسيق | الهوية الثابتة لهذا الإعداد.              |
| `$timezone` و`$now`                          | النطاق والتنسيق | منطقة المؤسسة أو UTC ووقت الإصدار الحالي. |
| `$namespace` و`$sequence`                    | التنسيق فقط     | النطاق المحلول والتسلسل التالي كنص.       |
| `serialPad` و`serialDate`                    | النطاق والتنسيق | دوال الحشو وعرض التاريخ.                  |

لا تضع اسم مواطن أو رقماً وطنياً أو بيانات اتصال أو كلمة مرور أو رمز وصول في تعبير الرقم. فقد يظهر المرجع في تصدير أو مستند أو حديث. وتجنب تنسيقاً لا يستخدم `$sequence` إلا إذا كانت الأجزاء المتبقية تميز كل إصدار نشط في الوقت نفسه بصورة مثبتة؛ فالتصادم مع سجل نشط يعاد حله ثم قد يفشل بدلاً من استبدال ذلك السجل بصمت.

### رقم البداية والمنطقة الزمنية والمعاينة والتعبئة المسبقة

**البدء من** هو أول تسلسل موجب لنطاق جديد. استخدمه عندما يبدأ سجل ورقي معتمد من رقم معلوم، لكن لا تخفضه بعد إصدار مراجع فعلية. تُطبع القيم غير الموجبة أو غير الصحيحة إلى بداية موجبة آمنة، لذلك أدخل الرقم المقصود وراجعه صراحة.

تختار **المنطقة الزمنية** منطقة المؤسسة الافتراضية أو UTC لقيمة `$timezone`. يهم ذلك عندما يحتوي التنسيق تاريخاً عند حدود اليوم المحلي. اختر منطقة المؤسسة ليوافق تاريخ يوم العمل المحلي، واختر UTC فقط عندما تكون هناك قاعدة تاريخ عالمية واحدة. غيّرها بحذر، إذ يمكن للحظة نفسها أن تعطي بادئة تاريخ مختلفة.

استخدم معاينة الرقم قبل إصدار سجل. تحل المعاينة التعبيرات وتعرض المرشح التالي لكنها غير ملزمة: لا تقدم العداد ولا تحجز القيمة. لذلك قد يختلف الرقم الحقيقي إذا أصدر سجل آخر رقماً من النطاق نفسه بين المعاينة والحفظ.

للسجلات القديمة التي لا تحمل قيمة، استخدم تعبئة الدفعات بعد حفظ الكيان والحقل. صفِّ مجموعة المرشحين، وافحص العدد والعينات في المعاينة، ثم شغّل المهمة الخلفية. الغرض من العملية تعبئة الحقول الفارغة، وتترك السجلات التي حصلت على رقم دون تغيير. اجعل المرشح محدوداً في التشغيل الأول وراجع نتيجة المهمة قبل توسيعه.

## مثال عملي

تستقبل مديرية خدمات عامة في سوريا طلبات مواطنين لخدمة محلية. يحتاج موظفو الاستقبال إلى مرجع يمكن ذكره عبر الهاتف، ويظهر في إشعار الاستلام، ويبقى ثابتاً عند الإحالة والمعاينة والقرار. الكيان هو `citizen_service_requests` ومفتاح حقل الرقم هو `request_reference`.

اضبط الحقل بهذه القيم:

| الإعداد         | القيمة                               | السبب                                                |
| --------------- | ------------------------------------ | ---------------------------------------------------- |
| النمط           | `automatic`                          | يجب أن يحصل كل طلب استلام مكتمل على مرجع فوراً.      |
| الإدخال اليدوي  | `never`                              | لا ينبغي لموظف الاستقبال إنشاء مراجع متشابهة يدوياً. |
| النطاق          | التعبير الافتراضي                    | لهذا الحقل سلسلة خاصة داخل المؤسسة.                  |
| التنسيق         | بادئة `CSR` وسنة وتسلسل من خمس خانات | يتعرف الموظف إلى الغرض ويذكر رقماً بعرض ثابت.        |
| البدء من        | `1`                                  | سجل خدمة جديد.                                       |
| المنطقة الزمنية | المؤسسة                              | تتبع بادئة التاريخ يوم العمل المحلي للمديرية.        |

احفظ الإعداد، ثم أنشئ طلباً واترك حقل الرقم فارغاً. يخصص مسار الإنشاء الرقم التالي ويخزنه مع الطلب. إذا كان التسلسل التالي 42 في وقت محلي من سنة 2026، فالتعبير الآتي ينتج القيمة التي يراها الموظف:

```jexl theme={null}
'CSR-' + serialDate('yyyy', $now, $timezone) + '-' + serialPad($sequence, 5)
```

قيمة السجل المتوقعة هي `CSR-2026-00042`. ينبغي لقالب إشعار الاستلام أن يقرأ `request_reference` المخزن، لا أن يعيد تقييم تعبير الرقم. ويمكن لسجل معاينة مرتبط بالطلب أن يعرض المرجع، لكن لا ينسخه إلى حقل نص قابل للتعديل.

إذا احتاجت المديرية مرجع شهادة يصدر في وقت لاحق، أنشئ كيان شهادة أو حقلاً تسلسلياً منفصلاً. ولمسار مراجعة أولاً، استخدم نمط `request`: اترك الحقل فارغاً عند الاستلام، ثم اسمح لعملية تحديث المراجع المصرح بها بتوليده بعد القبول، واختبر أن الطلب الثاني يعيد الرقم المعين بدلاً من توليد رقم جديد.

لترحيل مضبوط من سجل قديم، اختر `blank_only`، وصفِّ فقط السجلات التي يكون فيها `request_reference` فارغاً، ثم امنح كل قيمة قديمة تعييناً أولياً. لا تحاول تغيير قيمة معينة عبر تحديث عادي. وإذا أقر تصحيح رسمي، فاستخدم مسار التغيير الصريح، وأدخل سبباً مثل «تصحيح نقل من السجل الورقي»، واحتفظ بتاريخ الإصدار القديم والجديد للمراجعة.

## الاختبار

اختبر الإعداد في مساحة غير إنتاجية مع مجموعة سجلات صغيرة مسماة. دوّن النتيجة المتوقعة قبل التنفيذ حتى يميز المراجع بين النتيجة الصحيحة والنتيجة العرضية.

| الاختبار               | الإعداد                                                                                      | النتيجة المتوقعة                                                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| أول إصدار              | نمط تلقائي وسجل فارغ وبدء من `1`                                                             | يخزن الحقل تسلسلاً منسقاً بالقيمة `1`.                                                                                               |
| إصدار متتالٍ           | أنشئ سجلين فارغين                                                                            | يحصل كل سجل إصدار نشط على القيمة التالية في النطاق نفسه من دون تصادم في القيمة المعروضة النشطة.                                      |
| أمان الإعادة           | أعد طلب الإنشاء أو التوليد نفسه عندما يدعمه المسار                                           | تعيد الإعادة القيمة الصادرة نفسها ولا تستهلك رقماً جديداً.                                                                           |
| السياسة اليدوية        | جرب قيمة مخصصة قبل التعيين ثم بعده                                                           | تسمح `blank_only` بالتعيين الأول فقط وتفحص السجلات النشطة؛ وترفض `never` الإدخال اليدوي، ويرفض الاستبدال العادي.                     |
| التصادم                | استخدم نطاقاً مشتركاً وحاول إدخال القيمة المعروضة نفسها مرتين ما دام سجل الإصدار الأول نشطاً | يفشل الطلب الثاني بتعارض بدلاً من استبدال سجل الإصدار النشط.                                                                         |
| حد الوقت               | عاين قبل وبعد منتصف الليل المحلي                                                             | تتبع بادئة التاريخ المنطقة الزمنية المضبوطة.                                                                                         |
| تعبئة دفعات            | صفِّ بضعة سجلات قديمة فارغة وافحص العينات                                                    | لا يصبح مرشحاً إلا السجل الفارغ المقصود وتراجع نتيجة المهمة قبل دفعة أكبر.                                                           |
| تغيير صريح             | استخدم حقلاً غير ثابت مع عضو مخول وسبب                                                       | يسجل البديل ويصبح السابق مستبدلاً، أما الحقل الثابت فيبقى غير قابل للتغيير.                                                          |
| قابلية التتبع التاريخي | افحص سجل الإصدار بعد استبدال صريح                                                            | يبقى النص المعروض القديم قابلاً للتتبع. قرر بسياسة الخدمة هل يمنع استخدامه مجدداً، إذ قد يسمح التخزين بإعادة استخدامه بعد الاستبدال. |

اختبر تعبير التنسيق منفصلاً ببيانات معروفة. استعمل عرض خمس خانات وتسلسلاً معلوماً لتكون النتيجة واضحة:

```jexl theme={null}
'CSR-' + serialPad($sequence, 5)
```

عندما تكون `$sequence` مساوية لـ `7` فالنتيجة المتوقعة هي `CSR-00007`. ثم اختبر تعبير نطاق يعتمد قيمة من السجل فقط إذا كانت السلسلة المنفصلة حسب الفئة سياسة معتمدة لا مصادفة:

```jexl theme={null}
$organizationId + ':citizen-service:' + $.service_category
```

ينشئ هذا نطاقاً مستقلاً داخل المؤسسة لكل قيمة مخزنة في `service_category`. اختبر الفئة الفارغة أو المتغيرة قبل الاعتماد عليه، وفضّل النطاق الافتراضي عندما لا توجد موافقة واضحة على تقسيم التسلسل.

## استكشاف الأخطاء وإصلاحها

| العرض                             | افحص أولاً                                                                          | الاستجابة الآمنة                                                                      |
| --------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| سجل جديد بلا رقم                  | هل الحقل في نمط `request`، أو هل تُرك فارغاً قصداً؟                                 | استخدم إجراء التوليد عند الطلب المصرح به عندما تصل العملية إلى مرحلة الإصدار.         |
| تختلف المعاينة عن القيمة النهائية | هل أصدر سجل آخر رقماً من النطاق نفسه بعد المعاينة؟                                  | اعتبر المعاينة تقديراً لا حجزاً.                                                      |
| التنسيق فارغ أو يعرض خطأ          | هل يعيد التعبير نصاً غير فارغ، وهل ترتيب `serialDate` صحيح والمفاتيح صحيحة؟         | ابدأ بـ `$sequence`، ثم أضف جزءاً واحداً في كل مرة بعد التحقق.                        |
| تُرفض قيمة يدوية                  | هل السياسة `never`، أو القيمة فارغة، أو تكرر قيمة سجل إصدار نشط، أو للسجل رقم قائم؟ | استخدم التعيين الأول المعتمد أو مسار التصحيح الصريح ولا تتجاوز سجل الإصدار التاريخي.  |
| لا يغير التحديث العادي الرقم      | هل حصل الحقل على رقم سابقاً؟                                                        | هذا متوقع. استخدم تغييراً صريحاً مصرحاً به فقط عندما لا يكون الحقل ثابتاً ويتوفر سبب. |
| لا تبدأ التعبئة المسبقة           | هل حُفظ الكيان والحقل، وهل يملك العضو صلاحية إدارة الحقول؟                          | احفظ أولاً، وراجع المرشحات، وشغّل معاينة صغيرة.                                       |
| الأرقام تبدو سليمة لكنها تتصادم   | هل تشترك إعدادات متعددة في نطاق وتنتج نمط بادئة وتسلسل واحداً لسجلات نشطة؟          | افصل النطاقات أو عدّل التنسيق المعتمد قبل إصدار قيم أخرى.                             |

## الأذونات وحدود جودة البيانات

يتطلب بناء الحقل أو تعبئة دفعاته صلاحية إدارة الحقول. وتتطلب معاينة الرقم صلاحية إنشاء الكيان أو تحديثه. ويتطلب التوليد عند الطلب والتبديل الصريح عملية تحديث مصرّحاً بها على السجل المعني؛ وقد تمنع صلاحيات النطاق العضو من تعديل سجل بعينه رغم امتلاكه عملية التحديث. ولا يستطيع حقل تسلسلي ثابت استخدام مسار الاستبدال الصريح.

تحمي الأذونات العملية، لكنها لا تضمن جودة السياسة. قبل النشر، اطلب من مالك الخدمة اعتماد البادئة وسلوك السنة ورقم البداية وحد النطاق وسبب التصحيح. اجعل حقل الرقم للقراءة فقط في التخطيطات التي لا ينبغي للموظف إدخاله فيها. واحفظ المرجع الخارجي في حقل مستقل، ولا تعتبر الشكل الجميل للرقم دليلاً على قبول الطلب أو صحة بياناته.

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

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

* اختر الحقل والتخطيط المحيطين بالمرجع في [حقول الكيانات وتخطيطاتها](/ar/build/entity-fields-and-layouts).
* صمّم الطلب والمعاينة والقرار كسجلات مترابطة في [الكيانات](/ar/build/entities).
* تعلّم قواعد الصياغة والعوامل والدوال في [صياغة لغة التعبيرات](/ar/reference/expressions/language-syntax).
* استخدم المبالغ والأعلام والملخصات المشتقة في [الحقول المحسوبة](/ar/build/calculated-fields).