# Technical Debt
### سجل الديون التقنية — المنصة العالمية للتعريف بالإسلام والتعليم الإسلامي

كل بند أدناه قرار مؤجَّل عمدًا حسب نطاق مرحلة Foundation، أو قيد ناتج عن بيئة التنفيذ الحالية. التصنيف يعكس **الأثر الحقيقي على المشروع في بيئة إنتاج حقيقية**، لا صعوبة الحل.

**مفتاح التصنيف:**
- 🔴 **Critical** — يمنع الانتقال إلى المرحلة التالية أو يمثّل خطرًا مباشرًا.
- 🟠 **High** — يجب حله مبكرًا في Phase 2، قبل أو مع أول ميزة حقيقية.
- 🟡 **Medium** — مهم قبل الإطلاق التجريبي (MVP)، ليس عاجلاً الآن.
- 🟢 **Low** — قرار هندسي واعٍ، يُعاد تقييمه دوريًا دون استعجال.

---

## 🔴 Critical

### 1. Prisma Generate لم يُشغَّل في بيئة هذه الجلسة
**السبب:** بيئة التنفيذ الحالية (Sandbox) لا تملك وصول شبكة إلى `binaries.prisma.sh` (خارج القائمة البيضاء المسموحة).
**الأثر الحالي:** 3 أخطاء TypeScript (`PrismaClient`, `Role` غير مُصدَّرة) في `lib/db.ts`, `lib/auth.ts`, `prisma/seed.ts`.
**هل هذا عيب في المشروع؟** لا. تم إضافة `"postinstall": "prisma generate"` في `package.json`، وسيُحل تلقائيًا وبشكل نهائي بمجرد تشغيل `npm install` في أي بيئة تطوير أو CI بها اتصال إنترنت عادي (وهي 100% من البيئات الحقيقية).
**الحل:** لا يتطلب أي تعديل كود — فقط تشغيل `npm install` في بيئة عادية. **الأولوية Critical هنا مرتبطة بحصر التحقق النهائي في هذه الجلسة فقط، وليست دينًا تقنيًا حقيقيًا على المشروع.**

---

## 🟠 High

### 2. Testing — لا يوجد أي إطار اختبار
**الوضع:** صفر اختبارات وحدة (unit)، تكامل (integration)، أو نهاية-إلى-نهاية (e2e). لا Vitest/Jest/Playwright مثبَّت.
**الأثر:** أي تعديل مستقبلي على `config/permissions.ts` أو `lib/auth.ts` (منطق حسّاس أمنيًا) لا يوجد ما يضمن عدم كسره صامتًا.
**التوصية:** أضف Vitest كإطار اختبار وحدة أول أولوية في بداية Phase 2، قبل أي منطق أعمال جديد، وابدأ بتغطية `hasPermission()` و`getDirection()` كنموذج مرجعي.

### 3. Logging Strategy — لا يوجد Logger هيكلي
**الوضع:** `console.error` فقط في نقاط معدودة؛ لا مستويات سجل، لا معرّف طلب (request id)، لا تكامل مراقبة.
**الأثر:** تشخيص أي عطل إنتاجي مستقبلي سيكون بطيئًا جدًا بدون سياق منظّم.
**التوصية:** أضف `pino` (أو ما يعادله) قبل أول Route Handler حقيقي، مع `request id` مُمرَّر عبر السياق.

### 4. CI/CD Pipeline غير موجود
**الوضع:** لا يوجد `.github/workflows/` أو معادله. سكربتات `lint`/`typecheck`/`build` جاهزة لكن غير مُشغَّلة آليًا.
**الأثر:** لا حماية تلقائية تمنع دمج كود مكسور.
**التوصية:** إضافة workflow أساسي واحد يشغّل الأوامر الأربعة (`install`, `lint`, `typecheck`, `build`) على كل PR — يمكن تنفيذه بمعزل عن Phase 2 بجهد منخفض جدًا.

### 5. Google Fonts — فشل الجلب في بيئة هذه الجلسة فقط
**السبب:** بيئة التنفيذ الحالية تحجب `fonts.googleapis.com`.
**الأثر:** فشل `next build` في هذه الجلسة تحديدًا عند مرحلة تحميل الخطوط.
**هل هذا عيب في المشروع؟** لا — تم التحقق (عبر استبدال مؤقت بالخطوط) أن باقي خط أنابيب البناء (Compile + Type-check + Bundling) يعمل بنجاح تام. أي بيئة حقيقية بوصول إنترنت عادي (dev machine أو CI عادي) ستُحمِّل الخطوط بنجاح دون أي تعديل.
**الحل:** لا شيء مطلوب من الكود. مُدرَج هنا للشفافية والتوثيق فقط.

### 6. رؤوس الأمان (Security Headers) غير مُهيَّأة
**الوضع:** لا CSP، لا HSTS، لا X-Frame-Options في `next.config.ts`.
**الأثر:** يجب إضافتها قبل تفعيل أي Provider مصادقة حقيقي أو نشر أي صفحة عامة.
**التوصية:** أضِف كائن `headers()` في `next.config.ts` كخطوة تحضيرية للنشر (Production Readiness)، ليست جزءًا من "ميزة" جديدة.

