# ضبط تسجيل المبيعات والمرتجعات في الخزينة

## نظرة عامة

تم تحسين نظام Observers لتسجيل فواتير البيع والمرتجعات في الخزينة بنفس طريقة المشتريات، مع إضافة آليات عكس الحركات عند الحذف.

---

## التحسينات المنفذة

### 1. ✅ **SaleObserver** (فواتير البيع)

#### Before (قبل):
```php
// كان يسجل كل المبيعات بدون تحقق من الحالة
if ($sale->vault_id) {
    // تسجيل في الخزينة
}
```

#### After (بعد):
```php
// يسجل فقط المبيعات المكتملة (مثل المشتريات)
if ($sale->vault_id && $sale->status === 'completed') {
    // تسجيل في الخزينة
}
```

**التحسينات:**
- ✅ إضافة شرط `status === 'completed'` للتأكد من اكتمال البيع
- ✅ إضافة `null check` للـ vault قبل الاستخدام
- ✅ تحسين رسالة الملاحظات لتشمل payment_method
- ✅ إضافة method `deleted()` لعكس الحركة عند الحذف

### 2. ✅ **SaleReturnObserver** (مرتجعات المبيعات)

**التحسينات:**
- ✅ إضافة method `deleted()` لعكس حركة المرتجع عند الحذف
- ✅ تحسين رسالة الملاحظات لتشمل رقم الفاتورة
- ✅ إضافة documentation واضحة للخطوات

**آلية العمل:**
1. **عند الإنشاء (created)**:
   - إرجاع المنتج للمخزون ✅
   - خصم المبلغ من الخزينة (رد للعميل) ✅
   
2. **عند الحذف (deleted)**:
   - خصم المنتج من المخزون (عكس الإرجاع) ✅
   - إرجاع المبلغ للخزينة (عكس الرد) ✅

### 3. ✅ **PurchaseReturnObserver** (مرتجعات المشتريات)

**التحسينات:**
- ✅ إضافة method `deleted()` لعكس حركة المرتجع عند الحذف
- ✅ تحسين رسالة الملاحظات لتشمل رقم الفاتورة
- ✅ عكس حركة رصيد المورد عند الحذف

**آلية العمل:**
1. **عند الإنشاء (created)**:
   - خصم المنتج من المخزون ✅
   - إضافة المبلغ للخزينة (استرداد من المورد) ✅
   - تقليل رصيد المورد ✅
   
2. **عند الحذف (deleted)**:
   - إرجاع المنتج للمخزون (عكس الخصم) ✅
   - خصم المبلغ من الخزينة (عكس الاسترداد) ✅
   - زيادة رصيد المورد (عكس التقليل) ✅

---

## الفرق بين المعاملات

### إيرادات (دخول للخزينة - type: 'in'):
1. **فاتورة بيع** (Sale):
   ```
   البيع → إضافة للخزينة
   الحذف → خصم من الخزينة
   ```

2. **مرتجع مشتريات** (PurchaseReturn):
   ```
   المرتجع → إضافة للخزينة (استرجاع من المورد)
   الحذف → خصم من الخزينة
   ```

### مصروفات (خروج من الخزينة - type: 'out'):
1. **مرتجع مبيعات** (SaleReturn):
   ```
   المرتجع → خصم من الخزينة (رد للعميل)
   الحذف → إضافة للخزينة
   ```

2. **فاتورة شراء** (Purchase):
   ```
   الشراء → خصم من الخزينة
   الحذف → إضافة للخزينة
   ```

---

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

1. ✅ **app/Observers/SaleObserver.php**
   - إضافة شرط status
   - إضافة deleted method
   - تحسين الملاحظات

2. ✅ **app/Observers/SaleReturnObserver.php**
   - إضافة deleted method
   - تحسين الملاحظات
   - إضافة documentation

3. ✅ **app/Observers/PurchaseReturnObserver.php**
   - إضافة deleted method
   - عكس حركة رصيد المورد
   - تحسين الملاحظات

---

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

### إنشاء فاتورة بيع:
```php
Sale::create([
    'sale_number' => 'SALE-001',
    'total_amount' => 1000,
    'vault_id' => 1,
    'status' => 'completed', // مهم!
]);
// ✅ سيتم تسجيل +1000 في الخزينة تلقائياً
```

### إنشاء مرتجع مبيعات:
```php
SaleReturn::create([
    'sale_id' => 1,
    'product_id' => 5,
    'quantity' => 2,
    'total_amount' => 200,
    'vault_id' => 1,
]);
// ✅ سيتم:
//    - إرجاع 2 قطعة للمخزون
//    - خصم 200 من الخزينة (رد للعميل)
```

### حذف فاتورة:
```php
$sale = Sale::find(1);
$sale->delete();
// ✅ سيتم:
//    - حذف soft delete للحركة المالية
//    - خصم المبلغ من الخزينة (عكس الإضافة)
```

---

## التحقق من العمل

### فحص VaultTransactions:
```php
// المبيعات
VaultTransaction::where('reference_type', 'sale')->get();

// مرتجعات المبيعات
VaultTransaction::where('reference_type', 'sale_return')->get();

// مرتجعات المشتريات
VaultTransaction::where('reference_type', 'purchase_return')->get();
```

### فحص رصيد الخزينة:
```php
$vault = Vault::find(1);
echo "رصيد الخزينة: " . $vault->balance;

// التحقق من صحة الرصيد
$calculated = VaultTransaction::where('vault_id', 1)
    ->sum(DB::raw("CASE WHEN type = 'in' THEN amount ELSE -amount END"));
echo "الرصيد المحسوب: " . $calculated;
```

---

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

### ⚠️ شروط التسجيل في الخزينة:

1. **المبيعات**:
   - يجب أن يكون `vault_id` موجود
   - يجب أن يكون `status = 'completed'`
   
2. **المرتجعات**:
   - يجب أن يكون `vault_id` موجود
   - يجب أن يكون `total_amount > 0`

### 🔄 آلية Soft Delete:

- جميع الـ VaultTransactions تستخدم soft delete
- عند حذف فاتورة/مرتجع، يتم حذف الحركة المالية soft delete
- يتم تحديث رصيد الخزينة بعكس الحركة الأصلية
- يمكن استرجاع الحركات المحذوفة باستخدام `withTrashed()`

### 📝 Logging والمتابعة:

- كل حركة في `VaultTransaction` لها `notes` توضيحية
- كل حركة مرتبطة بـ `reference_type` و `reference_id`
- يتم تسجيل `balance_before` و `balance_after` لكل حركة
- يتم تسجيل `created_by` لمعرفة من قام بالعملية

---

## الخلاصة

✅ **تم ضبط النظام بالكامل**:
- المبيعات تُسجل في الخزينة (مثل المشتريات تماماً)
- مرتجعات المبيعات تُسجل في الخزينة كمصروف
- مرتجعات المشتريات تُسجل في الخزينة كإيراد
- جميع الحركات قابلة للعكس عند الحذف
- رصيد الخزينة يُحدّث تلقائياً في كل الحالات

---

**تاريخ التحديث**: 29 مارس 2026  
**الحالة**: مكتمل ومختبر ✅