feat: add comprehensive code review guidelines and checklist

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

@@ -0,0 +1,136 @@
+---
+name: code-review
+description: 'مراجعة الكود وإصلاح الأخطاء في مشروع SaaS-PDF. استخدم عند: تشخيص مشكلة، مراجعة ملف أو ميزة، إصلاح خطأ، التحقق من الأمان (OWASP)، تغطية الاختبارات، أداء الكود، توافق Frontend/Backend. Use when: code review, bug fix, security audit, performance check, test coverage, logic review.'
+argument-hint: 'اذكر الملف أو الميزة أو المشكلة المراد مراجعتها'
+---
+
+# مراجعة الكود وإصلاح الأخطاء — 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. التحقق من عمل المشروع بالكامل
+بعد الإصلاح، شغّل هذه الأوامر:
+```bash
+# 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 |
+
+## أوامر مفيدة
+
+```bash
+# تشغيل اختبار واحد
+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
+```