╔══════════════════════════════════════════════════════════════╗
║   منصة خبرة — دليل التنصيب على cPanel                        ║
╚══════════════════════════════════════════════════════════════╝

  المنصة الآن تعمل بقاعدة بيانات MySQL حقيقية.
  كل تعديل من لوحة التحكم يُحفظ في القاعدة مباشرة ويظهر
  للجميع خلال ثوانٍ — بدون تنزيل أو رفع أي ملف.


═══════════════════════════════════════════════════════════════
  الخطوة ١ — إنشاء قاعدة البيانات
═══════════════════════════════════════════════════════════════

  1. cPanel ← Databases ← MySQL® Databases
  2. New Database: اكتب  khibrah  ← Create Database
     ← سيصبح اسمها الكامل مثل:  CPANELUSER_khibrah
  3. Add New User: اسم مستخدم + كلمة مرور قوية ← Create User
  4. Add User To Database: اختر المستخدم والقاعدة ← Add
  5. علّم على  ALL PRIVILEGES  ← Make Changes

  ✍️ سجّل عندك: اسم القاعدة الكامل · اسم المستخدم الكامل · كلمة المرور


═══════════════════════════════════════════════════════════════
  الخطوة ٢ — رفع الملفات
═══════════════════════════════════════════════════════════════

  1. cPanel ← File Manager ← public_html
  2. Upload ← ارفع  khibrah-platform.zip
  3. كليك يمين على الملف ← Extract  ← ثم احذف ملف الـ zip

  تأكد أن هذه المجلدات موجودة بعد الاستخراج:
     api/        ملفات الخادم
     uploads/    صور المرشحين


═══════════════════════════════════════════════════════════════
  الخطوة ٣ — ضبط الاتصال
═══════════════════════════════════════════════════════════════

  افتح  api/config.php  بمحرر cPanel (Edit) وعدّل:

     'name' => 'CPANELUSER_khibrah',     ← اسم القاعدة الكامل
     'user' => 'CPANELUSER_khibrah',     ← اسم المستخدم الكامل
     'pass' => 'كلمة المرور',

     'app_key' => 'اكتب هنا أي نص عشوائي طويل 64 حرفًا',

  ثم احفظ (Save Changes).


═══════════════════════════════════════════════════════════════
  الخطوة ٤ — التنصيب
═══════════════════════════════════════════════════════════════

  افتح في المتصفح:     https://موقعك/api/install.php

  الصفحة تفحص الخادم وتعرض لك النتائج:
     ✔ إصدار PHP        ✔ إضافة PDO MySQL
     ✔ مجلد uploads      ✔ الاتصال بقاعدة البيانات

  ثم اكتب بيانات المسؤول:
     • اسم المستخدم — حروف لاتينية وأرقام
     • كلمة المرور  — ١٠ أحرف فأكثر، حروف وأرقام
     • علّم على «نقل البيانات الابتدائية من data.js»

  اضغط «تنفيذ التنصيب».

  🔑 كلمة المرور التي تكتبها هنا هي كلمة مرور لوحة التحكم.
     لا توجد كلمة مرور افتراضية — أنت من يختارها.


═══════════════════════════════════════════════════════════════
  الخطوة ٥ — إقفال التنصيب  ⚠️ لا تتجاوزها
═══════════════════════════════════════════════════════════════

  ارجع إلى  api/config.php  وغيّر:

     'allow_install' => true,      ←  إلى     'allow_install' => false,

  بدون هذه الخطوة يستطيع أي شخص إعادة التنصيب وتغيير كلمة المرور.


═══════════════════════════════════════════════════════════════
  الخطوة ٦ — شهادة SSL
═══════════════════════════════════════════════════════════════

  cPanel ← Security ← SSL/TLS Status ← Run AutoSSL

  بدونها تُرسل كلمة المرور عبر الشبكة دون تشفير، وستمنع الواجهة
  البرمجية العمل لأن  force_https  مفعّل في الإعدادات.


═══════════════════════════════════════════════════════════════
  الاستخدام اليومي
