# 🌱 Modular Seeders & Universal Data Ingestion Guide

The application features a decoupled, modular seeding pipeline and an enterprise **Universal Data Import Center** designed for rapid bulk onboarding of healthcare directories across new governorates.

---

## 1. Modular Seeders Architecture

The master seeder (`DatabaseSeeder.php`) delegates to dedicated domain seeders in a strict dependency sequence:

```mermaid
graph TD
    A["1. RoleAndPermissionSeeder\n(Spatie Roles & Gates)"] --> B["2. AdminUserSeeder\n(Super Admin: admin@alhilal.sy)"]
    B --> C["3. GovernorateAreaSeeder\n(14 Govs + 202 Areas)"]
    C --> D["4. SpecialtySeeder\n(23 Canonical Specialties)"]
    D --> E["5. DosageFormSeeder\n(10 Dosage Forms)"]
    E --> F["6. ProductCategorySeeder\n(3 Product Categories)"]
    F --> G["7. ProductSeeder\n(13 Al-Hilal Products)"]
    G --> H["8. DoctorSeeder\n(816 Doctors + Phone Match + Workplaces)"]
    H --> I["9. PharmacySeeder\n(897 Pharmacies + Hospital Flags)"]
```

---

## 2. CLI Execution Commands

### Complete Production Seeding
To run the full automated pipeline:
```bash
php artisan db:seed
```

To reset the database completely and re-seed all tables from scratch:
```bash
php artisan migrate:fresh --seed
```

### Running Individual Modular Seeders
Every seeder is fully decoupled and can be run independently:

```bash
# 1. Re-seed Roles and Permissions
php artisan db:seed --class=RoleAndPermissionSeeder

# 2. Re-create or verify Super Admin
php artisan db:seed --class=AdminUserSeeder

# 3. Seed Governorates and Areas
php artisan db:seed --class=GovernorateAreaSeeder

# 4. Seed Canonical Specialties with English names and icons
php artisan db:seed --class=SpecialtySeeder

# 5. Seed Dosage Forms
php artisan db:seed --class=DosageFormSeeder

# 6. Seed Product Categories
php artisan db:seed --class=ProductCategorySeeder

# 7. Seed Al-Hilal Products
php artisan db:seed --class=ProductSeeder

# 8. Ingest Doctors and create Primary Workplaces
php artisan db:seed --class=DoctorSeeder

# 9. Ingest Pharmacies
php artisan db:seed --class=PharmacySeeder
```

---

## 3. Universal Data Import Center (`/admin/import`)

For ongoing operational data imports (e.g. adding 200 new doctors in Latakia or 150 pharmacies in Aleppo), administrators use the **Data Import Hub** at `/admin/import`.

### Architectural Flow:
```
┌───────────────────────────┐      ┌───────────────────────────┐      ┌───────────────────────────┐
│ 1. Download Template      │ ───> │ 2. Upload & Pre-Flight    │ ───> │ 3. Confirm & Execute      │
│ - Pre-styled Excel .xlsx  │      │ - In-memory parsing       │      │ - Atomic DB Transaction   │
│ - Dropdown validation     │      │ - Smart fuzzy resolution  │      │ - Workplace auto-creation │
│ - Reference tab guide     │      │ - Duplicate detection     │      │ - Audit log entry         │
└───────────────────────────┘      └───────────────────────────┘      └───────────────────────────┘
```

### Supported Entities & Template Specifications:

#### 1. Doctors (`doctors`)
- **Headers**: `اسم الطبيب *`, `الاختصاص الطبي *`, `تصنيف الطبيب *`, `المحافظة *`, `المنطقة / الحي`, `اسم العيادة / المركز`, `رقم الهاتف / الجوال`, `درجة التعاون`, `ملاحظات إضافية`
- **Excel Dropdown Lists**:
  - `تصنيف الطبيب`: `A+, A, B, C`
  - `درجة التعاون`: `مرتفعة, متوسطة, منخفضة`
- **Automated Actions**:
  - Resolves specialty by Arabic or English name.
  - Generates a primary `DoctorWorkplace` clinic record linked to the doctor's resolved area and governorate.

#### 2. Pharmacies (`pharmacies`)
- **Headers**: `اسم الصيدلية *`, `اسم الصيدلي المسؤول`, `المحافظة *`, `المنطقة / الحي *`, `العنوان التفصيلي`, `رقم الهاتف / الجوال`, `صيدلية مشفى؟ (نعم/لا)`, `اسم المشفى التابع له`, `ملاحظات وتفضيلات الطلب`
- **Excel Dropdown Lists**:
  - `صيدلية مشفى؟`: `نعم, لا`

