# سِيَر أعلام المعاصرين — مرجع الموقع للأنظمة الذكية والمطورين

آخر تحديث: 2026-09-10
إصدار الوثيقة: 1.0.2
الرابط القانوني: https://alsear.com/
اللغة والاتجاه: العربية، من اليمين إلى اليسار.

## 1. تعريف الموقع

«سِيَر أعلام المعاصرين» أرشيف رقمي مفتوح لتراجم الشخصيات المعاصرة. يعرض معلومات عن علماء ودعاة وسياسيين وقراء قرآن وأزهريين وشخصيات من مجالات أخرى، مع تصنيفات ووسوم وبيانات سيرة منظمة عند توفرها.

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

## 2. الجمهور والاستخدام المقصود

- الزائر العام: البحث في السير وقراءتها وحفظ روابط مختارة محليًا في متصفحه.
- الباحث ومحرك البحث: الوصول إلى صفحات ثابتة وروابط قانونية وبيانات منظمة وخريطة موقع ديناميكية.
- المحرر: إدارة المقالات والوسائط والتصنيفات وتحسين الظهور والذكاء الاصطناعي من لوحة محمية.
- المطور: صيانة تطبيق خادمي واحد وقاعدة بيانات بوستغرس وتخزين وسائط دائم.

لا يجوز اعتبار كل مادة منشورة حكماً نهائياً أو بديلاً عن الرجوع إلى المصادر الأصلية. بعض المقالات تتضمن تقويماً أو تصنيفاً فكرياً للشخصيات وفق سياسة الموقع التحريرية.

## 3. الروابط العامة الأساسية

- `/` — الصفحة الرئيسية.
- `/{publicId}` — صفحة سيرة منشورة؛ المعرّف العام ثابت من ستة رموز إنجليزية صغيرة أو أرقام.
- `/category/{slug}` — أرشيف تصنيف، مع ترقيم الصفحات عبر `?page=N`.
- `/tag/{slug}` — أرشيف وسم، مع ترقيم الصفحات عبر `?page=N`.
- `/media/{filename}` — ملف وسائط مخزّن في التخزين الدائم.
- `/robots.txt` — سياسة الزحف العامة.
- `/sitemap.xml` — خريطة الموقع الديناميكية.
- `/llms.txt` — هذا المرجع.
- `/health` — حالة عملية الخادم واتصال قاعدة البيانات.
- `/config` — المسار الأساسي وعنوان واجهة البرمجة العام إن ضُبط.

لوحة الإدارة موجودة لكنها غير مفهرسة، ومسارها غير موثق في هذا الملف العام عمداً. عدم نشر المسار ليس بديلاً عن الحماية؛ الدخول نفسه محمي بجلسة وكلمة مرور.

## 4. الصفحة الرئيسية

تعرض الصفحة الرئيسية البيانات الحقيقية المنشورة في قاعدة البيانات، وتشمل:

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

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

## 5. صفحة السيرة

صفحة السيرة تعرض عند توفر البيانات:

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

يسجل الخادم مشاهدة الصفحة حتى إن كان جافاسكربت معطلاً. فشل تسجيل المشاهدة لا يمنع عرض المقال.

## 6. التصنيفات والوسوم

- كل أرشيف يعرض 12 بطاقة في الصفحة.
- لا تظهر إلا المقالات ذات الحالة `PUBLISHED`.
- الترتيب هو الأحدث نشراً أولاً.
- التصنيف علاقة واحدة اختيارية لكل مقال.
- الوسوم علاقة متعدد إلى متعدد، ويمكن إنشاء وسم جديد تلقائياً من محرر المقال.
- دمج تصنيفين ينقل المقالات إلى الهدف ويحذف المصدر داخل معاملة واحدة وينشئ تحويلة للرابط القديم عند توفر معرّف ووردبريس.

## 7. البحث والمحفوظات

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

## 8. نموذج المحتوى وحالات المقال

حالات المقال:

- `DRAFT` — مسودة غير عامة.
- `SCHEDULED` — مجدول في البيانات.
- `PUBLISHED` — منشور ويظهر في الصفحات والخريطة.
- `TRASHED` — حذف منطقي قابل للاستعادة كمسودة.

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

الحالة المجدولة وموعدها محفوظان، لكن لا توجد حالياً خدمة طابور أو عامل خلفي ينشر المجدول تلقائياً. لا ينبغي وصف النشر المجدول بأنه مؤتمت قبل إضافة عامل فعلي واختباره.

## 9. الوسائط