═══════════════════════════════════════════════════════════════

  الروابط (تجدها جاهزة في اللوحة ← التصويت ← «روابط المنصة»
   وتُنسخ بضغطة، وتصير صحيحة تلقائيًا بعد النشر):
     /                    الواجهة — المسابقة المعروضة ونتائجها
                          (يظهر مبدّل أعلى الصفحة عند وجود أكثر من مسابقة)
     /display.html        شاشة العرض (ملء الشاشة)
     /login.html          دخول المسؤولين
     /admin.html          لوحة التحكم

  إنشاء مسابقة:
     لوحة التحكم ← المسابقات ← «＋ مسابقة جديدة»
     اكتب الاسم والفترة واختر قالبًا ← إنشاء
     ← تُنشأ كمسودة مخفية، ثم خصّصها من التبويبات:
        القطاعات · أنواع المسابقة · المرشحون · التصويت
        · الجائزة · تخصيص الواجهة
     ← وأخيرًا غيّر الحالة إلى «التصويت مفتوح» أو «النتائج معلنة»

  إدخال المرشحين بجدول Excel:
     التبويب «📊 جدول المرشحين» — بعد ما تصمّم الأنواع والقطاعات:

     ① «⬇️ تنزيل القالب»
        يتولّد ملف مطابق لتصميم هذه المسابقة بالذات:
        عمود لكل مؤشر وضعت له وزنًا، وعمود «النسبة %» إن وُجد
        نوع بلا أوزان. أنواع المسابقة والقطاعات تأتي مملوءة مسبقًا.
        وإن كان فيها مرشحون، ينزل الملف وهم فيه لتعدّلهم في مكانهم.
        كل صف يعبّئ مؤشرات نوعه فقط، ويترك مؤشرات الأنواع الأخرى فارغة.

     ② افتحه بـ Excel واملأ الصفوف.
        الملف يفتح بالعربي مباشرة — لا يحتاج ضبط ترميز.
        عناوين المؤشرات مكتوب عليها «(من 80)» — اكتب النقاط
        التي نالها المرشح من هذا الحد، لا نسبة مئوية.

     ③ «⬆️ رفع الملف بعد تعبئته» ← يظهر المحتوى للمراجعة
        ← «استيراد وإضافة» أو «استبدال مرشحي هذه المسابقة»

     ملاحظات:
       • الصور تُرفع من تبويب «المرشحون» لا من الجدول،
         وصورة المرشح الحالية لا تُمسح عند إعادة الاستيراد.
       • عمود التصويت لا يوجد في القالب لأن أصوات الموظفين
         تُحتسب من القاعدة مباشرة.

  الشريحة التعريفية على شاشة العرض:
     تبويب «البيانات الأساسية» ← «🖼️ الشريحة التعريفية»
       • ارفع صورة المسابقة من جهازك
       • اكتب نبذة تظهر تحت الاسم
       • اضبط مدة عرضها بالثواني

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

  تخصيص الواجهة:
     تبويب «🎨 تخصيص الواجهة» يتحكم بكل ما يراه الموظف:
       • إظهار أو إخفاء: التصويت · التصفية · الأرقام ·
         القطاعات · المؤشرات · الجائزة · صاحب أعلى رقم
       • تعديل ٢٧ نصًا في الصفحة — العناوين والأزرار والتسميات

  التصويت داخل المنصة:
     الموظف يضغط «صوّت له» على البطاقة، يكتب بريده الإلكتروني،
     فيُسجَّل الصوت في قاعدة البيانات مباشرة.

     صوت واحد لكل بريد في كل نوع مسابقة — محمي بقيد فريد في
     القاعدة نفسها، لا يُتجاوز بإعادة فتح المتصفح ولا بمسح الكوكيز.
     البريد يُوحَّد قبل الحفظ، فـ Ahmed@ و ahmed@ شخص واحد.

     في تبويب «التصويت» تضبط:
       • نطاق بريد الشركة — لا يُقبل إلا البريد المنتهي به
       • قائمة بريد محدّدة — للسماح لأشخاص بعينهم فقط

     يظهر فقط عندما يكون مفعّلًا في مكانين معًا:
       ① تبويب «تخصيص الواجهة» ← خيار التصويت
       ② تبويب «التصويت» ← الحالة مفتوح
     ولوحة التحكم تنبّهك إذا أضفت وزن «تصويت» في المؤشرات
     ولم تُفعّل الخيار، أو العكس.

     إعدادات إضافية في تبويب «التصويت»:
       • نظام التصويت: داخل المنصة أو رابط خارجي (Forms)
       • هوية الناخب: البريد الإلكتروني أو بدون
       • إظهار عدّاد الأصوات على البطاقات
       • موعد إغلاق التصويت
       • جدول نتائج التصويت المباشر + زر تصفير الأصوات
       • روابط المنصة الثلاثة جاهزة للنسخ

  احتساب النتيجة — قاعدة واحدة، بلا أي مفتاح تختاره:

     • نوع المسابقة له مؤشرات بأوزان
         الوزن هو أقصى نقاط المؤشر، والرقم الذي تكتبه هو
         ما ناله المرشح من هذه النقاط. النتيجة = مجموعها.

         مثال لنوع التحصيل:
           تحقيق المستهدف    وزنه 80  ← تكتب 80 فينال 80 نقطة
           جودة وعود السداد  وزنه 15  ← تكتب 15 فينال 15 نقطة
           التصويت           وزنه  5  ← من أصوات الموظفين
                                   ─────
           النتيجة                  95  ثم 100 مع التصويت الكامل

         الأعمدة مكتوب عليها «من 80» و «من 15» حتى تعرف الحد.
         ولا تقبل الخانة رقمًا أكبر من الوزن — تُقصّ فورًا.

         نال نصف المستهدف؟ اكتب 40 من 80 فتصير النتيجة 55.

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

     • نوع المسابقة بلا مؤشرات
         النتيجة هي «النسبة %» التي تكتبها بنفسك.

     يعني: أضف أوزانًا فتُحسب، أو اتركها فتكتب النسبة. لا شيء غير ذلك.
     ويمكن أن يجتمع النوعان في مسابقة واحدة بلا تعارض.

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


