> ## 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 الفاشل وأعد المحاولة فقط عندما تكون آمنة وصعّد بسجل قابل للتنفيذ.

## شخّص الحد لا العرض وحده

تحدث معظم مشكلات KayanOS عند حد: مؤسسة خاطئة أو إصدار منشور غير متاح أو عدم تطابق دور/نطاق أو قيمة حقل مفقودة أو خطوة مزامنة غير متصلة أو قاعدة دورة حياة سجل أو استعلام مصدر لوحة أو اتصال أو شرط تزامن API. لا يكفي زر ظاهر أو قائمة فارغة أو رسالة خطأ عامة لتحديد السبب.

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

![عرض استكشاف أخطاء KayanOS لمسار طلب خدمة مواطن.](https://kayanos.app/docs-images/ar/reference/troubleshooting.png)

## التقط سجل حادث آمن أولاً

اجمع ما يكفي من الدليل لإعادة الإنتاج وتوجيه المشكلة من دون نسخ أسرار أو محتوى خاص:

| ما تجمعه               | مثال                                                                                                   | ما لا تجمعه/تشاركه                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| النتيجة الدقيقة        | «يعيد الحفظ رفض صلاحية بعد تغيير `status`».                                                            | إعادة صياغة تفقد نص الخطأ الفعلي.                               |
| الوقت والمنطقة الزمنية | `2026-07-12 14:20 Asia/Damascus` أو منطقة المؤسسة المضبوطة.                                            | وقت محلي مفترض بلا منطقة زمنية.                                 |
| المؤسسة والفاعل        | اسم/معرف المؤسسة ودور العضو أو نوع المشارك العام أو **اسم/تلميح** رمز التكامل.                         | كلمة مرور أو رمز API كامل أو رمز دخول أو مفتاح خاص أو سر تسجيل. |
| الهدف                  | سجل/مرجع منقح أو مرجع نموذج/جلسة أو مفتاح كيان أو لوحة/عنصر أو قالب أو مهمة تصدير أو معرف تشغيل أتمتة. | سجل مواطن كامل أو محتوى مرفق أو URL ملف موقع.                   |
| الإجراء/السياق         | URL أو وحدة وإصدار نموذج وحالة مختارة ونطاق/مركز خدمة وإصدار متصفح/تطبيق وخطوات قبل الفشل.             | لقطات تعرض بيانات شخصية أو بيانات اعتماد مخفية.                 |
| دليل الخطأ             | الرسالة المرئية الدقيقة أو `x-request-id` لـAPI أو معرف تشغيل/مهمة أو لقطة آمنة.                       | تفريغات وحدة تحكم تحوي ترويسات Authorization أو حمولة سرية.     |

أعط الحادث عنواناً قصيراً يذكر الحد: «لا يستطيع مفتش تسليم معاينة غير متصلة بعد إعادة الاتصال» قابل للتنفيذ؛ «KayanOS معطل» ليس كذلك.

## اتبع ترتيب التشخيص نفسه

1. **أعد الإنتاج بأمان.** هل يستطيع الدور المقصود إعادة العرض بطلب غير إنتاجي معتمد؟ سجل الخطوات الدقيقة والنتيجة المتوقعة.
2. **افحص المؤسسة والهوية.** أكد المؤسسة المختارة والعضو/المشارك العام المسجل والدور والنطاق ومالك جلسة النموذج أو مالك رمز التكامل.
3. **افحص الإتاحة.** أكد أن الميزة صادرة وأن النموذج/الإصدار/القالب/اللوحة/الاتصال مضبوط لهذا الاستخدام وأن شروط النشر/الانتهاء/الحد اللازمة متحققة.
4. **افحص البيانات والحالة.** راجع القيم المطلوبة وأنواع الحقول والخيارات والعلاقات وحالة السجل وحالة جلسة النموذج والإصدار وقاعدة دورة الحياة الحالية.
5. **افحص الحد القابل للتدقيق.** افحص دليل التشغيل/المهمة/الطلب/الجلسة/المرجع الآمن. لمشكلة API احتفظ بـ`x-request-id`؛ ولأتمتة KayanOS احتفظ بمعرف التشغيل؛ ولجلسة غير متصلة احتفظ بمعرف الإرسالة المحلي ومعرف جلسة الخادم إن توفر.
6. **اختر أصغر معالجة آمنة.** صحح إعداداً/قيمة خاطئة معروفة واحدة ثم أعد اختبار الحالة نفسها. لا تجمع تغييرات غير مترابطة.
7. **وثق النتيجة.** سجل السبب الجذري والتغيير ونتيجة الاختبار والخطر المتبقي والمالك. إن لم يثبت السبب، صعّد بدلاً من التخمين.

## فهرس الأعراض

| العرض                          | أول حد للفحص                                                         | الخطوة الآمنة التالية                                                            |
| ------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| قائمة أو كيان أو إجراء غائب    | المؤسسة أو السطح الصادر أو الدور/الفعل أو النطاق                     | قارن الدور المقصود بدور مرفوض؛ لا تمنح وصول مالك كاختبار.                        |
| سجل مرئي لا يفتح/يحفظ          | فعل فتح/تحديث أو نطاق سجل أو قاعدة حقل أو حالة/دورة حياة             | التقط نطاق/حالة السجل المستهدف والحقل/الإجراء الدقيق.                            |
| لا يبدأ نموذج أو لا تفتح جلسة  | نوع/إصدار النموذج أو صلاحية بدء/فتح أو حد مالك الجلسة العامة         | أكد مسار عادي/عام/غير متصل وبادئ/إصدار الجلسة.                                   |
| لا يصل عمل غير متصل            | حالة الطابور أو الاتصال أو التوثيق أو ملف محلي أو بدء/تثبيت مزامنة   | احتفظ بالجلسة/الملفات المحلية وافحص دليل `pending`/`failed` قبل إنشاء جلسة أخرى. |
| لا يظهر/يبدأ نموذج عام         | التمكين العام أو إصدار عادي/منشور أو تاريخ انتهاء أو سقف أو شرط حساب | افحص كل شروط الأهلية وجلسة متصفح عامة نظيفة.                                     |
| لوحة فارغة/مرفوضة              | مصدر/مرشح/إعداد عنصر وصلاحيات مصدر المشاهد                           | تحقق بسجل معروف ونطاق المشاهد؛ ميّز الصفر عن الرفض.                              |
| تصيير/اسم ملف قالب خاطئ        | سياق سجل أو وسم/تعبير أو وضع بحث/قائمة سماح أو إصدار مخرج/قالب       | استخدم سجلاً مضبوطاً وافحص الناتج المصير لا مصدر DOCX فقط.                       |
| قيمة تسلسلية/محسوبة غير متوقعة | إعداد الحقل أو بيانات المصدر أو التعبير أو توقيت/تبعية               | قارن الإعداد والمدخلات بالنتيجة المتوقعة المعروفة.                               |
| تعيد API خطأ                   | حالة/مالك الرمز أو أهلية كيان/حقل أو جسم/مرشح أو حد أو `ETag`        | احتفظ بالحالة ورمز الغلاف و`x-request-id` وترويسات الحد/ETag؛ لا تسجل السر.      |
| يفشل تصدير أو يختفي تنزيل      | حالة المهمة أو البيانات/الصلاحيات المختارة أو احتفاظ/انتهاء          | سجل معرف/حالة المهمة وأعد التشغيل فقط بعد مراجعة الفشل.                          |
| لا يبدأ تشغيل أتمتة أو يفشل    | اتصال KayanOS أو مشغل/مرشح أو حالة هدف/إصدار أو دور/نطاق وقت التشغيل | احتفظ بمعرف التشغيل وبيانات الاختبار؛ لا تشغل مساراً ذا أثر جانبي مراراً.        |

## فشل الصلاحية والإتاحة

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

افحص بهذا الترتيب:

1. المؤسسة الصحيحة والهوية النشطة.
2. المورد والفعل الدقيق المطلوب للعملية.
3. نطاق السجل/الجلسة المستهدف وعلاقة الهيكل.
4. قاعدة قراءة/تحديث مستوى الحقل إن تعلق الأمر بحقل محدد.
5. قاعدة الحالة أو الإجراء أو التوقيع أو دورة الحياة الحالية.
6. شرط النشر/الاتصال/الميزة للسطح المختار.

شغّل اختباراً مسموحاً وآخر مرفوضاً عمداً. إذا نجح الاثنان، فحد الوصول واسع جداً. وإذا فشل الاثنان، فقد تكون المشكلة إعداداً/حالة لا دوراً فردياً.

راجع [الصلاحيات والإتاحة](/ar/reference/permissions-and-availability) لسلسلة القرار الكاملة.

## فشل النماذج والجلسات

| العرض                    | الدليل المطلوب                                            | المعالجة الآمنة                                                                             |
| ------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| لا يبدأ                  | معرف/إصدار/نوع النموذج ودور الفاعل والمؤسسة والرفض الدقيق | أكد صلاحية `initiate` والإصدار المنشور/المقصود؛ استخدم المسار العام أو غير المتصل الصحيح.   |
| الجلسة للقراءة فقط       | نوع/حالة الجلسة والبادئ/المشارك وحالة العنصر              | للعمل غير المتصل المسلّم، احتفظ به وتحقق من المزامنة/المراجعة؛ لا تغيره عبر حساب غير مرتبط. |
| حقل مطلوب يمنع الإرسال   | مفتاح الحقل والشرط وقيم الحالي/الأب/المكرر ونص التحقق     | أعد الإنتاج بصف مضبوط واحد وافحص السياق المحلي/تعبير الإلزام.                               |
| يتصرف صف مكرر بشكل مختلف | فهرس الصف وقيم الأب/الإخوة ونوع المكرر والصف الأول/اللاحق | اختبر كل مثيل ولا تعامل `$index` كمعرف دائم.                                                |
| ملف غير متاح             | مرجع الجلسة ومسار الحقل وحالة المزامنة والفاعل المخول     | تحقق من اكتمال الرفع/المزامنة ووصول الجلسة؛ لا توزع روابط موقعة.                            |
| مشارك عام مرفوض          | مالك جلسة/حساب عام وحالة أهلية النموذج                    | أكد تطابق المشارك/الجلسة وإعدادات العامة لا صلاحيات الموظفين.                               |

لمشكلة إجراء/توقيع، سجل مفتاح الإجراء والحالة قبل/بعد والفاعل والاستجابة—لا الحمولة الحساسة الكاملة.

## فشل المزامنة غير المتصلة

تملك الجلسات غير المتصلة حالات `pending` و`syncing` و`failed` و`synced`. ليست الجلسة المحلية المسلمة مستلمة مركزياً حتى تكون `synced`. أبق الجهاز وملفاته المحلية سليمين أثناء التشخيص.

1. سجل معرف الإرسالة المحلي والنموذج/الإصدار وأوقات إنشاء/إرسال الجهاز وحالة الطابور والمحاولات ووقت الإعادة التالي وآخر خطأ آمن.
2. أكد اتصال الجهاز وأن البادئ يملك جلسة موثقة قابلة للاستخدام. لا تدخل بيانات اعتماد شخص آخر «لفك التعليق».
3. افحص التخزين المحلي وكل ملف مرفق. لا يحل فشل رفع ملف بحذف الملف.
4. دع مسار الإعادة المعتمد يعمل بعد استعادة الاتصال/التوثيق. يستخدم العميل تراجعاً محدوداً؛ وقد يخلق الإرسال اليدوي المتكرر ارتباكاً.
5. عند `synced` افتح جلسة الخادم وقارن الحقول والمكررات والملفات والطوابع. إن كانت جلسة الخادم ناقصة، صعّد بالمرجعين المحلي والخادمي.

راجع [النماذج دون اتصال](/ar/build/offline-forms) لنموذج الحالة/التعافي الكامل.

## فشل نموذج البيانات والمعرف التسلسلي والحقل المحسوب والقالب

### حقول الكيانات وتخطيطات

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

### المعرفات التسلسلية

التقط إعداد حقل التسلسل وتعبير مساحة الاسم/التنسيق وقيمة التسلسل/البداية ومدخلات التاريخ/المنطقة ووضع التوليد وحالة السجل الحالية والمرجع المتوقع. لا تحرر تسلسلاً يدوياً لإخفاء تصادم أو فجوة. اختبر بسجل مضبوط وقارن المعاينة/الإعداد بالنتيجة المخزنة. راجع [المعرفات التسلسلية](/ar/build/serial-ids).

### الحقول المحسوبة

التقط الصيغة ونوع القيمة وإعداد العلاقة المباشرة/العكسية وقيم المصدر والنتيجة والحالة وتوقيت إعادة الحساب. افحص null والقوائم الفارغة والعلاقات المفقودة قبل معاملة نتيجة صفر/فارغة كفشل منطق. لخطأ تبعية/حلقة، أوقف تحرير الحسابات المرتبطة بكثرة واعزل أصغر حلقة. راجع [الحقول المحسوبة](/ar/build/calculated-fields).

### قوالب المستندات

التقط القالب/الإصدار والسجل المستهدف وتنسيق المخرج وتعبير اسم الملف ووضع المتصل/المدير وقائمة السماح الإدارية غير الفارغة إن استخدمت والوسم/التعبير والناتج المصير. اختبر القيم الاختيارية الغائبة والعلاقات الفارغة وأهداف البحث المسموحة/المرفوضة واسم الملف منفصلة. لا تلصق مستنداً فعلياً أو بيانات اعتماد في طلب دعم. راجع [قوالب المستندات](/ar/build/document-templates) و[وسوم قوالب المستندات والتصيير](/ar/build/document-template-tags-and-rendering).

## فشل اللوحة وAPI والتصدير والأتمتة

### لوحات المعلومات

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

### الواجهة البرمجية العامة

سجل حالة HTTP ورمز/رسالة الخطأ و`x-request-id` و**اسم/تلميح** الرمز ونقطة النهاية ومفتاح الكيان ومفتاح الحقل وجسم الطلب المنقح وترويسات الحد و`ETag`/`If-Match` عند اللزوم. تشمل المعالجات الشائعة تدوير/إعادة تفويض رمز وتمكين كيان وتصحيح حقل/مرشح قابل للاستعلام العام واحترام `retry-after` أو إعادة القراءة بعد `412 PRECONDITION_FAILED`. لا تعِد إنشاء/حذفاً بلا تدقيق بعد مهلة.

### مهام التصدير

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

### أتمتة KayanOS

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

## إعادة محاولة آمنة مقابل تصعيد

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

## حزمة التصعيد

عندما تحتاج المشكلة مسؤولاً أو مالك دعم، أرسل حزمة منقحة موجزة:

```txt theme={null}
Title: <boundary and symptom>
Organization: <name or ID>
Time/timezone: <ISO time and timezone>
Actor: <member role / public participant type / token name-hint>
Target: <sanitized record, session, job, run, or request ID>
Expected: <what should happen>
Actual: <what happened, exact safe error>
Steps: <minimal reproduction>
Evidence: <safe screenshot, x-request-id/run ID, relevant status>
Changes already tried: <one or none>
Risk/side effect: <none / possible duplicate / access exposure / other>
```

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

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

* [الصلاحيات والإتاحة](/ar/reference/permissions-and-availability)
* [إرسالات النماذج](/ar/build/form-submissions)
* [النماذج دون اتصال](/ar/build/offline-forms)
* [البوابة العامة](/ar/build/public-portal)
* [مرجع الواجهة البرمجية العامة](/ar/reference/public-api)
* [المعرفات التسلسلية](/ar/build/serial-ids)
* [الحقول المحسوبة](/ar/build/calculated-fields)
* [قوالب المستندات](/ar/build/document-templates)
* [اختبار وتشغيل واستكشاف أتمتة KayanOS](/ar/build/automations-test-run-and-troubleshoot)