SaaS-PDF/.github/skills/code-review/SKILL.md

name, description, argument-hint

name	description	argument-hint
code-review	مراجعة الكود وإصلاح الأخطاء في مشروع SaaS-PDF. استخدم عند: تشخيص مشكلة، مراجعة ملف أو ميزة، إصلاح خطأ، التحقق من الأمان (OWASP)، تغطية الاختبارات، أداء الكود، توافق Frontend/Backend. Use when: code review, bug fix, security audit, performance check, test coverage, logic review.	اذكر الملف أو الميزة أو المشكلة المراد مراجعتها

مراجعة الكود وإصلاح الأخطاء — SaaS-PDF

متى تُستخدم هذه المهارة

• عند الإبلاغ عن خطأ أو مشكلة في الكود
• عند مراجعة ملف أو خدمة أو endpoint محدد
• عند إضافة ميزة جديدة والتحقق من جودتها
• عند الرغبة في تقرير شامل بالأخطاء والتوصيات

---

الخطوات المتبعة

1. فهم المشكلة والسياق

• اقرأ المعطيات الأولية: رسالة الخطأ، الملف المعني، السلوك المتوقع مقابل الفعلي.
• ابحث في قاعدة الكود بحثاً مستهدفاً (لا تفترض — تحقق).
• حدد نطاق التأثير: هل المشكلة في backend/، frontend/، أم في كليهما؟

2. البحث عن أفضل حل حديث

• قارن الحلول المتاحة بناءً على:
  • التوافق مع الإصدار الحالي من المكتبات (requirements.txt / package.json)
  • أفضل الممارسات لعام 2025+
  • أقل تعقيد وأكبر صيانة
• اختر الحل الأكثر مباشرةً دون هندسة مفرطة.

3. قائمة التحقق الشاملة

الأمان (OWASP Top 10)

• لا يوجد SQL Injection أو NoSQL Injection
• لا يوجد XSS أو CSRF غير محمي
• التحقق من صحة المدخلات على الـ backend (لا تثق في الـ frontend فقط)
• لا توجد بيانات حساسة مكشوفة في الاستجابات أو logs
• الجلسات ورموز JWT محمية بشكل صحيح
• لا توجد أذونات مفرطة في المسارات المحمية

معايير الكود

• يتبع الكود أسلوب backend/ الحالي (Flask Blueprints, Services pattern)
• يتبع الكود أسلوب frontend/ الحالي (Vite/TypeScript, custom hooks)
• لا توجد وظائف متكررة موجودة مسبقاً في services/ أو utils/
• أسماء المتغيرات والدوال واضحة ومعبّرة

الاختبارات

• يوجد اختبار وحدة يغطي السلوك الجديد أو المُصلَح
• اختبارات backend: cd backend && python -m pytest tests/ -q
• اختبارات frontend: cd frontend && npx vitest run
• لا يوجد اختبار مكسور قبل أو بعد التغيير

الأداء

• لا توجد استعلامات N+1 أو عمليات تكرارية غير ضرورية
• الملفات الكبيرة تُعالَج بشكل منقسم (streaming/chunked)
• لا يوجد blocking I/O في Celery tasks
• استجابة الـ API ضمن الحدود الطبيعية

منطق الأعمال

• السلوك يتطابق مع المتطلبات الموثقة في docs/
• حالات الحافة (edge cases) معالجة (ملف فارغ، مستخدم غير مسجل، إلخ)
• رسائل الخطأ مفيدة للمستخدم وليست كاشفة للنظام

توافق Frontend/Backend

• نقاط النهاية (endpoints) متطابقة بين routes/ والاستدعاءات في frontend/src/
• هياكل البيانات المُرسَلة والمُستقبَلة متوافقة
• رموز HTTP الصحيحة مستخدمة (200, 201, 400, 401, 403, 404, 422, 500)

4. تطبيق الإصلاح

• طبّق أصغر تغيير ممكن يحل المشكلة.
• لا تعيد هيكلة كود لم يُطلب تغييره.
• اختبر التغيير فوراً بعد تطبيقه.

5. التحقق من عمل المشروع بالكامل

بعد الإصلاح، شغّل هذه الأوامر:

# Backend
cd backend && python -m pytest tests/ -q

# Frontend
cd frontend && npx vitest run

# Full stack (إن كان Docker متاحاً)
docker compose up --build

6. إنتاج التقرير

أنتج تقريراً يحتوي على:

## تقرير مراجعة الكود

### الملفات المراجعة
- [اذكر الملفات]

### المشاكل المكتشفة
| الأولوية | المشكلة | الملف | السطر | الحل المقترح |
|----------|---------|-------|-------|--------------|
| عالية    | ...     | ...   | ...   | ...          |

### الإصلاحات المطبقة
- [ما تم إصلاحه بالفعل]

### توصيات لاحقة
- [مشاكل غير حرجة تستحق المعالجة لاحقاً]

### نتائج الاختبارات
- Backend: ✅ / ❌
- Frontend: ✅ / ❌

---

هيكل المشروع (مرجع سريع)

الطبقة	المسار	التقنية
Backend	backend/app/routes/	Flask Blueprints
Services	backend/app/services/	Python classes
Tasks	backend/app/tasks/	Celery
Tests	backend/tests/	pytest
Frontend	frontend/src/	Vite + TypeScript + React
API hooks	frontend/src/hooks/	Custom React hooks

أوامر مفيدة

# تشغيل اختبار واحد
cd backend && python -m pytest tests/test_<name>.py -v

# فحص أخطاء TypeScript
cd frontend && npx tsc --noEmit

# عرض تغطية الاختبارات
cd backend && python -m pytest tests/ --cov=app --cov-report=term-missing