حسينية العترة الطاهرة — المنصة الرسمية

تطبيق ويب متكامل (Frontend + Backend + Database) لحسينية العترة الطاهرة: تعريف بالحسينية وموقعها، المحاضرات والمجالس، المناسبات، نظام حجز كامل بالفواتير والعربون، التبرعات، المفقودات، معرض الصور، الإشعارات، ولوحة تحكم كاملة لإدارة كل شيء.

عربي بالكامل · RTL · Mobile First · لا يحتاج أي اتصال بالإنترنت للعمل.

---

التشغيل

المتطلب الوحيد: Node.js 22 أو أحدث (لا توجد أي حزم npm للتثبيت).

npm run seed

npm start

العنوان	الرابط
الموقع	http://127.0.0.1:3000/
لوحة التحكم	http://127.0.0.1:3000/admin
فحص الخادم	http://127.0.0.1:3000/api/health

أوامر أخرى:

npm run dev

npm run reset

node --test "tests/*.test.js"

• npm run dev — تشغيل مع إعادة التحميل التلقائي عند تعديل الملفات.
• npm run reset — مسح كل البيانات وإعادة زرع البيانات التجريبية.
• الاختبارات — 33 اختباراً تغطي سيناريو الحجز الكامل والصلاحيات والأمان.

لتغيير المنفذ: PORT=8080 npm start

للنشر على الإنترنت: راجع DEPLOY.md — خطوات الرفع على Vercel مجاناً مع قاعدة بيانات سحابية وتخزين صور ونسخ احتياطي يومي.

---

حسابات الدخول التجريبية

الصلاحية	رقم الهاتف	كلمة المرور
المدير (كل الصلاحيات)	07700000001	admin1234
المشرف	07700000002	admin1234
مستخدم — أبو علي الموسوي	07700000010	user1234
مستخدم — حيدر الكعبي	07700000011	user1234
مستخدم — كاظم الجابري	07700000012	user1234

مهم: غيّر كلمات المرور هذه قبل أي استخدام حقيقي (لوحة التحكم ← المستخدمون).

---

تجربة سيناريو الحجز الكامل

1. سجّل الدخول كمستخدم (07700000010 / user1234).
2. اضغط حجز الحسينية وأكمل الخطوات الست: تاريخ البداية ← عدد الأيام (يُحسب تاريخ النهاية تلقائياً) ← نوع المناسبة ← عدد الحضور ← الطعام ← المراجعة ← الإرسال.
3. تظهر الحالة قيد المراجعة ويصل إشعار للمستخدم وللإدارة.
4. ادخل لوحة التحكم بحساب المشرف ← الحجوزات ← افتح الطلب.
5. حدّد سعر اليوم الواحد وتكلفة الطعام والعربون — يحسب النظام: سعر اليوم × عدد الأيام + تكلفة الطعام = المجموع الكلي، وتُصدر الفاتورة تلقائياً.
6. يرى المستخدم الفاتورة ← الموافقة على السعر ← الحالة بانتظار العربون.
7. إرسال العربون: يختار طريقة الدفع، ينسخ الرقم بزر «نسخ الآن»، يدفع خارج التطبيق، ثم يرفع صورة وصل الدفع → الحالة بانتظار تأكيد العربون.
8. المشرف يفتح الطلب ويضغط قبول العربون → الحالة تم دفع العربون / تم تثبيت الحجز.
9. الفاتورة النهائية تعرض: المجموع الكلي − العربون = المبلغ المتبقي، وزر حفظ الفاتورة / طباعة يخرجها بمقاس إيصال حراري 80mm (قابلة للحفظ PDF على الهاتف).

مثال محسوب في البيانات التجريبية: 100,000 × 3 أيام = 300,000 + طعام 150,000 = 450,000، عربون 150,000 → المتبقي 300,000.

---

شكل المحاضرة

كل محاضرة تُعرض بأربعة أسطر بهذا الترتيب:

اسم المحاضرة:      الشباب رؤية المستقبل
تقديم المحاضرة:    أم سيد محمد الشيرازي
يليها              مجلس عزاء عن أم البنين عليها السلام
الملا:             الملا حوراء

