# 📊 تقرير حركة الصنف - Item Movement Report

## نظرة عامة
تقرير شامل لمتابعة حركة أي صنف في المخزن خلال فترة زمنية محددة، مع عرض الرصيد الافتتاحي والختامي بالوحدات الكبرى والصغرى.

## المميزات الرئيسية

### 1. الرصيد الافتتاحي (Opening Balance)
- **التعريف**: الرصيد قبل تاريخ البداية المختار
- **طريقة الحساب**:
  ```
  الرصيد الافتتاحي = الرصيد الأساسي للصنف
                     + المشتريات (قبل تاريخ البداية)
                     + مرتجع العملاء (قبل تاريخ البداية)
                     - المبيعات (قبل تاريخ البداية)
                     - مرتجع الموردين (قبل تاريخ البداية)
  ```
- **العرض**: يتم عرضه بالوحدات الكبرى والصغرى (مثال: 5 كرتونة + 3 قطعة)

### 2. حركات الصنف
يتم عرض جميع العمليات في الفترة المحددة:

#### أنواع العمليات:
1. **المشتريات** (Purchase)
   - لون أخضر
   - تضاف للمخزون (+)

2. **المبيعات** (Sale)
   - لون أحمر
   - تطرح من المخزون (-)

3. **مرتجع عميل** (Customer Return)
   - لون أزرق
   - تضاف للمخزون (+)

4. **مرتجع لمورد** (Supplier Return)
   - لون برتقالي
   - تطرح من المخزون (-)

### 3. معلومات كل حركة
- **التاريخ والوقت**: تاريخ العملية الكامل
- **رقم المرجع**: رقم الفاتورة أو المستند
- **نوع العملية**: شراء، بيع، مرتجع، إلخ
- **البيان**: وصف العملية
- **الكمية**: الكمية بوحدة العملية الأصلية
- **الوحدة**: وحدة القياس المستخدمة
- **الوارد**: الكمية الداخلة للمخزون
- **الصادر**: الكمية الخارجة من المخزون
- **الرصيد**: الرصيد الجاري بعد كل عملية (بالوحدات الكبرى والصغرى + الوحدة الأساسية)

### 4. الرصيد الختامي (Closing Balance)
- **التعريف**: الرصيد في نهاية الفترة
- **طريقة الحساب**:
  ```
  الرصيد الختامي = الرصيد الافتتاحي + صافي الحركات خلال الفترة
  ```
- **العرض**: يتم عرضه بالوحدات الكبرى والصغرى

### 5. الملخص الإحصائي
- **إجمالي الوارد**: مجموع كل الكميات الداخلة
- **إجمالي الصادر**: مجموع كل الكميات الخارجة
- **صافي التغيير**: الفرق بين الوارد والصادر
- **عدد العمليات**: إجمالي عدد الحركات

## الفلاتر المتاحة

### 1. الصنف (Product) - **إلزامي**
- يمكن البحث بـ:
  - اسم الصنف بالعربية
  - اسم الصنف بالإنجليزية
  - كود الصنف

### 2. المخزن (Warehouse) - **إلزامي**
- اختيار المخزن المراد الاستعلام عنه

### 3. من تاريخ (From Date) - **اختياري**
- إذا لم يتم تحديده، سيتم احتساب كل الحركات من البداية

### 4. إلى تاريخ (To Date) - **اختياري**
- إذا لم يتم تحديده، سيتم استخدام التاريخ الحالي

## طريقة الاستخدام

1. **الدخول للتقرير**:
   - من القائمة الرئيسية → التقارير (Reports) → تقرير حركة الصنف

2. **اختيار الفلاتر**:
   - اختر الصنف من القائمة (البحث متاح)
   - اختر المخزن
   - (اختياري) حدد من تاريخ
   - (اختياري) حدد إلى تاريخ

3. **عرض التقرير**:
   - يتم تحديث التقرير تلقائياً عند تغيير أي فلتر
   - يمكن طباعة التقرير أو حفظه كـ PDF

## مثال توضيحي

### سيناريو:
- **الصنف**: عصير برتقال
- **المخزن**: المخزن الرئيسي
- **الفترة**: من 1-1-2026 إلى 17-1-2026

### النتيجة:
```
الرصيد الافتتاحي: 10 كرتونة + 5 قطعة (125 قطعة)

الحركات:
┌──────────────┬──────────┬──────────┬────────┬────────┬────────────────┐
│ التاريخ      │ المرجع  │ النوع    │ الوارد │ الصادر │ الرصيد        │
├──────────────┼──────────┼──────────┼────────┼────────┼────────────────┤
│ 2-1-2026     │ #1524    │ مشتريات │ +60    │ -      │ 15 كرتونة + 5 │
│ 5-1-2026     │ #2041    │ مبيعات  │ -      │ 30     │ 13 كرتونة + 5 │
│ 10-1-2026    │ #2156    │ مرتجع عميل │ +12 │ -      │ 14 كرتونة + 5 │
└──────────────┴──────────┴──────────┴────────┴────────┴────────────────┘

الرصيد الختامي: 14 كرتونة + 5 قطعة (173 قطعة)

الملخص:
- إجمالي الوارد: 72 قطعة
- إجمالي الصادر: 30 قطعة
- صافي التغيير: +42 قطعة
- عدد العمليات: 3
```

## الملفات المتعلقة

### Backend:
- **Page Class**: `app/Filament/Pages/ItemMovementReport.php`
- **Models Used**:
  - `App\Models\Product`
  - `App\Models\Warehouse`
  - `App\Models\OpeningBalance`
  - `App\Models\PurchaseItem`
  - `App\Models\SaleItem`
  - `App\Models\PurchaseReturnItem`
  - `App\Models\SaleReturnItem`

### Frontend:
- **View**: `resources/views/filament/pages/item-movement-report.blade.php`

### Translations:
- **Arabic**: `lang/ar/filament/admin/reports.php`
- **English**: `lang/en/filament/admin/reports.php`
- **French**: `lang/fr/filament/admin/reports.php`

## معادلات الحساب

### 1. الرصيد الافتتاحي
```php
$opening_balance = $basic_opening_balance 
                 + $purchases_before_date
                 + $customer_returns_before_date
                 - $sales_before_date
                 - $supplier_returns_before_date;
```

### 2. الرصيد الجاري
```php
$running_balance = $opening_balance + $cumulative_quantity_change;
```

### 3. الرصيد الختامي
```php
$closing_balance = $opening_balance + $total_quantity_change;
```

### 4. تحويل الوحدات
```php
$base_quantity = $quantity * $conversion_factor;
```

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

1. **الوحدات**: 
   - يتم حساب كل شيء بالوحدة الأساسية داخلياً
   - العرض يكون بالوحدات الكبرى والصغرى للسهولة

2. **الترتيب**:
   - الحركات مرتبة حسب التاريخ والوقت

3. **الدقة**:
   - جميع الحسابات بدقة رقمين عشريين

4. **الألوان**:
   - كل نوع عملية له لون مميز لسهولة التمييز

## التحديثات المستقبلية المقترحة

- [ ] إضافة إمكانية التصدير لـ Excel
- [ ] إضافة فلتر بحسب نوع العملية
- [ ] إضافة رسوم بيانية للحركات
- [ ] إضافة مقارنة بين فترتين زمنيتين

---

**تاريخ الإنشاء**: 2026-01-17  
**الإصدار**: 1.0.0  
**الحالة**: ✅ جاهز للاستخدام