نموذج تشخيص خطأ برمجي وطلب إصلاحه

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

أجزاء التقرير التسعة

1. الملخّص

سطر واحد يقول ماذا يحدث وأين: «زر تأكيد الطلب لا يستجيب على آيفون في صفحة الدفع». لا «مشكلة في الموقع».

2. خطوات إعادة الإنتاج

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

3. المتوقّع مقابل الفعلي

جملتان منفصلتان: ما كان يجب أن يحدث، وما حدث فعلًا. كثير من «الأخطاء» يتبيّن أنها اختلاف في التوقّع؛ كتابة المتوقّع تكشف ذلك مبكرًا.

4. البيئة

الجهاز، نظام التشغيل، المتصفح وإصداره، التطبيق أو الموقع (تجريبي أو حقيقي)، الحساب أو الدور (بلا كلمة مرور)، الوقت التقريبي لحدوث الخطأ ومنطقته الزمنية، وهل بدأ بعد تغيير معيّن.

5. الأدلة والسجلات الآمنة

لقطة شاشة أو تسجيل قصير، ونص رسالة الخطأ كما هو (منسوخًا لا مُعاد كتابته)، والأسطر ذات الصلة من السجل أو من لوحة المطوّر في المتصفح. قبل الإرسال، نظّف السجلات:

• المفاتيح والرموز استُبدلت بـ[محذوف] أو بقيمة وهمية بالشكل نفسه.
• أسماء العملاء وأرقامهم وعناوينهم وبريدهم أُخفيت أو استُبدلت.
• روابط الاتصال بقاعدة البيانات، وملفات تعريف الجلسة، ورؤوس التفويض حُذفت.
• لقطات الشاشة لا تُظهر كلمات مرور محفوظة، أو إشعارات خاصة، أو بيانات عميل.
• أرسلت الأسطر المتعلّقة بالخطأ فقط، لا ملف السجل كاملًا.

6. المثال الأدنى

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

7. ما جرّبته

ما فعلته حتى الآن ونتيجته: «مسحت ذاكرة المتصفح: لا تغيير»، «على كروم يعمل»، «بدأ بعد تحديث يوم الثلاثاء». هذا يوفّر على من يصلح تكرار ما جُرّب.

8. قيود الإصلاح

ما لا يجوز لمسه أو تغييره: «لا تغيّر منطق الدفع»، «لا تضف مكتبات جديدة»، «حافظ على الاتجاه من اليمين إلى اليسار»، «لا تغيّر بنية قاعدة البيانات». أدوات الذكاء الاصطناعي تميل إلى إعادة كتابة أكثر مما يلزم؛ القيود تحصر الإصلاح في مكانه.

9. فحص عدم التراجع

بعد الإصلاح لا يكفي أن يختفي الخطأ؛ يجب ألّا يظهر خطأ جديد. اكتب مسبقًا: خطوات إعادة الإنتاج نفسها يجب أن تعطي النتيجة المتوقّعة، وقائمة قصيرة بما يجب أن يبقى يعمل (الوظائف القريبة من الإصلاح)، واختبارًا آليًا يمنع عودة الخطأ إن أمكن.

قالب تقرير الخطأ

الملخّص: [ماذا يحدث وأين، في سطر واحد]
الخطورة: [يمنع العمل / يعيق جزئيًا / شكلي]      التكرار: [دائمًا / أحيانًا / مرة]

خطوات إعادة الإنتاج:
1. [افتح الرابط .. بحساب بدور ..]
2. [..]
3. [..]

المتوقّع: [..]
الفعلي: [..]

البيئة: الجهاز [..] | النظام [..] | المتصفح والإصدار [..]
        البيئة [تجريبية / حقيقية] | الدور [..] | الوقت والمنطقة الزمنية [..]
        بدأ بعد: [تغيير أو تحديث إن وُجد]

الأدلة (بعد التنظيف): [لقطة / تسجيل / نص رسالة الخطأ / أسطر السجل]
المثال الأدنى: [الملف أو الدالة + أقل بيانات تُظهر الخطأ]
ما جرّبته: [الإجراء ← النتيجة]

قيود الإصلاح: [ما لا يجوز تغييره]
فحص عدم التراجع: [ما يجب أن يبقى يعمل بعد الإصلاح]

قالب طلب الإصلاح من أداة ذكاء اصطناعي

أنت مطوّر حذر. أمامك تقرير خطأ ومثال أدنى من الكود.
المطلوب بالترتيب:
1) اشرح السبب الأرجح في 3 أسطر، واذكر إن كنت غير متأكد وما الذي يؤكّده.
2) اقترح أصغر تغيير يصلح الخطأ، في الملفات المذكورة فقط.
3) التزم بقيود الإصلاح حرفيًا. إن رأيت أن قيدًا يمنع الإصلاح، قل ذلك ولا تتجاوزه.
4) اكتب اختبارًا يفشل قبل الإصلاح وينجح بعده.
5) اذكر ما قد يتأثّر بالتغيير لأختبره يدويًا.
لا تعِد كتابة ملفات كاملة، ولا تضف مكتبات، ولا تغيّر التنسيق أو الأسماء خارج الإصلاح.

التقرير: [الصق التقرير]
الكود: [الصق المثال الأدنى بعد استبدال أي مفتاح أو بيانات حقيقية بقيم وهمية]

بعد الإصلاح

مثال مكتمل

الملخّص: زر «تأكيد الطلب» لا يستجيب على آيفون في صفحة الدفع عند اختيار موعد توصيل.
الخطورة: يمنع العمل (لا يمكن إتمام الطلب)      التكرار: دائمًا على آيفون

خطوات إعادة الإنتاج:
1. افتح المتجر من سفاري على آيفون، بلا تسجيل دخول.
2. أضف «صابون زيت الزيتون» إلى السلة واضغط «إتمام الشراء».
3. عبّئ الاسم والهاتف بقيم تجريبية، واختر موعد توصيل «غدًا 10:00».
4. اضغط «تأكيد الطلب».

المتوقّع: تظهر صفحة «تمّ استلام طلبك» برقم الطلب.
الفعلي: لا يحدث شيء. الزر لا يتغيّر ولا تظهر رسالة.

البيئة: آيفون | iOS محدّث | سفاري | الموقع الحقيقي | زائر بلا حساب
        بدأ بعد إضافة حقل «موعد التوصيل» الأسبوع الماضي.

الأدلة: تسجيل شاشة 15 ثانية. من لوحة المطوّر (بعد التنظيف):
  RangeError: Invalid time value  at checkout.js:88
  POST /api/orders  لم يُرسَل
  Authorization: Bearer [محذوف]

ما جرّبته: على كروم في الحاسوب وأندرويد يعمل. بلا اختيار موعد يعمل على آيفون.

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

// checkout.js (excerpt)
function buildOrder(form) {
  const slot = form.deliveryDate + ' ' + form.deliveryTime;   // "2026-09-22 10:00"
  return {
    items: form.items,
    deliverAt: new Date(slot).toISOString(),                  // line 88
  };
}

قائمة الإنجاز قبل الإرسال

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