الحقول في لوحة التحكم (المحاضرات ← إضافة محاضرة):

الحقل	الوصف
اسم المحاضرة	العنوان الرئيسي — مطلوب
تقديم المحاضرة	اسم من يُلقي المحاضرة
المجلس الذي يليها	يظهر في الواجهة مسبوقاً بكلمة «يليها» تلقائياً
اسم القارئ / الملا	قارئ مجلس العزاء الذي يلي المحاضرة

الحقلان الأخيران اختياريان — إن تركتهما فارغين لا يظهر سطرهما إطلاقاً. البحث في المحاضرات يشمل اسم القارئ أيضاً.

---

صور التبرع

الصورة	مكانها	الإعداد
بوست التبرع	قسم التبرعات في الصفحة الرئيسية (قابل للنقر ← صفحة التبرعات)	donation_post
بنر التبرع	أعلى صفحة التبرعات	donation_image

كلتاهما تُرفعان من لوحة التحكم ← الإعدادات العامة ← التبرعات.

النسبة المعتمدة 16:7 ومثبّتة في التصميم، فأي صورة تُرفع تبقى بنفس الإطار دون أن يختل شكل الصفحة. إن تُرك البوست فارغاً يُستخدم البنر تلقائياً.

---

شعار الحسينية وأيقونة التطبيق

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

طريقتان لتركيب شعارك:

1. من لوحة التحكم (الأسهل): الإعدادات العامة ← شعار الحسينية ← اختر الصورة ← حفظ. يُطبَّق فوراً في كل مكان.

2. كملف افتراضي: ضع الصورة في public/img/ باسم logo.png (أو .webp / .jpg / .svg) — يكتشفها التطبيق تلقائياً دون أي تعديل في الكود.

الأولوية: الشعار المرفوع من لوحة التحكم ← ملف public/img/logo.* ← النسخة المؤقتة المرفقة.

الصيغة المفضّلة: PNG مربّعة 512×512 بخلفية شفافة أو خضراء داكنة.

---

البنية

