# QURAN_CONTENT_MANAGEMENT_REPORT.md
### تقرير إدارة محتوى القرآن — Phase 11, Module 2.1

**الحالة العامة: ✅ مكتمل ومُتحقَّق منه فعليًا (Lint + TypeCheck + Build + تشغيل خادم حقيقي).**
**لا Prisma، لا API، لا حفظ حقيقي — بيانات وهمية بالكامل في `lib/mock/admin-quran.ts`.**

---

## 1. الصفحة المنفَّذة

| الصفحة | المسار |
|---|---|
| إدارة محتوى القرآن | `/admin/quran` |

**لم تُبنَ أي صفحة أخرى لأنواع محتوى أخرى** (حديث، مقالات، فتاوى...) — التزامًا حرفيًا بحدود هذه الوحدة.

---

## 2. قرار معماري جوهري: ماذا يدير الجدول فعليًا؟

**الجدول يدير سجلات ترجمة/تفسير الآيات (شبيهة بـ`QuranTranslation`/`Tafsir`)، لا نص الآية العربي الثابت نفسه (`Verse`).** السبب: `Verse` بيانات مرجعية (النمط B، `Content Models §1.3`) **بلا سير عمل نشر أصلاً** — لا معنى لأزرار "مراجعة/نشر/أرشفة" على نص مصحف ثابت. الترجمة/التفسير تخضعان للنمط A الكامل (Draft→Review→Scholarly Review→Published→Archived) وتحملان مراجعًا فعليًا — وهذا بالضبط ما طلبته هذه المرحلة (حالة + آخر مراجع + نشر/أرشفة). قرار يحقق طلب المستخدم حرفيًا **دون** التناقض مع حساسية النص القرآني المقرَّرة في وثائق سابقة (`Database Migration Strategy`, `Content Models`).

---

## 3. المكوّنات الجديدة

### 3.1 النظام العام لجدول البيانات (`components/admin/data-table/`) — **النموذج القياسي لكل صفحات الإدارة القادمة**

| المكوّن | الوصف |
|---|---|
| `DataTable<T>` | جدول عام (TypeScript Generics) — أعمدة، فرز، تحديد متعدد، مبني بالكامل فوق `Table` من Phase 8 |
| `DataTableToolbar` | بحث + فلاتر + عدد نتائج + زر إنشاء + إجراءات جماعية |
| `BulkActionsBar` | شريط إجراءات جماعية يظهر عند التحديد |
| `RowActions` | 5 أزرار إجراء صف (عرض/تعديل/مراجعة/نشر/أرشفة) بمنطق تعطيل حسب صحة انتقال الحالة |
| `DataTableSkeleton` | حالة التحميل |
| `DataTableEmpty` | حالة "لا نتائج" (يعيد استخدام `EmptyState` من Phase 9.5) |
| `DataTableError` | حالة خطأ جاهزة (غير مُفعَّلة حيًا — انظر §6) |

### 3.2 عام عبر كل المحتوى (لا خاص بالقرآن)

`StatusBadge` (`components/admin/status-badge.tsx`) — شارة الحالات الخمس، **لن تُعاد كتابتها لأي نوع محتوى لاحق**.

### 3.3 خاص بالقرآن فقط

`QuranContentTable` (المنسِّق الرئيسي)، `QuranTableFilters` — هذان فقط سيُستبدَلان بمكافئيهما لكل نوع محتوى لاحق (`HadithContentTable`, `ArticlesTableFilters`...)، بينما القسمان أعلاه (3.1، 3.2) يبقيان كما هما حرفيًا.

---

## 4. المكوّنات المُعاد استخدامها

**من Phase 8:** `Table` (+كل الأجزاء الفرعية)، `Checkbox`, `Label`, `Button`, `IconButton`, `SearchInput`, `Skeleton`, `Badge`, `Pagination`.
**من محرك المحتوى (Phase 9.5):** `EmptyState`.
**من طبقة الأساس:** `useToast`.

