# 💰 تقرير حركة الخزينة - Cashbox Movement Report

## نظرة عامة
تقرير شامل لمتابعة جميع حركات الخزينة (الإيرادات والمصروفات) خلال فترة زمنية محددة، مع عرض الرصيد الافتتاحي والختامي.

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

### 1. الرصيد الافتتاحي (Opening Balance)
- **التعريف**: رصيد الخزينة قبل تاريخ البداية المختار
- **طريقة الحساب**:
  ```
  الرصيد الافتتاحي = الرصيد الأساسي للخزينة
                     + جميع الإيرادات (قبل تاريخ البداية)
                     - جميع المصروفات (قبل تاريخ البداية)
  ```

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

#### أنواع العمليات الإيرادية (+):
1. **المبيعات** (Sale)
   - لون أخضر
   - المبلغ المدفوع من فاتورة البيع

2. **سداد العملاء** (Customer Payment)
   - لون أخضر زمردي
   - مدفوعات مستقلة من العملاء

3. **مرتجع مورد** (Purchase Return)
   - لون سماوي
   - استرداد من المورد

4. **إيداع نقدي** (Cash In)
   - لون أخضر مزرق
   - إيداع مباشر للخزينة

#### أنواع العمليات المصروفات (-):
1. **المشتريات** (Purchase)
   - لون أحمر
   - المبلغ المدفوع من فاتورة الشراء

2. **دفع للموردين** (Supplier Payment)
   - لون برتقالي
   - مدفوعات مستقلة للموردين

3. **مرتجع عميل** (Sale Return)
   - لون وردي
   - رد مبلغ للعميل

4. **صرف نقدي** (Cash Out)
   - لون كهرماني
   - صرف مباشر من الخزينة

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

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

### 5. الملخص الإحصائي

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

#### الملخص التفصيلي حسب النوع:
عرض إجمالي وعدد العمليات لكل نوع من أنواع الحركات:
- مبيعات
- مشتريات
- سداد عملاء
- دفع موردين
- مرتجع عميل
- مرتجع مورد
- إيداعات نقدية
- صرفيات نقدية

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

### 1. الخزينة (Cashbox) - **إلزامي**
- اختيار الخزينة المراد الاستعلام عنها
- يمكن البحث بالاسم

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

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

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

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

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

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

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

### سيناريو:
- **الخزينة**: الخزينة الرئيسية
- **الفترة**: من 1-1-2026 إلى 18-1-2026

### النتيجة:
```
الرصيد الافتتاحي: 50,000.00 EGP

الحركات:
┌──────────────┬──────────┬──────────────────┬──────────┬──────────┬────────────┐
│ التاريخ      │ المرجع  │ النوع            │ إيرادات │ مصروفات │ الرصيد     │
├──────────────┼──────────┼──────────────────┼──────────┼──────────┼────────────┤
│ 2-1-2026     │ SAL-1524 │ مبيعات          │ +5,000   │ -        │ 55,000.00  │
│ 3-1-2026     │ PUR-2041 │ مشتريات         │ -        │ 3,000    │ 52,000.00  │
│ 5-1-2026     │ CPR-0015 │ سداد عميل       │ +2,500   │ -        │ 54,500.00  │
│ 8-1-2026     │ SPD-0008 │ دفع لمورد        │ -        │ 1,200    │ 53,300.00  │
│ 10-1-2026    │ CM-0023  │ إيداع نقدي      │ +10,000  │ -        │ 63,300.00  │
└──────────────┴──────────┴──────────────────┴──────────┴──────────┴────────────┘

الرصيد الختامي: 63,300.00 EGP

الملخص العام:
- إجمالي الإيرادات: 17,500.00 EGP
- إجمالي المصروفات: 4,200.00 EGP
- صافي التغيير: +13,300.00 EGP
- عدد العمليات: 5

الملخص التفصيلي:
- مبيعات: 5,000.00 EGP (1 عملية)
- مشتريات: 3,000.00 EGP (1 عملية)
- سداد عملاء: 2,500.00 EGP (1 عملية)
- دفع موردين: 1,200.00 EGP (1 عملية)
- إيداعات نقدية: 10,000.00 EGP (1 عملية)
```

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

### Backend:
- **Page Class**: `app/Filament/Pages/CashboxMovementReport.php`
- **Models Used**:
  - `App\Models\Cashbox`
  - `App\Models\CashMovement`
  - `App\Models\Sale`
  - `App\Models\Purchase`
  - `App\Models\CustomerPayment`
  - `App\Models\SupplierPayment`
  - `App\Models\SaleReturn`
  - `App\Models\PurchaseReturn`

### Frontend:
- **View**: `resources/views/filament/pages/cashbox-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_balance;

foreach ($movements_before_date as $movement) {
    if ($movement->movement_type === 'in') {
        $opening_balance += $movement->amount;
    } else {
        $opening_balance -= $movement->amount;
    }
}
```

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

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

### 4. صافي التغيير
```php
$net_change = $total_income - $total_expense;
```

## أنواع الحركات المالية

### الحركات المباشرة (CashMovement):
- إيداعات وصرفيات نقدية مباشرة
- حركات تحويل بين الخزائن
- مصروفات عامة

### الحركات من المبيعات:
- المبلغ المدفوع من فاتورة البيع (paid_amount)
- يضاف للخزينة عند تأكيد الفاتورة

### الحركات من المشتريات:
- المبلغ المدفوع من فاتورة الشراء (paid_amount)
- يطرح من الخزينة عند تأكيد الفاتورة

### الحركات من مدفوعات العملاء:
- سدادات مستقلة من العملاء
- تضاف للخزينة عند التأكيد

### الحركات من مدفوعات الموردين:
- دفعات مستقلة للموردين
- تطرح من الخزينة عند التأكيد

### الحركات من المرتجعات:
- مرتجع عميل: يطرح من الخزينة (رد مبلغ)
- مرتجع مورد: يضاف للخزينة (استرداد)

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

1. **العملات**: 
   - يتم عرض جميع المبالغ بعملة الخزينة المختارة

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

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

4. **الألوان**:
   - كل نوع عملية له لون مميز لسهولة التمييز
   - الرصيد السالب يظهر باللون الأحمر

5. **الحالة**:
   - يتم احتساب العمليات المؤكدة فقط (status = 'confirmed')

## الفوائد

1. **الشفافية المالية**: 
   - متابعة دقيقة لكل حركة مالية

2. **الرقابة**:
   - مراقبة الإيرادات والمصروفات

3. **التدقيق**:
   - سهولة مراجعة العمليات المالية

4. **اتخاذ القرارات**:
   - بيانات دقيقة للتخطيط المالي

5. **المطابقة**:
   - مطابقة الرصيد الفعلي مع النظام

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

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

---

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