# إصلاح حالة الدفع الافتراضية في مرتجعات المبيعات
## Default Payment Status Fix for Sale Returns

تاريخ الإصلاح: 25 مارس 2026

---

## 📋 ملخص المشكلة

كان هناك تعارض بين القيم المسموح بها في قاعدة البيانات وبين القيم المستخدمة في الكود:

- **قاعدة البيانات (ENUM):** `'unpaid'`, `'partial'`, `'paid'`
- **الكود القديم:** `'pending'`, `'partial'`, `'paid'`

عند محاولة إدخال قيمة `'pending'` في عمود `payment_status`، كانت قاعدة البيانات ترفض القيمة لأنها غير مسموح بها في ENUM، مما يسبب الخطأ:

```
SQLSTATE[01000]: Warning: 1265 Data truncated for column 'payment_status' at row 1
```

---

## ✅ التغييرات المنفذة

### 1. ملف النموذج (Form Schema)
**الملف:** `app/Filament/Resources/SaleReturns/Schemas/SaleReturnForm.php`

#### التغيير الأول - دالة calculateTotals (السطر ~272)
```php
// قبل:
if ($paidAmount == 0) {
    $status = 'pending';  // ❌ خطأ
}

// بعد:
if ($paidAmount == 0) {
    $status = 'unpaid';   // ✅ صحيح
}
```

#### التغيير الثاني - خيارات ToggleButtons (السطر ~867)
```php
// قبل:
'pending' => __('filament/admin/sale_return_resource.payment_status.pending')

// بعد:
'unpaid' => __('filament/admin/sale_return_resource.payment_status.unpaid')
```

#### التغيير الثالث - القيمة الافتراضية (السطر ~869)
```php
// قبل:
->default('pending')

// بعد:
->default('unpaid')
```

---

### 2. صفحة الإنشاء (Create Page)
**الملف:** `app/Filament/Resources/SaleReturns/Pages/CreateSaleReturn.php`

تم إضافة منطق للتأكد من تعيين `payment_status` الصحيح:

```php
protected function mutateFormDataBeforeCreate(array $data): array
{
    // ... existing code ...
    
    // التأكد من حفظ حالة الدفع
    if (!isset($data['payment_status']) || empty($data['payment_status'])) {
        $paidAmount = $data['paid_amount'] ?? 0;
        $totalAmount = $data['total_amount'] ?? 0;
        
        if ($paidAmount == 0) {
            $data['payment_status'] = 'unpaid';
        } elseif ($paidAmount >= $totalAmount) {
            $data['payment_status'] = 'paid';
        } else {
            $data['payment_status'] = 'partial';
        }
    }
    
    return $data;
}
```

---

### 3. صفحة التعديل (Edit Page)
**الملف:** `app/Filament/Resources/SaleReturns/Pages/EditSaleReturn.php`

تم إضافة نفس المنطق لصفحة التعديل لضمان الاتساق.

---

### 4. ملفات الترجمة (Translation Files)

#### اللغة العربية
**الملف:** `lang/ar/filament/admin/sale_return_resource.php`

```php
// قبل:
'payment_status.pending' => 'قيد الانتظار',

// بعد:
'payment_status.unpaid' => 'غير مدفوع',
```

#### اللغة الإنجليزية
**الملف:** `lang/en/filament/admin/sale_return_resource.php`

```php
// قبل:
'payment_status.pending' => 'Pending',

// بعد:
'payment_status.unpaid' => 'Unpaid',
```

#### اللغة الفرنسية
**الملف:** `lang/fr/filament/admin/sale_return_resource.php`

```php
// قبل:
'payment_status.pending' => 'En Attente',

// بعد:
'payment_status.unpaid' => 'Non payé',
```

---

## 🔧 إصلاح السجلات الموجودة

تم إنشاء سكريبتين لإصلاح أي سجلات موجودة تحتوي على القيمة الخاطئة `'pending'`:

### الخيار 1: سكريبت PHP
**الملف:** `fix_sale_returns_payment_status.php`