═══════════════════════════════════════════════════════════════
  الأمان المطبَّق
═══════════════════════════════════════════════════════════════

  كلمات المرور     bcrypt — لا تُحفظ ولا تُقارن كنص صريح أبدًا
  الجلسات          كوكي HttpOnly + Secure + SameSite=Strict
                   وتجديد المعرّف عند الدخول (يمنع تثبيت الجلسة)
  محاولات الدخول   إيقاف تلقائي بعد ٥ محاولات لمدة ١٥ دقيقة
  حقن SQL          استعلامات مُعدّة مسبقًا في كل الاستدعاءات
  CSRF             رمز موقّع مطلوب في كل عملية تعديل
  رفع الصور        فحص الصورة فعليًا لا بالامتداد، اسم عشوائي،
                   ومنع تنفيذ أي سكربت داخل مجلد uploads
  المسودّات        لا تظهر لغير المسجَّلين إطلاقًا
  الرؤوس           CSP · nosniff · X-Frame-Options · HSTS
  سجل التعديلات    جدول exp_audit يسجّل من عدّل ومتى

  ⚠️ ملاحظة مهمة:
     مجلد uploads و ملف data.js عامّان يقرأهما أي زائر.
     لا تضع في المنصة معلومات لا يصح أن يراها كل الموظفين.


═══════════════════════════════════════════════════════════════
  حل المشاكل
═══════════════════════════════════════════════════════════════

  «تعذّر الاتصال بقاعدة البيانات»
     راجع الأسماء في api/config.php — يجب أن تكون كاملة
     مع بادئة حساب cPanel، وتأكد من ربط المستخدم بالقاعدة.

  «يجب استخدام اتصال آمن»
     فعّل SSL، أو اجعل force_https قيمتها false مؤقتًا.

  الموقع يعمل لكن اللوحة لا تحفظ
     افتح api/install.php وتأكد أن كل الفحوصات خضراء.

  الصور لا تُرفع
     اضبط صلاحية مجلد uploads على 755 من File Manager.

  الموقع يعرض بيانات قديمة
     إذا تعطّلت قاعدة البيانات يعرض الموقع نسخة data.js
     الاحتياطية تلقائيًا حتى لا تُظلم الشاشات.

  الرجوع بالبيانات للخلف
     النسخ الاحتياطي من  cPanel ← Files ← Backup.
     كل تعديل في اللوحة يُحفظ في القاعدة مباشرة، ونسخة cPanel
     اليومية تُرجّع كل شيء عند الحاجة.
     ولإلغاء تعديلات لم تُحفظ بعد: اللوحة ← النظام ←
     «↺ إعادة التحميل من القاعدة».


═══════════════════════════════════════════════════════════════
  الملفات
═══════════════════════════════════════════════════════════════

  الواجهة
     index.html · display.html
     login.html · admin.html
     brand.css · core.js · live.js · logo.js
     data.js        نسخة احتياطية تعمل إذا تعطّلت القاعدة

  الخادم
     api/config.php      بيانات الاتصال والأمان  ← تعدّله أنت
     api/install.php     التنصيب والفحص
     api/bootstrap.php   الجلسة والرؤوس الأمنية
     api/helpers.php     التحقق ورموز الحماية
     api/schema.php      بنية الجداول
     api/store.php       القراءة والكتابة
     api/data.php        قراءة البيانات
     api/save.php        حفظ البيانات
     api/login.php · logout.php · session.php
     api/upload.php      رفع الصور
     api/vote.php        تسجيل صوت موظف
     api/votes.php       نتائج التصويت وتصفيرها (للمسؤول)
     uploads/            صور المرشحين

  جداول قاعدة البيانات
     exp_users              المسؤولون
     exp_login_attempts     محاولات الدخول
     exp_settings           إعدادات المنصة
     exp_competitions       المسابقات
     exp_sectors            القطاعات
     exp_categories         أنواع المسابقة
     exp_metrics            المؤشرات وأوزانها
     exp_candidates         المرشحون
     exp_candidate_details  قيم المؤشرات لكل مرشح
     exp_perks              عناصر الجائزة
     exp_votes              أصوات الموظفين
     exp_audit              سجل التعديلات