- الأنواع المقبولة: صور جيه بي إي جي وبي إن جي وويب بي وجيف، وفيديو إم بي 4.
- الحد الأقصى للملف 15 ميغابايت.
- التحقق يعتمد النوع الحقيقي لمحتوى الملف، لا الامتداد المعلن.
- الصور الجديدة تتحول إلى ويب بي بجودة 82 مع الحفاظ على الأبعاد.
- أسماء الملفات الجديدة عشوائية من ستة رموز صغيرة أو أرقام.
- يمكن رفع ملف أو جلب صورة من رابط ويب.
- الجلب الخارجي له مهلة عشر ثوان وحد للحجم وتحقق من النوع.
- ملفات الإنتاج في `/app/media` ومربوطة بوحدة تخزين دائمة في كوليفاي.
- السجل يحفظ المصدر والاسم الأصلي والنوع والحجم والأبعاد والنص البديل والرابط الأصلي وحالة الملف المفقود.

## 10. الروابط القديمة والترحيل من ووردبريس

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

وسيط التحويلات يعمل قبل المسارات الجديدة. طلبات `?p=` و`?cat=` و`?tag=` المعروفة وروابط `wp-content/uploads` القديمة تتحول بالحالة 301. يزداد عداد استخدام التحويلة عند تنفيذها.

سكربتات الاستيراد قابلة لإعادة التشغيل دون تكرار السجلات، وتعتمد معرّفات ووردبريس القديمة للمطابقة.

## 11. المشاهدات وتصنيف الزوار

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

## 12. لوحة الإدارة

قدرات لوحة الإدارة المحمية:

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

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

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

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

## 14. تحسين الظهور والفهرسة

- عنوان ووصف ورابط قانوني فريد لكل صفحة عامة.
- بيانات أوبن غراف وبطاقات تويتر وصورة مشاركة عند توفرها.
- بيانات منظمة من نوع `Person` عند وجود ملف سيرة، وإلا `Article`.
- مسار تنقل منظم من نوع `BreadcrumbList`.
- خريطة ديناميكية تشمل الرئيسية و`llms.txt` وكل مقال منشور وكل تصنيف وكل وسم.
- المقالات تحمل تاريخ آخر تعديل في الخريطة.
- ملف الروبوتات يسمح بالزحف العام ويصرح صراحة بملف `llms.txt` وموقع الخريطة.
- الصفحات غير الموجودة تعيد الحالة 404 فعلياً.

## 15. الحماية والخصوصية

- ترويسات أمان أساسية عبر هيلمت.
- سياسة أمن المحتوى الصارمة غير مفعلة حالياً لاعتماد الواجهة على مكتبة تصميم من شبكة توزيع وسكربتات مضمّنة.
- جلسة الإدارة موقعة بإتش ماك ومدتها سبعة أيام.
- ملف تعريف الارتباط مخفي عن جافاسكربت وآمن في الإنتاج وسياسة الموقع نفسه مرنة.
- تسجيل الدخول محدود بعشر محاولات لكل عنوان خلال 15 دقيقة.
- الطلبات العامة تحت `/api` محدودة بستين طلباً في الدقيقة.
- عمليات الإدارة المغيرة للبيانات محمية من تزوير الطلبات.
- محتوى المقال ينظف بقائمة عناصر وخصائص وأنماط مسموحة.
- إطارات الفيديو تقبل من يوتيوب وفيميو فقط.
- الخادم في الإنتاج يرفض البدء إذا غاب سر الجلسة أو مفتاح التشفير.
- الأسرار ومتغير اتصال قاعدة البيانات لا تحفظ في المستودع أو هذا الملف.

## 16. واجهات البرمجة العامة

- `POST /api/articles/{publicId}/view` — تسجيل مشاهدة وإرجاع نتيجة التسجيل ونوع الزائر.
- `GET /api/articles/{publicId}/views` — الإجمالي التاريخي والحي والتوزيع حسب نوع الزائر.
- `GET /health` — يعيد 200 ما دامت عملية نود حية، مع `db.configured` و`db.connected`. يجب فحص قيمة الاتصال لا الرمز وحده.
- `GET /config` — يعيد `basePath` و`apiBaseUrl` فقط.

المسارات الإدارية ليست واجهة عامة ولا ينبغي استخدامها آلياً دون جلسة وصلاحية ورمز حماية صحيح.

## 17. التقنية والبنية

- بيئة التشغيل نود 24، واللغة تايب سكربت بوضع صارم.
- الخادم إكسبريس 4، وقاعدة البيانات بوستغرس مع بريزما 6.
- العرض صفحات إتش تي إم إل مولدة على الخادم مع جافاسكربت خفيف.
- السجلات بينو، والصور شارب، والتحرير كويل، والتعقيم بمكتبة تنظيف إتش تي إم إل.
- البناء صورة حاوية متعددة المراحل على نود 24 ألباين، والتشغيل بمستخدم غير الجذر.
- النشر من جت هب إلى كوليفاي خلف ترايفك ونفق كلاود فلير.
- المنفذ الداخلي 3000، والتخزين الدائم لقاعدة البيانات و`/app/media`.
- بداية الحاوية تطبق `prisma migrate deploy` ثم تشغل الخادم.

