# نظام استيراد الأصناف من Excel - دليل سريع

## ⚡ البداية السريعة

### 1. توليد ملف Template
```bash
php artisan products:template
```
سيتم إنشاء ملف `products_template.xlsx` في مجلد `storage/app/public`

### 2. تعديل البيانات
افتح الملف وقم بتعديل البيانات في الصفحات الستة

### 3. استيراد البيانات
```bash
php artisan products:import storage/app/public/products_template.xlsx
```

---

## 📋 الصفحات المطلوبة

يجب أن يحتوي ملف Excel على الصفحات التالية **بنفس الترتيب والأسماء**:

1. **Categories** - المجموعات
2. **Units** - الوحدات
3. **Warehouses** - المخازن
4. **Products** - الأصناف
5. **ProductUnits** - وحدات الأصناف (للربط)
6. **ProductWarehouses** - أصناف المخازن (للربط)

---

## 🔗 آلية الربط

### المفتاح الأساسي: الأكواد
- كل صفحة تحتوي على عمود `code`
- هذا الكود يُستخدم للربط بين الجداول
- مثال:
  - في صفحة Categories: `CAT001`
  - في صفحة Products: `category_code` = `CAT001`

### مثال عملي

#### صفحة Categories
| code | name | name_ar |
|------|------|---------|
| CAT001 | Electronics | إلكترونيات |

#### صفحة Units
| code | name | name_ar |
|------|------|---------|
| UNIT001 | Piece | قطعة |
| UNIT002 | Box | كرتونة |

#### صفحة Products
| code | name | category_code | base_unit_code |
|------|------|---------------|----------------|
| PRD001 | Laptop | CAT001 | UNIT001 |

#### صفحة ProductUnits
| product_code | unit_code | conversion_factor |
|--------------|-----------|-------------------|
| PRD001 | UNIT001 | 1 |
| PRD001 | UNIT002 | 12 |

**الشرح:**
- الصنف `PRD001` تابع للمجموعة `CAT001`
- الوحدة الرئيسية له `UNIT001` (قطعة)
- له وحدة فرعية `UNIT002` (كرتونة) = 12 قطعة

---

## 📊 نسب التحويل (Conversion Factor)

### المفهوم
نسبة التحويل تحدد كم وحدة فرعية = 1 وحدة رئيسية

### أمثلة

#### مثال 1: أرز
- الوحدة الرئيسية: كيلو (`UNIT_KG`)
- وحدات فرعية:
  - شيكارة = 50 كيلو → `conversion_factor = 50`
  - طن = 1000 كيلو → `conversion_factor = 1000`

#### مثال 2: مشروبات
- الوحدة الرئيسية: زجاجة (`UNIT_BOTTLE`)
- وحدات فرعية:
  - كرتونة = 24 زجاجة → `conversion_factor = 24`

---

## 🏪 ربط الأصناف بالمخازن

### صفحة ProductWarehouses

| product_code | warehouse_code | current_stock |
|--------------|----------------|---------------|
| PRD001 | WH001 | 25 |
| PRD001 | WH002 | 10 |

**الشرح:**
- الصنف `PRD001` موجود في مخزنين
- المخزن `WH001`: 25 قطعة
- المخزن `WH002`: 10 قطع
- **الإجمالي**: 35 قطعة

---

## ✅ نصائح مهمة

### 1. الأكواد
- استخدم أكواد واضحة ومميزة
- مثال جيد: `CAT001`, `UNIT_KG`, `PRD_LAPTOP_DELL`
- تجنب: `1`, `A`, `X`

### 2. الوحدة الرئيسية
- كل صنف **يجب** أن يكون له وحدة رئيسية
- الوحدة الرئيسية `conversion_factor = 1`

### 3. البيانات الاختيارية
- يمكن ترك الأعمدة الاختيارية فارغة
- سيتم استخدام القيم الافتراضية

### 4. القيم المنطقية
- استخدم `1` للـ true
- استخدم `0` للـ false

---

## 🚨 استكشاف الأخطاء

### المشكلة: فشل الاستيراد
**الحل:**
1. تحقق من أسماء الصفحات (يجب أن تكون مطابقة تماماً)
2. تأكد من وجود جميع الأعمدة المطلوبة
3. راجع ملف الـ Logs: `storage/logs/laravel.log`

### المشكلة: الصنف لم يُستورَد
**الحل:**
1. تأكد من وجود `base_unit_code` صحيح
2. تحقق من أن الكود موجود في صفحة Units

### المشكلة: الوحدة الفرعية لم تُربَط
**الحل:**
1. تأكد من أن `product_code` و `unit_code` صحيحان
2. تحقق من أن `conversion_factor` أكبر من 0

---

## 📚 الملفات المرجعية

- [PRODUCTS_IMPORT_GUIDE.md](PRODUCTS_IMPORT_GUIDE.md) - دليل تفصيلي كامل
- [EXCEL_TEMPLATE_EXAMPLE.md](EXCEL_TEMPLATE_EXAMPLE.md) - أمثلة إضافية

---

## 🎯 سير العمل الموصى به

1. **التخطيط**
   - حدد المجموعات
   - حدد الوحدات
   - حدد المخازن

2. **الإعداد**
   - قم بتوليد Template: `php artisan products:template`
   - عدّل صفحات: Categories, Units, Warehouses

3. **الأصناف**
   - أضف الأصناف في صفحة Products
   - حدد الوحدة الرئيسية لكل صنف

4. **الوحدات الفرعية**
   - أضف الوحدات الفرعية في ProductUnits
   - حدد نسب التحويل بدقة

5. **المخازن**
   - اربط الأصناف بالمخازن في ProductWarehouses
   - حدد الأرصدة الافتتاحية

6. **الاستيراد**
   - استورد الملف: `php artisan products:import path/to/file.xlsx`
   - راجع الـ Logs للتأكد من النجاح

---

## 🔄 الاستيراد المتقدم

### استيراد لـ Tenant محدد
```bash
php artisan products:import file.xlsx --tenant=1
```

### من الكود
```php
use App\Imports\ProductsImporter;
use Maatwebsite\Excel\Facades\Excel;

Excel::import(new ProductsImporter($tenantId), $filePath);
```

---

## 📞 الدعم

إذا واجهت أي مشاكل:
1. راجع ملف الـ Logs: `storage/logs/laravel.log`
2. راجع [PRODUCTS_IMPORT_GUIDE.md](PRODUCTS_IMPORT_GUIDE.md)
3. تحقق من صيغة الملف مقابل [EXCEL_TEMPLATE_EXAMPLE.md](EXCEL_TEMPLATE_EXAMPLE.md)