# 🚀 دليل نشر حزمة التحديث على الخادم (Production Deployment Guide)
### حزمة تحديث تدقيق وجودة البيانات والمطابقة الزمنية — منصة الهلال للزيارات الطبية
### Al-Hilal Medical Visits Platform — Data Quality & Timezone Update Package

---

## 📦 محتويات حزمة التحديث (Package Contents)

تتضمن هذه الحزمة جميع الملفات المعدلة والجديدة، بالإضافة إلى الأصول المترجمة ومخرجات البناء الجاهزة (`public/build`):

1. **الواجهة الخلفية (Backend & Models)**:
   - `config/app.php`: ضبط المنطقة الزمنية رسمياً إلى `'Asia/Damascus'` (توقيت دمشق UTC+3).
   - `app/Models/Visit.php` و `app/Models/ArchivedVisit.php`: ضبط صب الحقل `visited_at` إلى `'datetime:Y-m-d H:i:s'` لمنع تحويلات التوقيت العالمي UTC من المتصفح.
   - `app/Support/ArabicNormalizer.php`: خوارزميات إزالة الألقاب الطبية (`د.` / `دكتور`) الآمنة، وحماية الأسماء العربية التي تبدأ بحرف الدال (`دريد`، `ديما`، إلخ)، ومعالجة تكرار بادئة العيادات.
   - `app/Services/DataQualityService.php`: محرك فحص وجودة البيانات، مطابقة وتوحيد السجلات، ودمج الأطباء والصيدليات المكررة.
   - `app/Http/Controllers/Admin/DataQualityController.php`: وحدة تحكم مركز جودة البيانات.
   - `app/Http/Controllers/DoctorController.php`: توليد اسم العيادة تلقائياً عند حفظ طبيب جديد.
   - `app/Console/Commands/CleanVisitsCommand.php`: أمر صيانة اختياري لتنظيف سجلات الزيارات.
   - `routes/web.php`: تسجيل مسارات `/admin/data-quality/*`.

2. **الواجهة الأمامية والترجمة (Frontend & Locales)**:
   - `resources/js/pages/Admin/DataQuality/Index.vue`: لوحة تدقيق وجودة البيانات المتكاملة والمتوافقة بالكامل مع الهواتف الذكية (Tabs متساوية، بطاقات إحصائيات متجاوبة، شريط فرعي للتنقل باللمس، عروض مزدوجة للبطاقات والجداول).
   - `resources/js/components/ClientPagination.vue`: ترقيم صفحات مدمج وخاص بشاشات الهواتف المحمولة (`[السابق] [ 1 / 15 ] [التالي]`).
   - `resources/js/components/AppSidebar.vue`: إضافة رابط مباشر لمركز تدقيق وجودة البيانات في القائمة الجانبية.
   - `resources/js/pages/Doctors/Index.vue` و `resources/js/pages/Pharmacies/Index.vue`: أزرار وصول سريع إلى مركز الجودة والتوحيد.
   - `resources/js/composables/useDateFormat.ts`: معالج التواريخ الآمن الذي يمنع انحراف الساعتين (+2h / -2h).
   - `resources/js/locales/ar.json` و `resources/js/locales/en.json`: قواميس الترجمة الكاملة للميزات الجديدة.

3. **حزمة البناء الجاهزة للإنتاج (Pre-compiled Production Assets)**:
   - `public/build/`: الحزمة المترجمة بالكامل بـ Vite، بما في ذلك `manifest.json` وجميع ملفات الـ JS والـ CSS والأيقونات، بحيث **لا تحتاج** لتثبيت Node.js أو تشغيل `npm run build` على خادم الإنتاج!

4. **أداة التنظيف التلقائي بدون Terminal**:
   - `clear_cache.php` و `public/clear_cache.php`: أداة لتنظيف الذاكرة المؤقتة من المتصفح مباشرة دون الحاجة لأي سطر أوامر.

---

## 🛠️ خطوات النشر على الخادم / الاستضافة (cPanel / VPS)

### الخطوة 1: رفع الأرشيف (Upload)
قم برفع ملف الأرشيف المضغوط:
```text
cpanel_update_data_quality_and_timezone.zip
```
إلى المجلد الرئيسي للتطبيق على السيرفر (Root directory للـ Laravel Project، مثل `public_html` أو مجلد المشروع).

---