## 18. متغيرات البيئة

- `PORT` — منفذ الخادم، افتراضياً 3000.
- `NODE_ENV` — يجب أن يكون `production` في الإنتاج.
- `DATABASE_URL` — رابط بوستغرس.
- `SESSION_SECRET` — سر توقيع الجلسات، إلزامي في الإنتاج.
- `ENCRYPTION_KEY` — مفتاح مستقل لتشفير الأسرار، إلزامي في الإنتاج.
- `SITE_ORIGIN` — الأصل القانوني؛ إنتاجياً `https://alsear.com`.
- `BASE_PATH` — مسار أساسي اختياري؛ الإنتاج الحالي على الجذر.
- `API_BASE_URL` — عنوان واجهة منفصل مستقبلياً.
- `LOG_LEVEL` — مستوى السجلات.
- `VIEW_IP_HASH_SALT` — تمليح تجزئة عناوين الزوار ويجب تغييره في الإنتاج.

## 19. قاعدة البيانات

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

الحذف للمقال منطقي. بعض العلاقات التابعة تحذف تلقائياً وفق المخطط، والعمليات المركبة المهمة تستخدم معاملة قاعدة بيانات.

## 20. لقطة البيانات وقت إعداد الوثيقة

لقطة بيئة التطوير بتاريخ 2026-09-10:

- 130 مقالاً إجمالاً: 129 منشوراً ومسودة واحدة.
- لا مقالات مجدولة ولا مقالات في السلة.
- 144 سجل وسائط، و22 تصنيفاً، و95 وسماً.
- 245 تحويلة قديمة، ومستخدم واحد.
- 30,698 مشاهدة ضمن المجاميع وقت اللقطة.

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

## 21. هيكل الشيفرة

- `src/server.ts` — تركيب الحماية والمسارات والملفات ومعالجة الأخطاء والإغلاق المنظم.
- `src/routes/pages.ts` — الرئيسية والسيرة والتصنيفات والوسوم.
- `src/routes/seo.ts` — الروبوتات وخريطة الموقع.
- `src/routes/admin*.ts` — الدخول وإدارة المقالات والتصنيفات والذكاء الاصطناعي.
- `src/views/` — قوالب الصفحات والمكونات الخادمية.
- `src/modules/` — منطق المقالات والإدارة والدخول والوسائط والمشاهدات والذكاء الاصطناعي.
- `src/middleware/` — التحويلات والدخول والحماية من تزوير الطلبات.
- `prisma/schema.prisma` و`prisma/migrations/` — المخطط والترحيلات.
- `scripts/import/` و`scripts/test/` — الاستيراد والاختبارات.
- `public/` — الملفات العامة ومنها هذا الملف.
- `media/` — الوسائط الأولية والدائمة وقت التشغيل.
- `Dockerfile` — بناء وتشغيل الإنتاج.

## 22. الاختبار والنشر

بوابة التحقق الدنيا لأي تطوير:

1. `npm ci` عند الحاجة.
2. `npx prisma generate` عند تغير المخطط.
3. `npm run build`.
4. اختبار الصحة والرئيسية ومقال والوسائط.
5. فحص `/llms.txt` و`/robots.txt` و`/sitemap.xml`.
6. التأكد من وجود `https://alsear.com/llms.txt` في الخريطة.
7. رفع الفرع الرئيسي وانتظار نشر كوليفاي السليم.
8. التحقق من الموقع الحي، لا الاكتفاء بالبناء أو الرفع.

## 23. القيود الحالية

- لا توجد ريدس أو خدمة طابور خلفي.
- النشر المجدول مخزن لكنه غير مؤتمت.
- حد استخدام الذكاء الاصطناعي اليومي غير مفروض برمجياً.
- فروق الصلاحيات الدقيقة بين الأدوار غير مطبقة.
- إدارة التحويلات من اللوحة للقراءة فقط.
- الواجهة تعتمد شبكة توزيع للتصميم والخطوط وسياسة أمن المحتوى الصارمة مؤجلة.
- بحث الرئيسية يضمن بطاقات كل المقالات وقد يحتاج بحثاً خادمياً عندما يكبر الأرشيف.
- فحص الصحة يعيد 200 حتى عند تعطل القاعدة؛ يجب قراءة `db.connected`.

## 24. قاعدة الصيانة

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