---

## 🟡 Medium

### 7. Redis Integration غير مفعّل فعليًا
**الوضع:** `lib/redis.ts` جاهز (اتصال كسول، `cacheGet`/`cacheSet`) لكن `REDIS_ENABLED=false` افتراضيًا ولا يوجد استخدام فعلي في أي مسار.
**التوصية:** فعّله عند إضافة أول مسار API يحتاج تخزينًا مؤقتًا فعليًا (على الأرجح بيانات القرآن/الحديث عالية القراءة في Phase 2).

### 8. OpenSearch/Elasticsearch Integration غير مفعّل
**الوضع:** `lib/search.ts` يحتوي على واجهة (`SearchClient`) محايدة تجاه المزوّد فقط، بدون أي مكتبة عميل مثبَّتة بعد.
**التوصية:** يُحسم القرار (OpenSearch مقابل Elasticsearch) ويُنفَّذ في مرحلة "Search" من Phase 2 Roadmap، بعد استقرار نماذج المحتوى (لا معنى للفهرسة قبل وجود بيانات).

### 9. S3 / Object Storage — لا بيانات اعتماد حقيقية
**الوضع:** `lib/storage.ts` مكتمل الكود، لكن `STORAGE_*` env vars فارغة (لا bucket فعلي مُزوَّد بعد).
**التوصية:** مهمة تزويد بنية تحتية (Infra Provisioning)، لا كود — تُنفَّذ عند الحاجة الفعلية لرفع أول ملف وسائط.

### 10. Background Jobs / Queue System غير موجود
**الوضع:** لا BullMQ أو معادله. لا حاجة إليه الآن (لا مهام غير متزامنة فعلية بعد: لا بريد، لا فهرسة، لا معالجة وسائط).
**التوصية:** يُضاف عند الحاجة الفعلية الأولى (مرشّح واضح: إعادة فهرسة المحتوى في OpenSearch بعد كل نشر/تعديل، أو إرسال بريد ترحيبي عبر nodemailer المثبَّت مسبقًا).

### 11. Global Error Boundaries غير موجودة
**الوضع:** لا `app/[locale]/error.tsx` ولا `not-found.tsx` مخصص.
**التوصية:** إضافتهما ملفات بنيوية بسيطة يمكن اعتبارها استكمالًا للأساس قبل أي محتوى فعلي، منخفضة الجهد.

### 12. Rate Limiting غير موجود
**الوضع:** لا حماية من الطلبات المفرطة على أي مسار (لا حاجة الآن، لا مسارات فعلية).
**التوصية:** يُضاف مع أول Route Handler حقيقي، خصوصًا `/api/auth/*` وأي مسار بحث لاحقًا.

---

## 🟢 Low

### 13. next-auth v4 (مستقر) بدل v5 (beta)
**السبب:** قرار واعٍ ومقصود — المستخدم طلب صراحة "أحدث إصدار مستقر"، وv5 لا يزال beta.
**إعادة التقييم:** عند استقرار Auth.js v5 رسميًا (خروجه من beta)، يستحق تقييم الترقية لواجهته الأحدث (`auth()` بدل `getServerSession`).

### 14. Prisma v6.19.3 بدل v7
**السبب:** قرار واعٍ — v7 يحتوي تغييرات جذرية (ESM إجباري، driver adapters إجبارية) وخطأ موثّق مع Turbopack + Next.js 16 حتى تاريخ هذه المراجعة.
**إعادة التقييم:** خلال 3–6 أشهر، تحقّق من استقرار v7 مع Turbopack قبل الترقية.

### 15. Email Provider (nodemailer) مثبَّت لكن غير مُستخدَم
**السبب:** ضروري فقط لحل تعارض Peer Dependency أمني؛ لا Email Provider مُفعَّل في `lib/auth.ts` بعد.
**إعادة التقييم:** عند تفعيل أول Auth Provider في Phase 2.

### 16. لا يوجد Prettier / lint-staged / Husky
**السبب:** خارج نطاق "البنية التقنية الأساسية" الصريح لهذه المرحلة.
**إعادة التقييم:** إضافة منخفضة الجهد، مرشّحة لأي وقت قبل انضمام أكثر من مطور واحد للمشروع.

---

## ملخّص عددي

| التصنيف | العدد |
|---|---|
| 🔴 Critical | 1 (بيئي بحت، يُحل تلقائيًا خارج هذه الجلسة) |
| 🟠 High | 5 |
| 🟡 Medium | 6 |
| 🟢 Low | 4 |
| **الإجمالي** | **16** |

لا يوجد أي دين تقني في القائمة أعلاه ناتج عن قرار هندسي متسرّع — كل بند إما (أ) قيد بيئي موثّق وسيُحل تلقائيًا، أو (ب) قرار مؤجَّل عمدًا لأنه خارج نطاق Phase 1 المتفَّق عليه.