---

## 5. قرارات معمارية جديدة

1. **إعادة اكتشاف نمط "Server Component عبر Props" بشكل استباقي — ثم رفضه لصالح حل أنظف:** بدأت بجعل `StatusBadge` مكوّن Server غير متزامن (متسقًا مع بقية المشروع)، لكن اكتُشف فورًا (قبل التشغيل الفعلي، أثناء التصميم) أنه سيُستخدَم داخل جدول تفاعلي يُحدِّث حالة الصف محليًا عند النقر — ومكوّن Server غير متزامن لا يمكن أن يُعاد تصييره تفاعليًا. **الحل هنا مختلف عن Phase 9.5/10 عمدًا:** بدل تمرير عناصر جاهزة التصيير عبر Props (الحل السابق)، حُوِّل `StatusBadge` نفسه إلى Client Component بسيط (`useTranslations` بدل `getTranslations`) — لأن الحاجة هنا هي *تفاعلية حقيقية للمكوّن نفسه* (تغيّر لونه/نصه حسب حالة تتبدَّل)، لا مجرد عرض ساكن يحتاج فقط تفاديًا لقيد الاستيراد. اختيار الحل الصحيح من بين حلَّين معروفين حسب طبيعة المشكلة تحديدًا، لا تطبيق حل سابق بلا تمييز.
2. **`DataTable` عام عبر TypeScript Generics لا عبر شرط `if (type === "quran")`:** أي صفحة إدارة لاحقة تمرر `columns`/`rows` بنوعها الخاص فقط — صفر تعديل على `DataTable` نفسه متوقَّع لأي نوع محتوى مستقبلي.
3. **انتقالات الحالة محكومة منطقيًا لا حرة:** زر "نشر" مُعطَّل برمجيًا ما لم تكن الحالة `SCHOLARLY_REVIEW` بالضبط — حتى في واجهة تجريبية بلا حفظ حقيقي، لم يُسمَح بتمثيل اختصار للاعتماد العلمي بصريًا.
4. **`DataTableError` مبني لكن غير مُفعَّل حيًا (صادق لا وهمي):** لا وجود لطلب شبكة حقيقي يمكن أن يفشل في نطاق هذه المرحلة (`ممنوع API` صراحة) — المكوّن جاهز ومُصدَّر، ويُستدعى فعليًا فقط حين تُستبدَل `mockQuranContentRows` باستدعاء حقيقي قابل للفشل لاحقًا.

---

## 6. نتائج التحقق

| الفحص | النتيجة |
|---|---|
| `npm run lint` | ✅ صفر أخطاء **من أول تشغيل** |
| `npx tsc --noEmit` | ✅ صفر أخطاء جديدة **من أول تشغيل** |
| `npm run build` | ✅ "Compiled successfully" |
| **تشغيل خادم فعلي + `curl`** | ✅ `HTTP 200` لـ`/ar/admin/quran` و`/en/admin/quran` |
| محتوى HTML الفعلي | ✅ كل عناوين الأعمدة السبعة، كل الحالات الخمس، شريط الأدوات كاملاً (بحث/تصفية/إنشاء)، والترقيم الفعلي (96 نتيجة) مؤكَّدة مباشرة في HTML الخام |

---

## 7. الخلاصة

النموذج القياسي (`DataTable`, `DataTableToolbar`, `BulkActionsBar`, `RowActions`, `StatusBadge`, وحالات التحميل/الفراغ/الخطأ) جاهز الآن ومُختبَر فعليًا، بحيث تصبح صفحات إدارة الحديث/المقالات/الفتاوى/الكتب/الدروس/الدورات/الوسائط القادمة عملية "تبديل بيانات وأعمدة" بحتة لا بناءً من الصفر — تحقيقًا حرفيًا للهدف المُعلَن من هذا التقسيم. بانتظار موافقة صريحة قبل Module 2.2.