server/          الخادم: API، قاعدة البيانات، المصادقة، منطق الحجز
  lib/           db · http · auth · validate · hijri · uploads · settings · notify · booking
  routes/        auth · public · bookings · payments · notifications · admin/*
  db/            schema.sql · seed.js
public/          الواجهة: تطبيق الزائر + لوحة التحكم
  css/           base · app · admin · print
  js/core/       api · router · store · ui · format · hijri · chrome
  js/views/      صفحات الزائر
  js/admin/      صفحات لوحة التحكم
  img/           شعار الحسينية وأيقونة التطبيق وصور التبرع
data/            ملف قاعدة البيانات (SQLite) — انسخه للنسخ الاحتياطي
uploads/         الصور المرفوعة
tests/           اختبارات السيناريو الكامل

تفاصيل المعمارية ومخطط قاعدة البيانات وتدفق الحجز: راجع ARCHITECTURE.md.

---

ما يتحكم به المشرف من لوحة التحكم

لا يوجد أي رقم أو رابط أو سعر مكتوب داخل الكود. كل ما يلي يُدار من اللوحة:

القسم	ما يمكن التحكم به
الإعدادات العامة	اسم الحسينية، الشعار، الوصف، صورة الواجهة، النبذة، العنوان، رابط Google Maps، أرقام الاتصال، العملة، حدود عدد الحضور، أقصى مدة حجز، نسبة العربون، نصوص التنبيهات
روابط التواصل	إنستغرام، فيسبوك، واتساب، الاتصال، البريد — تظهر في الفوتر وصفحة «تواصل معنا»
طرق الدفع	كي كارد، زين كاش، تحويل رصيد — الاسم والرقم/الكود وتعليمات الدفع ونطاق الاستخدام (عربون/تبرع)
الحجوزات	التسعير، العربون، تغيير الحالة، تعديل التواريخ، مراجعة وصولات الدفع، إرسال إشعارات
توفر الحسينية	إغلاق أيام محددة للحجز، ومعاينة التواريخ المحجوزة
المحاضرات	اسم المحاضرة، تقديم المحاضرة، المجلس الذي يليها، اسم القارئ/الملا، التاريخ، الوقت، المناسبة، الوصف، الصورة، الظهور في «المحاضرة القادمة» وفي التقويم
المناسبات	مجلس/مولود/فاتحة/ذكرى وأي نوع آخر
معرض الصور	رفع وحذف وترتيب، تحديد صورة رئيسية، تصنيف (خارج/داخل/مناسبات)
المفقودات	الصورة، الاسم، الوصف، مكان العثور (قابل للإخفاء)، التاريخ، الحالة (متوفر/تم تسليمه)
الإعلانات	صورة، عنوان، وصف، رابط، تاريخ بداية ونهاية، مكان الظهور، تفعيل/إيقاف
التبرعات	حملات التبرع + سجل التبرعات للتقارير
القوائم	أنواع المناسبات (مع خيار «أخرى» الذي يفتح حقلاً نصياً) وخيارات الطعام
المستخدمون	إضافة/تعديل/إيقاف، وتغيير الصلاحيات (للمدير فقط)
الإشعارات	إرسال إشعار لمستخدم محدد أو إشعار عام للجميع
التقارير	الحجوزات بالشهر، الإيرادات، العربونات، المتبقي، تكلفة الطعام، التبرعات، أكثر أنواع المناسبات حجزاً — مع تحديد فترة زمنية وطباعة

---

نظام عرض المناسبات

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

---

حالات الحجز

قيد المراجعة ← بانتظار تعديل السعر ← بانتظار موافقة المستخدم ← بانتظار العربون ← بانتظار تأكيد العربون ← تم دفع العربون ← تم التأكيد ← مكتمل (وفي أي مرحلة مناسبة: ملغي أو مرفوض).

الانتقالات غير المنطقية محجوبة على الخادم — لا يمكن القفز بين الحالات حتى من لوحة التحكم.

---

الأمان

• كلمات المرور مشفّرة بـ scrypt مع ملح عشوائي لكل مستخدم — لا تُخزَّن كنص عادي أبداً ولا تُعاد في أي استجابة.
• الجلسات برموز عشوائية 32 بايت في cookie بخصائص HttpOnly; SameSite=Strict.
• نظام صلاحيات ثلاثي: مستخدم / مشرف / مدير، وكل مسار /api/admin/* محروس.
• تحقق كامل من المدخلات على الخادم مع رسائل خطأ عربية واضحة.
• المستخدم لا يستطيع تعديل السعر أو الحالة أو بيانات حجزه بعد بدء المراجعة.
• أرقام الدفع للقراءة فقط بالنسبة للمستخدمين، وتُعدَّل حصرياً من لوحة التحكم.
• رفع الصور: فحص الامتداد والنوع والتوقيع الثنائي الفعلي (magic bytes)، حد 4MB، اسم ملف عشوائي.
• حماية من XSS (تهريب كل المخرجات)، ومن Path Traversal، وتحديد معدل محاولات الدخول.

---

التخزين والنسخ الاحتياطي

التطبيق يعمل بوضعين تلقائياً حسب متغيرات البيئة — نفس الكود بلا أي تغيير:

الوضع	متى	قاعدة البيانات	الصور
file	محلياً أو على استضافة بقرص دائم	data/husseiniya.db	uploads/
cloud	على Vercel	Upstash Redis	Vercel Blob / Cloudinary

للتحقق من الوضع الحالي: GET /api/health يعيد حقل storage.

النسخ الاحتياطي: مهمة يومية تلقائية (1:00 ليلاً) تحتفظ بآخر 14 نسخة. يدوياً: POST /api/cron/backups، والاستعادة POST /api/cron/backups/restore (للمدير فقط). محلياً تكفي نسخة من data/husseiniya.db وuploads/.

---

التوسع المستقبلي

• الواجهة والـ API منفصلان تماماً — يمكن استبدال الواجهة بـ Next.js/React دون تغيير الخادم.
• استبدال SQLite بقاعدة أخرى يتطلب تعديل server/lib/db.js فقط.
• كل النصوص العربية في طبقة العرض، والبنية جاهزة لإضافة الإنجليزية لاحقاً.