---
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
```