**طريقة الاستخدام:**
```bash
php fix_sale_returns_payment_status.php
```

**الميزات:**
- يعرض حالة السجلات قبل وبعد التحديث
- يطلب تأكيد قبل التنفيذ
- يعرض تقرير مفصل بالنتائج
- يتعامل مع الأخطاء بشكل آمن

---

### الخيار 2: سكريبت SQL
**الملف:** `fix_sale_returns_payment_status.sql`

**طريقة الاستخدام:**
```sql
-- في MySQL Client أو phpMyAdmin
source fix_sale_returns_payment_status.sql;

-- أو عبر سطر الأوامر:
mysql -u username -p database_name < fix_sale_returns_payment_status.sql
```

**محتوى السكريبت:**
```sql
UPDATE sale_returns
SET payment_status = 'unpaid',
    updated_at = NOW()
WHERE payment_status = 'pending';
```

---

## 📝 خطوات التطبيق

### 1. تحديث الكود (تم بالفعل ✅)
جميع التغييرات في الكود قد تم تطبيقها تلقائياً.

### 2. إصلاح السجلات الموجودة (اختياري)
إذا كان لديك سجلات موجودة في قاعدة البيانات:

```bash
# الطريقة 1: استخدام PHP
php fix_sale_returns_payment_status.php

# الطريقة 2: استخدام SQL مباشرة
mysql -u your_username -p your_database < fix_sale_returns_payment_status.sql
```

### 3. مسح الكاش
```bash
# مسح كاش Laravel
php artisan cache:clear
php artisan config:clear
php artisan view:clear

# إعادة تحميل opcache (إذا كان مفعلاً)
php clear_opcache.php
```

### 4. الاختبار
- أنشئ مرتجع مبيعات جديد
- تأكد من أن حالة الدفع تظهر بشكل صحيح
- لا يجب أن تظهر رسالة خطأ بعد الآن

---

## 🎯 النتيجة النهائية

الآن عند إنشاء أو تعديل مرتجع مبيعات:

1. **إذا لم يتم الدفع (المبلغ المدفوع = 0):**
   - حالة الدفع = `'unpaid'` (غير مدفوع)

2. **إذا تم الدفع بالكامل (المبلغ المدفوع ≥ الإجمالي):**
   - حالة الدفع = `'paid'` (مدفوع)

3. **إذا تم الدفع جزئياً:**
   - حالة الدفع = `'partial'` (مدفوع جزئياً)

---

## 📊 قيم payment_status المسموح بها

| القيمة | بالعربية | بالإنجليزية | بالفرنسية |
|--------|----------|-------------|-----------|
| `unpaid` | غير مدفوع | Unpaid | Non payé |
| `partial` | مدفوع جزئياً | Partial | Partiel |
| `paid` | مدفوع | Paid | Payé |

---

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

1. **لا تستخدم** القيمة `'pending'` في أي مكان متعلق بـ `payment_status` في `sale_returns`
2. القيمة `'pending'` موجودة فقط في:
   - جدول `sales` 
   - جدول `purchases`
   - **ليس** في `sale_returns` أو `purchase_returns`
3. إذا قمت بإضافة customize أو تعديلات مستقبلية، تأكد من استخدام القيم الصحيحة

---

## 🔍 للتحقق من نجاح الإصلاح

قم بتشغيل هذا الاستعلام للتأكد من عدم وجود سجلات بقيمة `'pending'`:

```sql
SELECT payment_status, COUNT(*) as count
FROM sale_returns
GROUP BY payment_status;
```

**النتيجة المتوقعة:** لا يجب أن تظهر `'pending'` في النتائج.

---

## 📞 الدعم

إذا واجهت أي مشاكل بعد تطبيق الإصلاح، تأكد من:
- [ ] تم مسح كل أنواع الكاش
- [ ] تم تحديث قاعدة البيانات (إذا كانت هناك سجلات قديمة)
- [ ] لا توجد تعديلات مخصصة أخرى تستخدم `'pending'`

---

**تم بحمد الله ✨**