# 📖 الدليل الشامل لمشروع القرآن الكريم وموقع التحميل
## Sacred Serenity Quran Project & Landing Website Guide

هذا الملف يحتوي على **كافة التفاصيل الهندسية والبرمجية** لتطبيق القرآن الكريم وموقع الويب، ليكون مرجعاً شاملاً عند الرغبة في التعديل أو التطوير أو نقل المشروع لأي مطور أو وكيل ذكاء اصطناعي (AI Agent).

---

## 🗂️ 1. هيكل المجلدات وتوزيع الملفات (Project Locations)

تم تنظيم المشروع داخل مجلد `Documents` في جهازك إلى مجلدين مستقلين تماماً:

```text
📁 C:\Users\212\Documents\
├── 📁 Quran-App/                   <-- تطبيق الكمبيوتر والمصحف الشريف التفاعلي
│   ├── index.html                 (الواجهة الرئيسية للتطبيق)
│   ├── css/
│   │   └── styles.css             (نظام التصميم Sacred Serenity، الدارك مود، الخطوط)
│   ├── js/
│   │   ├── app.js                 (المحرك البرمجي: البحث، التلاوة، مواقيت الصلاة، الختمات)
│   │   ├── quranData.js           (بيانات السور الـ 114، الأجزاء، والقراء الـ 15)
│   │   └── azkarData.js           (أذكار الصباح والمساء وحصن المسلم والتسابيح)
│   └── icons/                     (أيقونات التطبيق للويندوز)
│
├── 📁 Quran-Web/                   <-- موقع الويب التعريفي وصفحة التحميل
│   ├── index.html                 (صفحة الموقع والـ Landing Page)
│   └── downloads/
│       └── quran-app.zip          (حزمة التطبيق المضغوطة الجاهزة للتحميل الفوري)
│
└── 📄 QURAN_PROJECT_MASTER_GUIDE.md <-- هذا الملف المرجعي الشامل
```

---

## ⚙️ 2. التفاصيل الفنية والبرمجية (Architecture & Modules)

### 🕌 أ. محرك مواقيت الصلاة والأذان (Prayer Times Module)
* **المسار**: `Quran-App/js/app.js` -> دالة `fetchPrayerTimes()` و `startPrayerCountdownTicker()`.
* **طريقة العمل**:
  - يتصل بواجهة `https://api.aladhan.com/v1/timingsByCity` لحساب مواقيت الصلاة بدقة حسب المدينة المختارة مع طريقة حساب الهيئة العامة المصرية للمساحة.
  - يحتوي على معالج ذكي للوقت الحالي يحسب الصلاة القادمة تلقائياً بدقة (الفجر، الشروق، الظهر، العصر، المغرب، العشاء).
  - عداد تنازلي لحظي مباشر يحدث كل ثانية بتنسيق عربي كامل (`متبقي: ٠١:٢٠:٤٥`).
  - تظليل تلقائي ديناميكي لوقت الصلاة القادمة بلون زمردي متوهج.

### 🔍 ب. محرك البحث الشامل في آيات وسور القرآن (Search Engine)
* **المسار**: `Quran-App/js/app.js` -> دالة `renderSurahsList()` و `searchQuranVerses()`.
* **طريقة العمل**:
  - يحتوي على دالة `normalizeArabic(text)` لتطبيع النصوص العربية وتجاهل التشكيل والهمزات (`أ إ آ` -> `ا`, `ة` -> `ه`, `ى` -> `ي`).
  - يبحث في أسماء السور ورقمها والترجمة الإنجليزية.
  - يبحث في **نصوص آيات القرآن كاملاً (6236 آية)** عبر واجهة `api.alquran.cloud/v1/search`.
  - يظلل الكلمات المبحوث عنها داخل نص الآية (`<mark>`).
  - يتيح الاستماع المباشر للآية أو فتح السورة والانتقال لمكان الآية فوراً.

