# دليل إعادة حساب المخزون للفواتير القديمة

## المشكلة
الفواتير التي تم إنشاؤها قبل تطبيق نظام الـ Observers لن تؤثر تلقائيًا على المخزون. الـ Observers تعمل فقط على الفواتير الجديدة أو المعدلة.

## الحل
تم إنشاء Command لإعادة حساب المخزون من جميع الفواتير الموجودة: `stock:recalculate`

---

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

### 1️⃣ إعادة حساب المخزون دون تغيير الكميات الحالية
```bash
php artisan stock:recalculate
```
- يضيف كميات فواتير الشراء على الكميات الموجودة
- يطرح كميات فواتير البيع
- **لا يحذف** الكميات الحالية

### 2️⃣ إعادة تعيين المخزون من الصفر (موصى به)
```bash
php artisan stock:recalculate --reset
```
- يعيد جميع الكميات إلى صفر أولاً
- ثم يحسب الكميات من جديد بناءً على الفواتير
- **الأفضل** لضمان دقة البيانات

### 3️⃣ إعادة حساب المخزون وإنشاء سجلات حركات المخزون
```bash
php artisan stock:recalculate --reset --movements
```
- يعيد الكميات إلى صفر
- يحسب الكميات من جديد
- يحذف سجلات `stock_movements` القديمة
- ينشئ سجلات جديدة لكل حركة

---

## ماذا يفعل الـ Command؟

### 1. فواتير الشراء (Purchase Items)
- يزيد `stock_quantity` لكل منتج بناءً على كميات فواتير الشراء
- ينشئ سجل في `stock_movements` لكل صنف (إذا استخدمت `--movements`)

### 2. فواتير البيع (Sale Items)
- يقلل `stock_quantity` لكل منتج بناءً على كميات فواتير البيع
- ينشئ سجل في `stock_movements` لكل صنف

### 3. مرتجعات الشراء (Purchase Returns)
- يقلل `stock_quantity` (لأنها إرجاع للمورد)
- ينشئ سجل في `stock_movements`

### 4. مرتجعات البيع (Sale Returns)
- يزيد `stock_quantity` (لأنها إرجاع من العميل)
- ينشئ سجل في `stock_movements`

---

## متى تستخدم كل خيار؟

### ✅ استخدم `--reset` إذا:
- كنت تريد البدء من جديد وحساب المخزون بدقة
- الكميات الحالية غير دقيقة أو متضاربة
- تريد ضمان تطابق المخزون مع الفواتير 100%

### ✅ استخدم `--movements` إذا:
- تريد إعادة بناء سجل حركات المخزون من جديد
- تريد تتبع كامل لجميع الحركات
- تريد تقارير دقيقة عن حركة المخزون

### ⚠️ لا تستخدم `--reset` إذا:
- لديك تعديلات يدوية على الكميات تريد الحفاظ عليها
- لديك مصادر أخرى للكميات غير الفواتير

---

## مثال عملي

### السيناريو:
لديك 100 فاتورة شراء قديمة و 50 فاتورة بيع قديمة، وتريد إعادة حساب المخزون بدقة.

### الأمر الموصى به:
```bash
php artisan stock:recalculate --reset --movements
```

### النتيجة:
```
🔄 بدء إعادة حساب المخزون...

📌 إعادة تعيين جميع الكميات إلى صفر...
🗑️  حذف سجلات حركات المخزون القديمة...
📥 معالجة فواتير الشراء...
 200/200 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
📤 معالجة فواتير البيع...
 150/150 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
↩️  معالجة مرتجعات الشراء...
 5/5 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
↪️  معالجة مرتجعات البيع...
 3/3 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

✅ تم إعادة حساب المخزون بنجاح!

📊 ملخص النتائج:
+---------------------------+-------+
| البيان                    | العدد |
+---------------------------+-------+
| إجمالي المنتجات          | 45    |
| المنتجات المتوفرة         | 38    |
| المنتجات غير المتوفرة     | 7     |
| سجلات حركات المخزون       | 358   |
+---------------------------+-------+
```

---

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

### ⚠️ تحذيرات:
1. **استخدم `--reset` بحذر**: سيحذف جميع الكميات الحالية
2. **استخدم في بيئة الـ staging أولاً**: للتأكد من النتائج قبل التطبيق على الإنتاج
3. **أخذ نسخة احتياطية**: قبل تشغيل الأمر مع `--reset`

### ✅ أفضل الممارسات:
1. شغل الأمر في وقت منخفض الاستخدام
2. راجع النتائج بعد التشغيل
3. تحقق من تطابق الكميات مع السجلات اليدوية

---

## الخطوات بعد إعادة الحساب

1. ✅ راجع الكميات في قائمة المنتجات
2. ✅ تحقق من تقارير حركة المخزون
3. ✅ قارن النتائج مع الجرد الفعلي
4. ✅ الفواتير الجديدة من الآن ستحدث المخزون تلقائيًا

---

## الأسئلة الشائعة

### س: هل سيؤثر على الفواتير نفسها؟
**ج:** لا، الأمر يؤثر فقط على جدول `products` (الكميات) و `stock_movements`

### س: هل يمكن التراجع؟
**ج:** نعم، يمكن إعادة تشغيل الأمر مع `--reset` في أي وقت

### س: كم من الوقت يستغرق؟
**ج:** يعتمد على عدد الفواتير، عادة من ثوانٍ إلى دقيقتين

### س: هل يعمل على البيانات المحذوفة (soft deleted)؟
**ج:** لا، يعالج فقط السجلات النشطة

---

## الخلاصة

✅ **للفواتير الجديدة**: تعمل تلقائيًا عبر Observers  
🔄 **للفواتير القديمة**: استخدم `php artisan stock:recalculate --reset --movements`