# المدجنة — ميديا هب

> وثيقة تعريفية موجهة لمحركات البحث والأنظمة الذكية. الروابط التي تبدأ بـ `https://modajana.com` تستبدل بعنوان الموقع العام الفعلي.

## التعريف

المدجنة منصة عربية مستقلة لتوثيق ونشر الفيديوهات والصور والمقالات والمواد المرتبطة بالأشخاص والتصنيفات. الواجهة عربية من اليمين إلى اليسار، والمحتوى العام قابل للقراءة والفهرسة دون تسجيل دخول.

## أهداف الموقع

- تنظيم المحتوى المرئي والمقروء في منشورات قابلة للبحث والأرشفة.
- ربط المنشور بالأشخاص والتصنيفات مع صفحات أرشيف مستقلة.
- الحفاظ على روابط المنشورات القديمة القادمة من ووردبريس.
- تقديم أدوات تحرير وإدارة للعنوان والمحتوى والوسائط والتاريخ والنشر.

## أنواع المنشورات

- `article`: مقال نصي أو توثيقي.
- `video`: فيديو مرفوع إلى الموقع أو رابط فيديو خارجي.
- `gallery`: منشور صورة أو معرض صور.
- `pdf`: ملف بي دي إف.

لكل منشور عنوان ورابط فريد وحالة نشر وتاريخ نشر اختياري وصورة مصغرة، وقد يرتبط بأكثر من شخص وأكثر من تصنيف. المنشور ذو التاريخ المستقبلي يبقى مخفيًا عن الواجهة العامة وخريطة الموقع حتى يحين موعده.

## الصفحات العامة

- الصفحة الرئيسية: `https://modajana.com/`
- صفحة المنشور: `https://modajana.com/{slug}`
- دليل الأشخاص: `https://modajana.com/persons`
- صفحة الشخص ومنشوراته: `https://modajana.com/person/{slug}`
- صفحة التصنيف ومنشوراته: `https://modajana.com/category/{slug}`
- خلاصة آر إس إس: `https://modajana.com/rss.xml`
- خريطة الموقع: `https://modajana.com/sitemap.xml`
- ملف تعريف الموقع للأنظمة الذكية: `https://modajana.com/llms.txt`
- سياسة الزحف: `https://modajana.com/robots.txt`

## تجربة الصفحة الرئيسية

تعرض الصفحة الرئيسية شريط أحدث المحتوى، ولوحة تصفية حسب نوع المحتوى والتصنيف والشخص، وبطاقات المنشورات، ورسالة يومية، وقسمًا للمحتوى القريب، مع دعم البحث العام والوضع الليلي والتصميم المتجاوب.

## المحتوى المختلط

المقال يمكن أن يجمع نصوصًا وصورًا وتعليقات وعناوين واقتباسات وروابط في ترتيب واحد. يحفظ هذا المحتوى ككتل JSON ذات إصدار داخل الحقل الحالي مع دعم المحتوى القديم، وتُنظف شيفرة HTML عند العرض العام لمنع العناصر التنفيذية.

## المشاهدات والتفاعلات

- مشاهدات المنشور تحفظ في قاعدة بيانات PostgreSQL وتظهر في بطاقة المنشور وصفحته.
- عداد الصفحة الرئيسية مستقل عن عدادات المنشورات.
- يمنع النظام تكرار احتساب الزائر نفسه خلال نافذة زمنية، بدل احتساب كل إعادة تحميل كزيارة جديدة.
- التفاعلات العامة لا تحتاج إلى حساب، ولكل نوع تفاعل عداد مستقل.
- توجد حماية من الإغراق على نقطة إضافة التفاعلات، وتوحّد الواجهة أرقام التفاعل القادمة من المصدر نفسه.

## إدارة المنشورات

لوحة الإدارة محمية بتسجيل دخول، وتدعم إنشاء وتعديل وحذف المنشورات، رفع الفيديو والصور والملفات، الروابط الخارجية، الصورة المصغرة، الأشخاص، التصنيفات، حالة المسودة أو النشر، وجدولة تاريخ النشر. رفع الفيديو الكبير يعمل في الخلفية مع حفظ التقدم.

## الأشخاص والتصنيفات

يمكن ربط منشور بعدة أشخاص وعدة تصنيفات، مع الاحتفاظ بالعلاقة الأولى للتوافق مع البيانات القديمة. يمكن إنشاء شخص أو تصنيف من داخل محرر المنشور، وتوجد صفحات عامة للأرشفة والتحرير السريع للأشخاص من لوحة الإدارة.

## الفيديو والتفريغ والصور

