تطبيق اتحاد طلاب كلية التمريض — جامعة الريادة

PWA عربية (RTL) لاتحاد الطلاب: أخبار، فعاليات ومؤتمرات مع تسجيل حضور، استطلاعات، ميديا، لجان وأعضاء، ترتيب الطلاب، إشعارات، ولوحة تحكم للأدمن.

التقنيات

• HTML / CSS / JavaScript عادي (من غير build)
• Firebase Auth + Firestore (SDK compat)
• Cloudinary لرفع الصور (unsigned preset)
• Service Worker + Web App Manifest

هيكل المشروع

index.html            الصفحة الوحيدة
css/style.css         الستايل
js/01-core.js         Firebase + مستمعات Firestore + تسجيل دخول الأدمن
js/02..13-*.js        الأقسام (استطلاعات، ميديا، أنشطة، أخبار، أدمن، إشعارات، تهيئة)
js/14-students-insights.js  ملفات الطلاب، التفاعل (مين صوّت/أعجب/سجّل)، التقييم التلقائي، كارت الطالب
js/17-certificate.js  شهادات الحضور PDF (قالب بيرفعه الأدمن + اسم الطالب تلقائي)
sw.js                 Service Worker (رقم النسخة بيتغيّر تلقائي)
firestore.rules       قواعد أمان Firestore
firebase.json         إعداد نشر الـ rules
scripts/bump-sw.sh    تغيير نسخة الكاش يدوي
.github/workflows/    CI + تحديث نسخة الـ SW

التشغيل محلياً

أي سيرفر ملفات ثابتة يكفي (الـ Service Worker محتاج http وليس file://):

npx serve .

الإعداد

1. عدّل firebase-config.js ببيانات مشروع Firebase وCloudinary. (مفتاح Firebase للويب مش سر، لكن قيّده بالدومينات من Google Cloud Console → Credentials → HTTP referrers.)
2. فعّل Auth providers (Google و/أو Email-Password).
3. انشر القواعد:

   npm i -g firebase-tools
   firebase login
   firebase deploy --only firestore:rules
   

الأدمن

الصلاحيات الحقيقية في firestore.rules، والواجهة بس بتخفي/تظهر اللوحة. الأدمن هو:

• إيميل مؤكَّد (email_verified) من القايمة في firestore.rules وADMIN_EMAILS في js/01-core.js، أو
• مستخدم له وثيقة admins/{uid} (تتضاف من Firebase Console بس، الكتابة من التطبيق ممنوعة).

لو بتدخل بإيميل/باسورد وإيميلك مش مؤكد: ادخل بجوجل أو أضف وثيقة admins/{uid}.

الطلاب والتقييم التلقائي

• لوحة التحكم ← الطلاب وملفاتهم: افتح أي طالب: غيّر صورته ونبذته ونقاطه، شوف نشاطه، أو اجعله طالب الأسبوع.
• التفاعل والإحصائيات: مين صوّت وعلى إيه، مين أعجب بكل خبر، مين مهتم/مسجل في كل فعالية.
• التقييم التلقائي: النقاط بتتحسب من التصويت والإعجاب والاهتمام والتسجيل (القيم من الإعدادات). التحديث بيتم لما أدمن يفتح اللوحة (مرة كل 6 ساعات) أو بزر «حدّث التقييم دلوقتي»؛ بيتحسب بالفرق فمفيش تكرار، والنقاط اليدوية ونقاط الحضور ما بتتأثرش.
• الترتيب العام بيتغذى من collection leaderboard (اسم + صورة + نقاط بس، من غير إيميل أو رقم جامعي). ولو عايز تخفي طالب: علّم «إخفاء من الترتيب» في ملفه.

شهادات الحضور

الشهادة قالب بتصمّمه إنت (إنجليزي أو أي لغة، بالشكل واللوجو والنصوص والختم والتوقيع اللي إنت عايزه) والتطبيق بيكتب اسم الطالب بس تلقائياً ويطلّعها PDF.

• الرفع: لوحة التحكم ← الطلاب ← «شهادات الحضور». ارفع القالب كصورة PNG/JPG (الأفضل عرض 2000 بكسل أو أكتر؛ ملفات PDF مش مدعومة، صدّرها صورة). الصور الكبيرة جداً بتتصغّر تلقائي.
• مكان الاسم: اضغط أو اسحب على الصورة، واختار الخط (Great Vibes / Playfair Display / Cinzel / Montserrat / Amiri) والحجم واللون والمحاذاة وأقصى عرض (الاسم الطويل بيصغّر نفسه) وخيار الحروف الكابيتال. زر «معاينة PDF» بيوريك الناتج النهائي.
• قالب افتراضي لكل الفعاليات، وقالب خاص لفعالية (مثلاً مؤتمر باسمه وتاريخه) وبيكسب على الافتراضي.
• الطالب: بعد ما الأدمن يسجّل حضوره (QR أو يدوي) بيظهر له زر «شهادة الحضور (PDF)» في نافذة الفعالية، بس لو فيه قالب. الملف A4 أفقي أو رأسي حسب القالب.
• الاسم بيتاخد من ملف الطالب زي ما هو مسجّل (الأسماء العربي بتتكتب بخط أميري تلقائي).
• التخزين: config/certificate للافتراضي وactivities/{id}.certificate للخاص (الكتابة للأدمن بس، من غير تغيير في firestore.rules).

النشر وتحديث النسخة

أي push على main بيغيّر ملفات التطبيق بيشغّل workflow بيحدّث CACHE_NAME في sw.js تلقائي. ولو بتشتغل محلياً: sh scripts/bump-sw.sh.

ملاحظات

• المستمعات في 01-core.js محدودة بـ limit() (مثلاً الأخبار 300) عشان القراءات تفضل محدودة.
• عند إضافة ملف JS/CSS جديد ضيفه في ASSETS في sw.js (الـ CI بيتأكد إنه موجود).

الاختبارات التلقائية

بتشتغل لوحدها في GitHub Actions مع كل Pull Request، وتقدر تشغّلها عندك:

npm install
npm test

بتحمّل كل ملفات js/ بنفس ترتيب index.html زي المتصفح، وتفحص: الملفات المسجّلة في الـ Service Worker، الـ IDs المكررة، الدوال المعرّفة مرتين، الكود اللي بينادي دالة لسه متحمّلتش، رسم الشاشات الأساسية، وسيناريو "نت بطيء" (سباق التحميل).