### 🎧 ج. محرك التلاوة والاستماع وتشغيل السورة كاملة (Audio Engine)
* **المسار**: `Quran-App/js/app.js` -> دالة `playAyahAudio()` و `playFullSurah()`.
* **طريقة العمل**:
  - خوادم صوتية عالية الجودة `everyayah.com` تدعم 15 قارئاً من كبار قراء العالم الإسلامي (كالشيخ ياسر الدوسري، مشاري العفاسي، عبد الباسط عبد الصمد، الحصري، المنشاوي، ماهر المعيقلي، السديس، الشريم، إلخ).
  - ميزة **«استماع للسورة كاملة»**: تشغيل متتابع للآيات آية تلو الأخرى دون انقطاع مع متابعة التمرير التلقائي (Auto-Scroll) وتظليل الآية الحالية.

### 📊 د. نظام الختمة القرآنية المباركة (Khatmah Tracker)
* **المسار**: `Quran-App/js/app.js` -> دالة `initKhatmahModule()`.
* **نوعان من الختمات**:
  1. **ختمة القراءة**: خطط متعددة (30، 60، 90 يوماً)، قائمة مرجعية تفاعلية لكل السور، تتبع أيام المداومة (Streak)، وتحديد الورد اليومي.
  2. **ختمة الاستماع**: اختيار القارئ المفضل ومتابعة السور المسموعة.
  3. **دعاء ختم القرآن**: نافذة منبثقة بنص دعاء الختم المبارك عند إتمام الختمة.

### 📿 هـ. قسم الأذكار والتسابيح والمسبحة الإلكترونية
* **المسار**: `Quran-App/js/azkarData.js` & `app.js`.
* **طريقة العمل**:
  - أذكار الصباح، أذكار المساء، أذكار بعد الصلاة، أذكار النوم والاستيقاظ، وأدعية قرآنية مع فضل كل ذكر وعداد نقرات ذكي بأصوات تفاعلية لطيفة (Web Audio API).
  - مسبحة إلكترونية مستقلة لحفظ عدد التسبيحات في الذاكرة المحلية.

### 🎨 و. التصميم ونظام الألوان (Sacred Serenity Design System)
* **المسار**: `Quran-App/css/styles.css`.
* **الأنماط المتوفرة**:
  1. **النمط الداكن الفاخر (Sacred Emerald Dark)**: خلفية ليلية `#060a08` / `#0f1714`، حدود زمردية `#10b981`، ولمسات ذهبية `#fbbf24` مع نصوص ناصعة البياض عالية التباين.
  2. **النمط الورقي الهادئ (Sepia / Parchment)**: مستوحى من ورق المصاحف القديمة لراحة العين.
  3. **النمط الفاتح (Light)**.

---

## ☁️ 3. خطوات رفع الموقع على Cloudflare Pages (مجاناً 100%)

خدمة **Cloudflare Pages** تمنحك استضافة سريعة جداً ومجانية مدى الحياة مع شهادة حماية SSL ورابط خاص بك.

### 📋 الطريقة المباشرة بالرفع السريع (Direct Upload - بدون كتابة أوامر):

1. **إنشاء حساب مجاني**:
   - افتح موقع: [https://dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) وسجل حساباً مجانياً.

2. **الدخول إلى قسم Pages**:
   - من القائمة الجانبية اليسرى اختر **Workers & Pages**.
   - اضغط على زر **Create Application**.
   - اختر تبويب **Pages** ثم اضغط على **Upload assets** (رفع الملفات مباشرة).

3. **تسمية المشروع ورفع المجلد**:
   - اكتب اسم المشروع (مثال: `quran-app` أو `sakina-quran`).
   - اضغط على **Select folder to upload** أو اسحب المجلد:
     👉 `C:\Users\212\Documents\Quran-Web`
   - اضغط على **Deploy site**.

4. **مبروك! موقعك أصبح أونلاين**:
   - خلال 10 ثوانٍ سيعطيك Cloudflare رابطاً رسمياً مثل:
     `https://quran-app.pages.dev`
   - يمكنك إرسال هذا الرابط لأصدقائك فوراً ليفتحوا الموقع ويحملوا التطبيق أو يستخدموه أونلاين!

---

## 💡 4. نصائح عند طلب تعديلات مستقبلية
عندما تريد تعديل أي شيء مستقبلاً، يمكنك ببساطة إرفاق هذا الملف `QURAN_PROJECT_MASTER_GUIDE.md` في المحادثة مع تحديد طلبك، وسيفهم المساعد الذكي بنية المشروع كاملة في أجزاء من الثانية!