- خدمة فاستر وسبير تفرغ صوت الفيديو إلى نص عربي عند توفرها.
- عند توقف خدمة التفريغ، يستخدم الخادم مسارًا احتياطيًا عبر جيميناي إذا كان مضبوطًا في إعدادات الذكاء الاصطناعي.
- استخراج الصورة المصغرة يتم على الخادم بواسطة إف إف إم بيغ من الثانية 1.5، مع محاولة احتياطية عند الثانية 0.5 للفيديو القصير.
- يمكن إعادة استخراج الصورة المصغرة من محرر المنشور.
- المهام الجماعية للتفريغ والمصغرات قابلة للإيقاف والاستئناف وإعادة ضبط التقدم من لوحة الإدارة.

## الذكاء الاصطناعي

تبويب الذكاء الاصطناعي في لوحة الإدارة يسمح بتعديل النموذج والبرومبت والمفتاح المحفوظ مشفرًا. يستخدم جيميناي من أجل:

- تصحيح النص المفرغ إملائيًا ولغويًا مع الحفاظ على المعنى.
- إنشاء تعليق أو رد مرتبط بالنص أو الصورة.
- قراءة النص الظاهر في الصورة عند الحاجة.
- تفريغ الفيديو احتياطيًا عند عدم توفر خدمة فاستر وسبير.

تظهر أخطاء المفتاح والحصة والمهلة والاتصال برسائل عربية واضحة، ولا تُعرض المفاتيح السرية كاملة في الواجهة.

## النشر عبر تيليجرام

يوجد مسار اختياري للنشر عبر بوت تيليجرام. يحمي الخادم الويب هوك برأس سري، ويقيّد المستخدمين المسموح لهم، ويحفظ الوسائط في التخزين المحلي ويعرضها عبر مسار الوسائط العام.

## البحث والإشعارات

البحث العام يدعم العنوان والمحتوى والوسوم والأشخاص والتصنيفات مع حماية من الطول والمعدل. يدعم الموقع إشعارات الويب عبر ويب بوش عند ضبط الإعدادات اللازمة.

## تحسين الظهور والأرشفة

- خريطة موقع رئيسية تجمع خرائط المنشورات والصور والفيديو والأشخاص والتصنيفات والصفحات الثابتة.
- خرائط فيديو تتضمن بيانات الفيديو والصورة المصغرة والعنوان.
- تغذية آر إس إس وبيانات وصفية للصفحات العامة.
- تحويلات دائمة من مسارات ووردبريس القديمة.
- يسمح `robots.txt` بالوصول إلى المحتوى العام وملفات الخريطة و`llms.txt`، ويمنع لوحة الإدارة وواجهات البرمجة الخاصة.

## البنية التقنية

- واجهة: ريأكت وفايت وتايلويند، مع تصميم عربي متجاوب وتطبيق ويب تقدمي.
- خادم: نود وإكسبريس.
- قاعدة البيانات: بوستجري إس كيو إل مع درزل.
- الوسائط: تخزين دائم داخل `STORAGE_PATH`، وتقدم خدمات الفيديو والتفريغ من الخادم.
- النشر: دوكر كومبوز، ويمكن تشغيله عبر كوليفاي.
- المستودع أحادي البنية، وتوجد الواجهة داخل `artifacts/media-hub` والخادم داخل `artifacts/api-server` والمكتبات المشتركة داخل `lib`.

## نقاط النهاية العامة المهمة

- `GET /api/healthz`: فحص صحة الخادم.
- `GET /api/posts/home`: بيانات الصفحة الرئيسية.
- `GET /api/posts`: قائمة المنشورات والبحث والتصفية.
- `GET /api/posts/{slug}`: تفاصيل منشور.
- `GET /api/persons` و`GET /api/persons/{slug}`: الأشخاص وأرشيفاتهم.
- `GET /api/categories` و`GET /api/categories/{slug}`: التصنيفات وأرشيفاتها.
- `POST /api/page-views`: تسجيل زيارة وفق حماية التكرار.
- `POST /api/reactions`: إضافة تفاعل عام مع تحديد المعدل.

## نقاط الإدارة

نقاط تسجيل الدخول وإدارة المنشورات والأشخاص والتصنيفات والوسائط والتفريغ والمصغرات والذكاء الاصطناعي خاصة بلوحة الإدارة وتتطلب مصادقة. لا تُدرج بيانات الدخول أو المفاتيح أو الأسرار في هذا الملف.

## مصدر الحقيقة والتحديث

هذا الملف هو الوصف العام المرجعي للموقع. عند إضافة ميزة أو تغيير مسار أو تعديل طريقة احتساب أو نشر أو تخزين، يجب تحديث هذا الملف في نفس التغيير، ثم تحديث خريطة الموقع واختبار `llms.txt` و`robots.txt` و`sitemap.xml` قبل الدمج والنشر.