#### 3. Hospitals & Centers (`hospitals`)
- **Headers**: `اسم المشفى بالعربية *`, `الاسم بالإنجليزية`, `المحافظة *`, `المنطقة / الحي *`, `نوع المشفى (حكومي/خاص/عسكري)`, `رقم هاتف الاستعلامات`, `العنوان التفصيلي`
- **Excel Dropdown Lists**:
  - `نوع المشفى`: `خاص, حكومي, عسكري`

#### 4. Products & Dosage Forms (`products`)
- **Headers**: `الاسم التجاري بالعربية *`, `الاسم العلمي / الإنجليزي *`, `الفئة الدوائية *`, `الشكل والعيار الصيدلاني *`, `نشط ومتاح للترويج (نعم/لا)`
- **Excel Dropdown Lists**:
  - `الشكل الصيدلاني`: `أقراص, كبسولات, شراب, معلق فموي, حقن, مراهم وكريمات, قطرات, فوار...`
  - `نشط`: `نعم, لا`

### Duplicate Policies:
- **`skip` (تخطي السجلات المكررة)**: Skips existing phone numbers or registered names in the same zone.
- **`update` (تحديث السجلات الحالية)**: Updates missing information (such as contact phone, classification, notes, or clinic name) without duplicating records or altering visit history.

---

## 4. Phone Number Normalization Standard

To ensure readability and native click-to-dial functionality on mobile browsers, all phone numbers follow the Syrian domestic standard:

$$\text{Format: } 09xxxxxxxx \quad \text{(10 digits starting with 09)}$$

### Conversion Rules:
1. International dialing prefixes (`+963`, `00963`, `963`) are stripped and replaced with leading `0`.
   - `+963933923020` $\rightarrow$ `0933923020`
   - `00963931364256` $\rightarrow$ `0931364256`
2. 9-digit mobile numbers starting with `9` are prefixed with `0`:
   - `933905374` $\rightarrow$ `0933905374`
3. Arabic numerals (`٠١٢٣٤٥٦٧٨٩`) are automatically converted to standard ASCII digits (`0123456789`).
4. Any doctor without an available phone number is safely preserved with `phone = null`.

---

## 5. Specialty De-duplication Matrix

The system consolidates raw text variations into 23 canonical specialties with English translations and Lucide icon identifiers:

| Raw Entries in Excel | Canonical Specialty (`name_ar`) | English (`name_en`) | Icon |
|---|---|---|---|
| `نسائية` | أمراض النساء والتوليد | Obstetrics & Gynecology | `baby` |
| `أطفال` | طب الأطفال | Pediatrics | `heart-pulse` |
| `عصبية`, `جراحة عصبية` | أمراض وجراحة الجملة العصبية | Neurology & Neurosurgery | `brain` |
| `بولية`, `جراحة بولية`, `جراخة بولية` | جراحة المسالك البولية | Urology & Urological Surgery | `activity` |
| `داخلية` | الأمراض الداخلية العامة | Internal Medicine | `stethoscope` |
| `عينية` | طب وجراحة العيون | Ophthalmology | `eye` |
| `أذنية`, `اذن أنف حنجرة`, `جراحة أنف أذن حنجرة` | أمراض الأذن والأنف والحنجرة (ENT) | Otolaryngology (ENT) | `ear` |
| `جراحة عامة`, `جراحة`, `جراحة عامة وتنظيرية` | الجراحة العامة والتنظيرية | General & Laparoscopic Surgery | `scissors` |
| `عظمية`, `جراحة عظمية`, `عظام و مفاصل` | جراحة العظام والمفاصل | Orthopedics & Joint Surgery | `bone` |
| `عام` | طب عام وممارس عام | General Practice | `user-check` |
| `قلبية` | أمراض القلب والأوعية | Cardiology & Vascular Medicine | `heart` |
| `هضمية`, `جراحة هضمية` | أمراض الجهاز الهضمي والكبد | Gastroenterology | `utensils` |
| `غدد صم` | أمراض الغدد الصم والسكري | Endocrinology & Diabetes | `activity` |
| `صدرية` | أمراض الجهاز التنفسي والصدرية | Pulmonology | `wind` |
| `أمراض الكلية` | أمراض وزراعة الكلى | Nephrology | `droplet` |
| `أسرة` | طب الأسرة والمجتمع | Family Medicine | `users` |
| `قابلة` | قبالة قانونية وتوليد | Midwifery | `baby` |
| `اوعية`, `جراحة اوعية` | جراحة الأوعية الدموية | Vascular Surgery | `git-merge` |
| `تغذية` | التغذية العلاجية والحميات | Clinical Nutrition | `apple` |
| `نفسية` | الطب النفسي | Psychiatry | `sparkles` |
| `جلدية` | الأمراض الجلدية والتناسلية | Dermatology | `shield` |
| `اسنان` | طب وجراحة الأسنان | Dentistry | `smile` |
| *(EMPTY)* | اختصاصات طبية أخرى | Other Specialties | `plus-circle` |