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

## نظرة عامة
هذا النظام يسمح باستيراد بيانات الأصناف الكاملة من ملف Excel واحد يحتوي على عدة صفحات (Sheets).

## ترتيب الاستيراد
يتم استيراد البيانات بالترتيب التالي تلقائياً:
1. **المجموعات (Categories)** - يتم تكويدها أولاً
2. **الوحدات (Units)** - يتم تكويدها ثانياً
3. **المخازن (Warehouses)** - يتم تكويدها ثالثاً
4. **الأصناف (Products)** - يتم ربطها بالمجموعات والوحدة الرئيسية
5. **وحدات الأصناف (ProductUnits)** - ربط الأصناف بالوحدات الفرعية مع نسب التحويل
6. **أصناف المخازن (ProductWarehouses)** - ربط الأصناف بالمخازن مع الأرصدة

---

## صيغة ملف Excel

### صفحة Categories (المجموعات)
| code | name | name_ar | description | is_active |
|------|------|---------|-------------|-----------|
| CAT001 | Electronics | إلكترونيات | إلكترونيات ومنتجات تقنية | 1 |
| CAT002 | Food | أغذية | منتجات غذائية | 1 |

**الأعمدة المطلوبة:**
- `code`: كود المجموعة (يستخدم للربط)
- `name`: اسم المجموعة بالإنجليزية **(مطلوب)**
- `name_ar`: اسم المجموعة بالعربية (اختياري)
- `description`: وصف المجموعة (اختياري)
- `is_active`: حالة التفعيل (1 أو 0) (اختياري - افتراضي 1)

---

### صفحة Units (الوحدات)
| code | name | name_ar | symbol | is_base_unit | conversion_factor | is_active |
|------|------|---------|--------|--------------|-------------------|-----------|
| UNIT001 | Piece | قطعة | قطعة | 1 | 1 | 1 |
| UNIT002 | Box | كرتونة | كرتونة | 0 | 1 | 1 |
| UNIT003 | Kilogram | كيلوجرام | كجم | 1 | 1 | 1 |

**الأعمدة المطلوبة:**
- `code`: كود الوحدة (يستخدم للربط) **(مطلوب)**
- `name`: اسم الوحدة بالإنجليزية **(مطلوب)**
- `name_ar`: اسم الوحدة بالعربية (اختياري)
- `symbol`: رمز الوحدة (اختياري)
- `is_base_unit`: هل هي وحدة أساسية (1 أو 0) (اختياري)
- `conversion_factor`: معامل التحويل (اختياري - افتراضي 1)
- `is_active`: حالة التفعيل (اختياري - افتراضي 1)

---

### صفحة Warehouses (المخازن)
| code | name | name_ar | address | phone | manager_name | is_active |
|------|------|---------|---------|-------|--------------|-----------|
| WH001 | Main Warehouse | المخزن الرئيسي | القاهرة | 0123456789 | محمد أحمد | 1 |
| WH002 | Branch Warehouse | مخزن الفرع | الجيزة | 0123456788 | علي حسن | 1 |

**الأعمدة المطلوبة:**
- `code`: كود المخزن (يستخدم للربط) **(مطلوب)**
- `name`: اسم المخزن بالإنجليزية **(مطلوب)**
- `name_ar`: اسم المخزن بالعربية (اختياري)
- `address`: عنوان المخزن (اختياري)
- `phone`: رقم الهاتف (اختياري)
- `manager_name`: اسم المدير (اختياري)
- `is_active`: حالة التفعيل (اختياري - افتراضي 1)

---

### صفحة Products (الأصناف)
| code | barcode | name | name_ar | description | category_code | base_unit_code | min_stock_level | max_stock_level | track_stock | has_expiry_date | is_active | cost_price |
|------|---------|------|---------|-------------|---------------|----------------|-----------------|-----------------|-------------|-----------------|-----------|------------|
| PRD001 | 123456789 | Laptop Dell | لابتوب ديل | لابتوب ديل موديل XPS | CAT001 | UNIT001 | 5 | 50 | 1 | 0 | 1 | 15000 |
| PRD002 | 987654321 | Rice 1KG | أرز 1 كيلو | أرز أبيض 1 كيلو | CAT002 | UNIT003 | 100 | 1000 | 1 | 1 | 1 | 10 |

