rafeq-backend

Imported from WHABGAMES/rafeq-backend (AGENTS.md). Install upstream with npx skills add WHABGAMES/rafeq-backend. Copyright stays with the author.

قواعد العمل الإلزامية — خادم رفيق

اقرأ هذا الملف وUPDATE_HISTORY.md بالكامل قبل أي تعديل. السجل هو مصدر الحقيقة للتغييرات والإصلاحات السابقة.

جودة الحل

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

التعامل مع المشكلات المجاورة

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

سير العمل والنشر

1. افحص الكود والسجل، واشرح المشكلة وخطة الحل قبل التعديل.
2. «ابدأ» يعني تعديل محلي واختبار فقط.
3. «ارفع» يعني GitHub فقط.
4. «انشر» يعني دمج ونشر وفق إعدادات المشروع.
5. قبل الرفع أو النشر شغّل TypeScript والبناء والاختبارات ذات الصلة.
6. بعد كل تعديل حدّث UPDATE_HISTORY.md: رقم النسخة، التاريخ، الحالة (محلي/مرفوع/منشور/متراجع)، المشكلة، السبب، الحل، الأثر، الرأي، المخاطر، الاختبار، مرجع PR/commit وخطة التراجع. استخدم معرّف مشكلة داخلياً متزايداً بصيغة BE-001 في العنوان ورسالة الـcommit والـPR وأي تعليق تقني ضروري؛ لا تعد استخدام المعرف.
7. رقم النسخة إلزامي ومتزايد: يبدأ التغيير أو الملف الجديد بـ v1، ثم v2 وما بعده مع كل تعديل لاحق عليه، وسجل نسخة كل ملف متأثر بجوار مساره.
8. عند الرفع: انسخ الملخص التشغيلي إلى رسالة الـcommit: عنوان يتضمن معرّف المشكلة ورقم النسخة، ثم نقاط موجزة للمشكلة والحل والتحقق. سجّل النص نفسه في حقل «رسالة الـcommit». لا تكتب SHA أو رابط PR قبل إنشائهما فعلياً.
9. حدّث الحالة التشغيلية في UPDATE_HISTORY.md عند كل انتقال فعلي: بعد push اكتب «مرفوع» مع SHA/PR، وبعد الدمج في main اكتب «مرفوع ومندمج»، وبعد نجاح نشر DigitalOcean وفحص حي مناسب اكتب «منشور في الإنتاج». لا تترك حالة «محلي» بعد الرفع، ولا تدّعِ النشر أو الفحص الحي بلا دليل. راجع السجل بعد كل رفع/نشر وصحّح السجلات المتأثرة في العملية نفسها.
10. بوابة إلزامية قبل الرفع: لا يكفي فحص الملفات المتأثرة. من تثبيت نظيف بالإصدار المحدد في package.json شغّل بالترتيب: npm ci --legacy-peer-deps، ثم npm audit --audit-level=high، ثم ESLint لكامل المشروع (صفر أخطاء؛ وتوثيق أي تحذيرات قائمة)، ثم البناء، ثم كامل الاختبارات، ثم git diff --check. افحص أيضاً أثر التغيير على سلة وزد وعقود Webhooks/OAuth، ولا تدّعِ فحصاً حياً أو تكاملياً بلا دليل.

الأمان

• لا تسجل أو تكرر أسراراً أو tokens أو كلمات مرور.
• لا تضع بيانات حساسة في الاستجابات أو السجلات بلا حاجة.
• حافظ على الحماية الحالية للجلسات وCORS وCSRF والتحقق؛ أي تخفيف لها يحتاج تبريراً وموافقة صريحة.