### الخطوة 2: فك الضغط (Extract)
من خلال **مدير الملفات (File Manager)** في cPanel:
- اضغط بالزر الأيمن على الملف ثم اختر **Extract**.
- تأكد من فك الضغط في مسار المشروع الرئيسي للموافقة على استبدال وتحديث الملفات.

---

### الخطوة 3: تحديث الكاش في حال عدم وجود Terminal (بدائل سطر الأوامر)

إذا كانت استضافتك استضافة مشتركة **ولا تحتوي على Terminal أو SSH**، اختر واحداً من الحلول البسيطة التالية:

#### 🟢 الحل الأول: عبر المتصفح بضغطة زر واحدة (الأسهل والأسرع)
الحزمة تحتوي على ملف أداة مخصص اسمه `clear_cache.php`.
1. افتح المتصفح وتوجه إلى الرابط التالي (مع استبدال النطاق بنطاق موقعك):
   ```text
   https://your-domain.com/clear_cache.php
   ```
   *(أو `https://your-domain.com/public/clear_cache.php` بحسب مسار مجلد public لديك)*
2. ستظهر لك لوحة خضراء تفيد بنجاح تفريغ كاش الإقلاع، وحذف القوالب القديمة، ومطابقة توقيت دمشق `Asia/Damascus`.
3. **أمان**: بعد الانتهاء، احذف ملف `clear_cache.php` من مدير الملفات لحماية موقعك.

---

#### 🔵 الحل الثاني: الحذف اليدوي عبر مدير الملفات (File Manager)
Laravel يقوم بتخزين الكاش في ملفات واضحة داخل مجلدات المشروع. يمكنك مسحها مباشرة:
1. افتح مجلد `bootstrap/cache/` في cPanel:
   - قم بحذف الملفات التالية إن وُجدت:
     - `config.php`
     - `routes-v7.php`
     - `events.php`
     - `services.php`
     - `packages.php`
   *(⚠️ تنبيه: لا تحذف ملف `.gitignore`)*
2. افتح مجلد `storage/framework/views/`:
   - حدد كافة الملفات بداخله واضغط **Delete** (لتنظيف قوالب Blade المخزنة).
3. **النتيجة**: بمجرد حذف هذه الملفات، سيتعرف Laravel فوراً وتلقائياً على ملف `routes/web.php` الجديد وملف `config/app.php` الجديد.

---

#### 🟠 الحل الثالث: عبر المهام المجدولة في cPanel (Cron Jobs)
تتوفر في كل لوحات cPanel أيقونة **المهام المجدولة (Cron Jobs)**:
1. افتح **Cron Jobs** في cPanel.
2. أضف مهمة جديدة تنفذ الأمر لمرة واحدة:
   ```bash
   /usr/local/bin/php /home/USER/public_html/artisan optimize:clear
   ```
   *(مع استبدال المسار بمسار مجلد مشروعك على السيرفر)*
3. بعد دقيقة واحدة، احذف هذه المهمة من قائمة المهام المجدولة.

---

### الخطوة 4: التحقق من الميزات الجديدة على الخادم (Verification)

1. **المنطقة الزمنية (Damascus Timezone UTC+3)**:
   - افتح صفحة الزيارات أو تقارير الزيارات (`/reports`).
   - ستلاحظ فوراً أن أوقات الزيارات مطابقة تماماً للتوقيت المحلي في دمشق دون أي انزياح ساعتين.

2. **مركز تدقيق وجودة البيانات (`/admin/data-quality`)**:
   - توجه إلى الرابط `/admin/data-quality` من القائمة الجانبية أو عبر زر "توحيد المكررات" في دليل الأطباء أو الصيدليات.
   - ستجد الأقسام التالية:
     - **توحيد ألقاب الأطباء (د. / دكتور)**: فحص الأطباء الذين تم تسجيل أسمائهم مسبوقة بـ "د." أو "دكتور"، مع إمكانية توحيد الأسماء بضغطة زر وتحديث عياداتهم ودمج المكررات تلقائياً.
     - **تنظيف عيادات الأطباء المزدوجة**: إزالة تكرار "عيادة د. د." بضغطة زر مع الحماية التامة للأطباء الذين تبدأ أسماؤهم بحرف الدال.
     - **مطابقة ودمج الأطباء والصيدليات المكررة**: دمج السجلات برقم الهاتف أو الاسم المتطابق مع نقل جميع الزيارات والعيادات والمسوحات.

---

**تم إعداد واختبار هذه الحزمة بنجاح 100% بنسبة توافق تامة مع PHP 8.3 و Laravel 13 و Vue 3.**