# ✅ إضافة خانة الرصيد الافتتاحي للعملاء

## 📋 الملخص

تم إضافة خانة **الرصيد الافتتاحي** (Opening Balance) لبيانات العملاء بنجاح، وتم دمجها في جميع معادلات كشف حساب العميل وكشف حساب جميع العملاء.

---

## 🎯 التحديثات المنفذة

### 1️⃣ قاعدة البيانات
- ✅ **Migration**: تم إنشاء `2026_01_29_000001_add_opening_balance_to_customers_table.php`
- ✅ إضافة عمود `opening_balance` من نوع `decimal(10, 2)` بقيمة افتراضية `0`
- ✅ تم وضع العمود بعد `credit_limit` في جدول `customers`

### 2️⃣ نموذج البيانات (Model)
**الملف**: `app/Models/Customer.php`
- ✅ إضافة `opening_balance` في `$fillable`
- ✅ إضافة `opening_balance` في `$casts` كـ `decimal:2`
- ✅ إضافة `opening_balance` في Activity Log

### 3️⃣ نموذج الإدخال (Form)
**الملف**: `app/Filament/Resources/Customers/Schemas/CustomerForm.php`
- ✅ إضافة حقل `opening_balance` في قسم "المعلومات المالية"
- ✅ الحقل يدعم الأرقام العشرية (step: 0.01)
- ✅ القيمة الافتراضية: 0.00
- ✅ يظهر بـ prefix "EGP"

### 4️⃣ الترجمات
تم إضافة الترجمات في جميع اللغات:

#### العربية (`lang/ar/filament/admin/customer_resource.php`)
```php
'opening_balance' => 'الرصيد الافتتاحي',
'opening_balance_help' => 'الرصيد الافتتاحي للعميل (رصيد بداية التعامل)',
'opening_balance_placeholder' => '0.00',
```

#### English (`lang/en/filament/admin/customer_resource.php`)
```php
'opening_balance' => 'Opening Balance',
'opening_balance_help' => 'Opening balance for the customer (initial balance)',
'opening_balance_placeholder' => '0.00',
```

#### Français (`lang/fr/filament/admin/customer_resource.php`)
```php
'opening_balance' => 'Solde d\'Ouverture',
'opening_balance_help' => 'Solde d\'ouverture pour le client (solde initial)',
'opening_balance_placeholder' => '0.00',
```

### 5️⃣ خدمة كشف الحساب (StatementService)
**الملف**: `app/Services/StatementService.php`

**التحديث الرئيسي**:
```php
// قبل التحديث:
$opening = Sale::where('customer_id', $customer->id)
    ->when($farmId, fn($q) => $q->where('farm_id', $farmId))
    ->when($from, fn($q) => $q->where('created_at', '<', $from))
    ->sum('remaining_amount');

// بعد التحديث:
$previousSales = Sale::where('customer_id', $customer->id)
    ->when($farmId, fn($q) => $q->where('farm_id', $farmId))
    ->when($from, fn($q) => $q->where('created_at', '<', $from))
    ->sum('remaining_amount');

$opening = ($customer->opening_balance ?? 0) + $previousSales;
```

**المعادلة الجديدة**:
```
الرصيد الافتتاحي = رصيد العميل الافتتاحي (من قاعدة البيانات) + المبيعات السابقة للفترة
```

### 6️⃣ كشف حساب جميع العملاء
**الملف**: `app/Filament/Pages/AllCustomersStatementReport.php`

**التحديث**:
```php
// قبل التحديث:
$opening_balance = $opening_balance_query->sum('remaining_amount');

// بعد التحديث:
$previous_sales = $opening_balance_query->sum('remaining_amount');
$opening_balance = ($customer->opening_balance ?? 0) + $previous_sales;
```

---

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

### إضافة رصيد افتتاحي لعميل جديد:
1. افتح **العملاء** → **إنشاء عميل جديد**
2. املأ البيانات الأساسية
3. في قسم **المعلومات المالية**:
   - أدخل **حد الائتمان**
   - أدخل **الرصيد الافتتاحي** (إن وجد)
4. احفظ العميل

### تعديل رصيد افتتاحي لعميل موجود:
1. افتح **العملاء** → اختر العميل
2. اضغط على **تعديل**
3. عدّل قيمة **الرصيد الافتتاحي** في قسم المعلومات المالية
4. احفظ التعديلات

---

## 🔍 التأثير على التقارير

### كشف حساب عميل (Customer Statement Report)
- يتم احتساب الرصيد الافتتاحي **تلقائياً**
- المعادلة: `الرصيد الافتتاحي = opening_balance + مبيعات سابقة للفترة`
- يظهر في رأس التقرير

### كشف حساب جميع العملاء (All Customers Statement)
- يتم احتساب الرصيد الافتتاحي لكل عميل **تلقائياً**
- المعادلة نفسها تُطبّق على كل عميل
- يظهر في عمود "رصيد افتتاحي"

---

## 🧮 مثال عملي

### مثال 1: عميل بدون رصيد افتتاحي
```
opening_balance = 0
مبيعات سابقة = 5000
الرصيد الافتتاحي في التقرير = 0 + 5000 = 5000 جنيه
```

### مثال 2: عميل برصيد افتتاحي
```
opening_balance = 2000
مبيعات سابقة = 3000
الرصيد الافتتاحي في التقرير = 2000 + 3000 = 5000 جنيه
```

### مثال 3: عميل برصيد افتتاحي سالب (مدين مسبقاً)
```
opening_balance = -1000
مبيعات سابقة = 4000
الرصيد الافتتاحي في التقرير = -1000 + 4000 = 3000 جنيه
```

---

## ✅ الاختبارات الموصى بها

### اختبار 1: إضافة عميل جديد
- [ ] افتح نموذج إنشاء عميل جديد
- [ ] تحقق من ظهور حقل "الرصيد الافتتاحي"
- [ ] أدخل قيمة (مثلاً: 1000)
- [ ] احفظ العميل
- [ ] افتح العميل للتعديل وتحقق من حفظ القيمة

### اختبار 2: كشف حساب عميل
- [ ] افتح تقرير كشف حساب عميل
- [ ] اختر عميل لديه رصيد افتتاحي
- [ ] تحقق من أن الرصيد الافتتاحي في التقرير يساوي: `opening_balance + مبيعات سابقة`

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

### اختبار 4: الترجمات
- [ ] غيّر اللغة إلى العربية → تحقق من النصوص
- [ ] غيّر اللغة إلى English → تحقق من النصوص
- [ ] غيّر اللغة إلى Français → تحقق من النصوص

---

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

1. **الرصيد الحالي (Current Balance)** يبقى للقراءة فقط ويُحدّث تلقائياً من المبيعات والمدفوعات
2. **الرصيد الافتتاحي (Opening Balance)** يُدخل مرة واحدة عند إنشاء العميل أو عند الحاجة لتعديله
3. في كشوف الحساب، يتم **جمع** الرصيد الافتتاحي مع المبيعات السابقة للفترة
4. الحقل يدعم القيم **الموجبة والسالبة**:
   - موجب: العميل مدين لك منذ البداية
   - سالب: أنت مدين للعميل منذ البداية

---

## 🎉 تم الانتهاء بنجاح!

جميع الملفات تم تحديثها وتشغيل المايجريشن بنجاح. النظام جاهز للاستخدام.

---

**تاريخ التطوير**: 29 يناير 2026  
**المطور**: GitHub Copilot  
**الإصدار**: 1.0