**الأعمدة المطلوبة:**
- `code`: كود الصنف (اختياري - يتم توليده تلقائياً إذا كان فارغاً)
- `barcode`: الباركود (اختياري)
- `name`: اسم الصنف بالإنجليزية **(مطلوب)**
- `name_ar`: اسم الصنف بالعربية (اختياري)
- `description`: وصف الصنف (اختياري)
- `category_code`: كود المجموعة (يجب أن يكون موجوداً في صفحة Categories)
- `base_unit_code`: كود الوحدة الرئيسية **(مطلوب)**
- `min_stock_level`: الحد الأدنى للمخزون (اختياري - افتراضي 0)
- `max_stock_level`: الحد الأقصى للمخزون (اختياري - افتراضي 0)
- `track_stock`: تتبع المخزون (1 أو 0) (اختياري - افتراضي 1)
- `has_expiry_date`: له تاريخ انتهاء (1 أو 0) (اختياري - افتراضي 0)
- `is_active`: حالة التفعيل (اختياري - افتراضي 1)
- `cost_price`: سعر التكلفة (اختياري - افتراضي 0)

---

### صفحة ProductUnits (وحدات الأصناف)
| product_code | unit_code | conversion_factor | purchase_price | selling_price | is_default | is_default_purchase |
|--------------|-----------|-------------------|----------------|---------------|------------|---------------------|
| PRD001 | UNIT001 | 1 | 15000 | 18000 | 1 | 1 |
| PRD002 | UNIT003 | 1 | 10 | 12 | 1 | 1 |
| PRD002 | UNIT002 | 10 | 100 | 115 | 0 | 0 |

**ملاحظة مهمة:**
- `conversion_factor`: نسبة التحويل مقارنة بالوحدة الرئيسية
- مثال: إذا كانت الوحدة الرئيسية "كيلو" و الوحدة الفرعية "كرتونة" = 10 كيلو
  - `conversion_factor` = 10

**الأعمدة المطلوبة:**
- `product_code`: كود الصنف **(مطلوب)**
- `unit_code`: كود الوحدة **(مطلوب)**
- `conversion_factor`: نسبة التحويل **(مطلوب)**
- `purchase_price`: سعر الشراء (اختياري - افتراضي 0)
- `selling_price`: سعر البيع (اختياري - افتراضي 0)
- `is_default`: وحدة البيع الافتراضية (1 أو 0) (اختياري)
- `is_default_purchase`: وحدة الشراء الافتراضية (1 أو 0) (اختياري)

---

### صفحة ProductWarehouses (أصناف المخازن)
| product_code | warehouse_code | current_stock | reserved_stock | available_stock |
|--------------|----------------|---------------|----------------|-----------------|
| PRD001 | WH001 | 25 | 5 | 20 |
| PRD001 | WH002 | 10 | 2 | 8 |
| PRD002 | WH001 | 500 | 50 | 450 |

**الأعمدة المطلوبة:**
- `product_code`: كود الصنف **(مطلوب)**
- `warehouse_code`: كود المخزن **(مطلوب)**
- `current_stock`: الرصيد الحالي (اختياري - افتراضي 0)
- `reserved_stock`: الرصيد المحجوز (اختياري - افتراضي 0)
- `available_stock`: الرصيد المتاح (اختياري - يساوي current_stock)

---

## كيفية الاستخدام

### الطريقة 1: عبر Command Line
```bash
php artisan products:import path/to/products.xlsx
```

### الطريقة 2: عبر الكود (Controller/Service)
```php
use App\Imports\ProductsImporter;
use Maatwebsite\Excel\Facades\Excel;

Excel::import(new ProductsImporter(), 'path/to/products.xlsx');
```

### الطريقة 3: عبر واجهة Filament (قريباً)
سيتم إضافة زر "استيراد" في صفحة الأصناف

---

## ملاحظات مهمة

1. **ترتيب الصفحات مهم**: يجب أن تكون أسماء الصفحات كما هو محدد أعلاه
2. **الأكواد**: استخدم أكواد فريدة لتجنب التكرار
3. **الوحدة الرئيسية**: كل صنف يجب أن يكون له وحدة رئيسية
4. **نسب التحويل**: يجب إدخال نسب التحويل بشكل صحيح للوحدات الفرعية
5. **المخازن**: يمكن ربط الصنف بأكثر من مخزن
6. **الوحدات الفرعية**: يمكن إضافة أكثر من وحدة فرعية لكل صنف

---

## أمثلة عملية

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

### مثال 2: منتج في مخازن متعددة
**صنف: لابتوب**
- المخزن الرئيسي: 25 قطعة
- مخزن الفرع: 10 قطع
- إجمالي المخزون: 35 قطعة

---

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

إذا فشل الاستيراد، تحقق من:
1. أسماء الصفحات صحيحة
2. الأعمدة المطلوبة موجودة
3. الأكواد المستخدمة في الربط موجودة
4. نسب التحويل صحيحة (أكبر من 0)
5. ملف Excel ليس محمياً بكلمة مرور

جميع الأخطاء يتم تسجيلها في ملف `storage/logs/laravel.log`