# 🚀 Quick Start Guide - Statement Reports & Expiry Tracking

## الوصول السريع للتقارير

### 1️⃣ كشف حساب العميل (Customer Account Statement)
**المسار:** Pages → Customer Statement Report

```
الخطوات:
1. افتح لوحة Filament
2. انظر إلى القائمة الجانبية
3. ابحث عن "Pages" القسم
4. انقر على "Customer Account Statement"
5. اختر عميل من القائمة المنسدلة
6. (اختياري) حدد نطاق التاريخ
7. سيتم عرض التقرير مباشرة
```

### 2️⃣ كشف حساب المورد (Supplier Account Statement)
**المسار:** Pages → Supplier Account Statement

```
نفس الخطوات السابقة لكن اختر مورد بدلاً من عميل
```

---

## 📊 محتوى التقرير

### الأجزاء الرئيسية:

```
┌─────────────────────────────────────┐
│  كشف حساب العميل / المورد           │
│  التاريخ: اليوم                     │
│  من: XX-XX-XXXX إلى: XX-XX-XXXX    │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ الرصيد الافتتاحي: XXXX.XX EGP      │
└─────────────────────────────────────┘

┌──────┬─────────┬───────┬──────┐
│ التاريخ│ الفاتورة│ البيان│ المبلغ│
├──────┼─────────┼───────┼──────┤
│ ...  │ ...     │ ...   │ ...  │
│ -- البنود --    │       │      │
│ ...  │ ...     │ ...   │ ...  │
└──────┴─────────┴───────┴──────┘

┌─────────────────────────────────────┐
│ الرصيد الختامي: XXXX.XX EGP        │
└─────────────────────────────────────┘

┌──────────────────┬────────────┐
│ إجمالي المبيعات │ XXXX.XX EGP│
│ إجمالي المدفوع │ XXXX.XX EGP│
│ إجمالي الباقي  │ XXXX.XX EGP│
└──────────────────┴────────────┘
```

---

## 🎨 دليل الألوان

| اللون | المعنى | الاستخدام |
|-----|----- |---------|
| 🔵 أزرق | معلومات | أرقام الفواتير، الأرصدة |
| 🔴 أحمر | تكليف سالب | الخصومات |
| 🟢 أخضر | تدفق إيجابي | المدفوعات |
| 🟠 برتقالي | معلق | الأرصدة المتبقية |
| ⚪ أبيض | عادي | الصفوف العادية |

---

## 📱 الاستخدام على الهاتف

التقرير يعمل تماماً على الهاتف المحمول:
- ✅ الجداول قابلة للتمرير أفقياً
- ✅ العناوين واضحة
- ✅ الأرقام قابلة للقراءة
- ✅ الفلاتر منظمة

---

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

### س: كيف أطبع التقرير؟
**الجواب:** 
1. استخدم Ctrl+P على لوحة المفاتيح
2. اختر طابعك
3. اختر "حفظ كـ PDF" للحفظ

### س: كيف أرى التقرير بدون تحديد تاريخ؟
**الجواب:** 
- ترك حقول التاريخ فارغة يعني "من البداية إلى الآن"

### س: لماذا الرصيد مختلف؟
**الجواب:**
- تأكد من اختيار العميل/المورد الصحيح
- تحقق من نطاق التاريخ
- تأكد من عدم وجود فلاتر أخرى نشطة

### س: هل يمكن تصدير التقرير؟
**الجواب:** 
- الطباعة إلى PDF: Ctrl+P → حفظ كـ PDF
- النسخ: Ctrl+A ثم Ctrl+C
- الإرسال عبر البريد: قريباً

---

## ⚙️ الإعدادات المتاحة

### الفلاتر:
```
1. العميل/المورد (مطلوب)
   - قائمة منسدلة قابلة للبحث
   - اكتب للبحث السريع

2. من التاريخ (اختياري)
   - تقويم تاريخ
   - اترك فارغاً للبداية من الحساب

3. إلى التاريخ (اختياري)
   - تقويم تاريخ
   - الافتراضي: اليوم
```

---

## 📊 شرح الأرقام

### الرصيد الافتتاحي (Opening Balance)
```
= الرصيد السابق للعميل
+ جميع الفواتير قبل التاريخ المختار
- جميع المدفوعات قبل التاريخ المختار
```

### الرصيد الجاري (Running Balance)
```
= الرصيد الافتتاحي
+ كل فاتورة
- كل سداد
```

### الرصيد الختامي (Closing Balance)
```
= الرصيد الافتتاحي
+ إجمالي الفواتير في الفترة
- إجمالي المدفوعات في الفترة
```

---

## 🔐 الصلاحيات

يمكن تحديد من يرى هذه التقارير من خلال:
- Filament Shield
- Role-based permissions
- User permissions management

---

## 📈 الأداء

التقرير محسّن للأداء:
- ⚡ تحميل سريع حتى مع الآلاف من الفواتير
- 🔄 تحديثات حية عند تغيير الفلتر
- 💾 لا توجد حفظ في قاعدة البيانات (حسابات فورية)

---

## 🆘 الدعم الفني

### إذا واجهت مشكلة:

1. **الصفحة لا تحمل:**
   - أعد تحميل الصفحة (F5)
   - امسح الـ cache (Ctrl+Shift+Delete)
   - تحقق من الاتصال بالإنترنت

2. **الأرقام غير صحيحة:**
   - تأكد من اختيار العميل الصحيح
   - تحقق من نطاق التاريخ
   - جدّد الصفحة

3. **أخطاء في الظهور:**
   - جرّب متصفح مختلف
   - استخدم وضع الشاشة الكاملة
   - قلل حجم الخط في المتصفح

---

## 📞 معلومات الاتصال

للمشاكل الفنية الأخرى:
- تحقق من ملف `REPORTS_IMPLEMENTATION.md`
- اقرأ `PROJECT_COMPLETION.md` للتفاصيل الكاملة
- راجع `REPORTS_SETUP.md` للإعدادات المتقدمة

---

## 🎯 الخلاصة (الجزء الأول)

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

---

---

# 🚀 نظام تتبع صلاحيات المنتجات (Expiry Date Tracking System)

## 📅 نظرة عامة سريعة

يوفر نظام تتبع الصلاحيات الجديد في Adly إدارة كاملة لصلاحية المنتجات عبر:
- ✅ الأرصدة الافتتاحية
- ✅ المشتريات والمشتريات المرتجعة
- ✅ المبيعات والمبيعات المرتجعة
- ✅ تقرير متخصص لمراقبة الصلاحيات

**النقطة الأساسية:** نظام **FEFO الصارم** يجبر بيع الدفعات الأقدم صلاحية أولاً تلقائياً ✅

---

## ⚡ البدء السريع (5 دقائق)

### الخطوة 1: تفعيل الصلاحية على المنتج
```
1. اذهب إلى Products (المنتجات)
2. افتح المنتج المراغب
3. علّم خيار: "هل يتطلب تاريخ صلاحية؟"
4. احفظ ✅
```

### الخطوة 2: إدخال رصيد افتتاحي مع تاريخ صلاحية
```
1. اذهب إلى Opening Balances
2. أنشئ رصيد جديد للمنتج
3. أدخل الكمية + تاريخ الصلاحية
4. احفظ ✅
```

### الخطوة 3: إدخال مشتريات مع تاريخ انتهاء
```
1. اذهب إلى Purchases
2. أنشئ فاتورة مشتريات جديدة
3. في كل صف منتج: أدخل الكمية + تاريخ الصلاحية
4. احفظ ✅
```

### الخطوة 4: بيع منتج (FEFO يعمل هنا!)
```
1. اذهب إلى Sales
2. أنشئ فاتورة مبيعات جديدة
3. في كل صف منتج:
   - اختر المنتج
   - اختر المستودع
   - تحديد تاريخ الصلاحية:
     ⚠️ سيختار النظام تلقائياً الدفعة الأقدم صلاحية
     ⚠️ لا يمكنك اختيار دفعة أحدث وجود دفعة أقدم
4. احفظ ✅
```

### الخطوة 5: مراقبة الصلاحيات
```
1. اذهب إلى Pages → Expiry Batches Report
2. اختر المنتج والمستودع (اختياري)
3. حدد نطاق التاريخ (اختياري)
4. انقر "Generate Report"
5. شاهد الدفعات مع الألوان:
   🟢 أخضر = صالح (أكثر من 30 يوم)
   🟠 برتقالي = قريب الانتهاء (≤30 يوم)
   🔴 أحمر = منتهي الصلاحية
```

---

## 🎨 فهم نظام FEFO (First Expire First Out)

### لماذا FEFO؟
```
أجود الممارسات العالمية في المخزون:
- ❌ لا تبيع دفعة حديثة بينما توجد دفعة أقدم متاحة
- ✅ بع الدفعات الأقدم أولاً دائماً
- ✅ قلل الخسائر من انتهاء الصلاحية
```

### كيف يعمل النظام؟

#### 1️⃣ على الواجهة (Client-Side)
```
عند اختيار منتج وخزن:
- النظام يجلب جميع الدفعات المتاحة
- يعرضها مرتبة من الأقدم إلى الأحدث
- عند تغيير التاريخ: يعود تلقائياً للأقدم ✅
```

#### 2️⃣ على الخادم (Server-Side)
```
عند الحفظ:
- يتحقق: "هل التاريخ المختار هو الأقدم المتاح؟"
- إذا لا: يرفع خطأ ❌
- إذا نعم: يوافق ✅
```

### مثال عملي:

**الحالة:**
```
المنتج: دواء (Medicine)
المستودع: المستودع الرئيسي

الدفعات المتاحة:
┌─────────────────┬───────────┬────────┐
│ تاريخ الصلاحية │ الكمية   │ الحالة │
├─────────────────┼───────────┼────────┤
│ 2025-03-15     │ 50 علبة  │ الأقدم ✅│
│ 2025-05-10     │ 100 علبة │ وسط   │
│ 2025-08-20     │ 75 علبة  │ أحدث  │
└─────────────────┴───────────┴────────┘

✅ البيع المسموح:
- اختر 2025-03-15 → يعمل ✅

❌ محاولة البيع من:
- اختر 2025-05-10 → خطأ "اختر الدفعة الأقدم صلاحية!" ❌
- اختر 2025-08-20 → خطأ نفس الرسالة ❌

✅ بعد بيع الدفعة الأولى كاملة:
- اختر 2025-05-10 → يعمل ✅ (الآن هي الأقدم)
```

---

## 📊 دليل تقرير دفعات الصلاحية (Expiry Batches Report)

### الوصول للتقرير
```
Pages → Expiry Batches Report
```

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

| الفلتر | الوصف | متطلب |
|--------|-------|--------|
| Product | اختر المنتج | اختياري (اتركه فارغاً لجميع المنتجات) |
| Warehouse | اختر المستودع | اختياري |
| From Expiry Date | من تاريخ الصلاحية | اختياري |
| To Expiry Date | إلى تاريخ الصلاحية | اختياري |

### ما يعرضه التقرير

#### 📈 ملخص إجمالي (Summary Cards)
```
┌─────────────────────────────────────────────────┐
│ إجمالي الكمية المتاحة: 1,250 وحدة              │
│ دفعات منتهية الصلاحية: 45 وحدة (🔴 أحمر)      │
│ دفعات قريب انتهاء (≤30 يوم): 120 وحدة (🟠)    │
│ دفعات سليمة: 1,085 وحدة (🟢 أخضر)            │
└─────────────────────────────────────────────────┘
```

#### 📋 جدول الدفعات
```
جدول يحتوي على:
- المنتج
- المستودع
- تاريخ الصلاحية
- الكمية المتاحة
- الأيام المتبقية
- الحالة (أخضر/برتقالي/أحمر)
```

#### 💾 تصدير Excel
```
زر "Export to Excel" يُنزّل:
- ملف Excel احترافي
- يحتوي على جميع البيانات والملخصات
- تنسيق ملون وسهل القراءة
```

### مثال على التقرير

```
بيانات الفلتر:
- المستودع: الرئيسي
- من التاريخ: 2025-01-01
- إلى التاريخ: 2025-12-31

النتيجة:
┌───────┬───────────────┬──────────────┬──────────┬─────────┬────────┐
│ المنتج│ تاريخ الصلاحية│ الكمية        │ الأيام   │ الحالة   │ ملاحظة │
├───────┼───────────────┼──────────────┼──────────┼─────────┼────────┤
│ دواء  │ 2025-02-15   │ 50 علبة      │ -10 يوم │ 🔴 منتهي│ بيع فوري│
│ دواء  │ 2025-03-15   │ 100 علبة     │ 20 يوم  │ 🟠 قريب │ نسق بيع │
│ فيتامين│ 2025-04-10   │ 75 علبة      │ 45 يوم  │ 🟢 سليم │ عادي    │
└───────┴───────────────┴──────────────┴──────────┴─────────┴────────┘
```

---

## 🔄 الحالات الواقعية والسيناريوهات

### السيناريو 1️⃣: منتج بدون صلاحية
```
المشكلة: بعض المنتجات (مثل الملابس) لا تحتاج صلاحية

الحل:
- في المنتج: لا تفعّل "Expiry Date Required"
- النظام سيعامله بشكل عادي
- لن تر حقول الصلاحية في العمليات
✅ يعمل بدون مشاكل
```

### السيناريو 2️⃣: منتج جديد محتاج صلاحية
```
الخطوات:
1. انشئ المنتج
2. فعّل "Expiry Date Required"
3. أضف رصيد افتتاحي مع صلاحية
4. في المشتريات القادمة: ادخل صلاحية كل فاتورة
5. عند البيع: النظام سيفرض FEFO ✅
```

### السيناريو 3️⃣: دفعة قريب انتهاء الصلاحية
```
المشكلة: دفعة دواء تنتهي صلاحيتها خلال يومين!

الحل:
1. افتح تقرير الصلاحيات
2. شاهد الدفعة بـ 🟠 برتقالي
3. حدد أيام قليلة للبيع:
   - أعطِ عرض خاص
   - أخبر فريق البيع
   - شجع على البيع السريع
4. تتبع باستمرار حتى انتهاء البيع ✅
```

### السيناريو 4️⃣: دفعة منتهية الصلاحية
```
المشكلة: دفعة تجاوزت تاريخ الصلاحية!

الآثار:
- الجدول سيعرضها بـ 🔴 أحمر
- ستظهر في ملخص "منتهية الصلاحية"
- لا تستطيع بيعها (نظام يمنع!)

الحل:
- معالجة خسارة (Adjustment)
- إزالة من المستودع
- توثيق في نظام الخسائر
```

### السيناريو 5️⃣: بيانات قديمة بدون صلاحية
```
المشكلة: لديك مخزون قديم بدون تاريخ صلاحية محدد

الحل:
- ترك حقل الصلاحية فارغ (NULL) ✅
- النظام يعامل المنتجات بدون صلاحية عادياً
- عند بيع: لا فرض FEFO
- عند إضافة صلاحيات جديدة: سيطبق FEFO ✅
```

---

## 💡 أفضل الممارسات

### ✅ ما يجب فعله

```
1. تفعيل الصلاحية على المنتجات صحيحة الاستخدام
   → صحة، أدوية، غذائيات، مواد كيميائية

2. إدخال صلاحية دقيق عند الاستقبال
   → اقرأ الصناديق بعناية
   → ادخل التاريخ الصحيح

3. مراقبة التقرير أسبوعياً
   → شاهد الدفعات القريبة للانتهاء
   → اتخذ إجراء قبل انتهاء الصلاحية

4. تثقيف فريق البيع
   → شرح FEFO
   → اشرح أهميتها
   → علمهم قراءة التقرير

5. توثيق الخسائر
   → عند انتهاء صلاحية: وثّق الخسارة
   → احفظ الإثباتات
```

### ❌ ما يجب تجنبه

```
1. ❌ عدم تفعيل الصلاحية على منتجات تحتاجها
   → خطر صحي وقانوني!

2. ❌ إدخال صلاحية خاطئة
   → يؤدي لقرارات بيع خاطئة

3. ❌ تجاهل التقرير
   → قد تبيع منتجات منتهية الصلاحية!

4. ❌ محاولة تجاوز FEFO
   → النظام لن يسمح! ❌

5. ❌ عدم توثيق الخسائر
   → فقدان المساءلة المالية
```

---

## ❓ أسئلة شائعة (FAQs)

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

---

### س: ماذا لو أدخلت صلاحية خاطئة؟
**الجواب:**
- انشئ فاتورة مرتجعة (Return)
- أدخل من جديد بالصلاحية الصحيحة
- وثّق في النظام

---

### س: هل يمكن بيع منتج بدون صلاحية؟
**الجواب:**
- نعم ✅ (إذا لم تفعّل الصلاحية عليه)
- لا ❌ (إذا فعّلت الصلاحية وتركت الحقل فارغ)
- الحل: ادخل صلاحية صحيحة

---

### س: كيف أتعامل مع دفعة منتهية؟
**الجواب:**
1. انشئ adjustment (تعديل) بحقل "الخسارة"
2. قلل الكمية إلى صفر
3. وثّق السبب: "صلاحية انتهت بتاريخ XX"
4. احفظ

---

### س: ماذا يعني "أيام متبقية"؟
**الجواب:**
```
أيام متبقية = تاريخ الصلاحية - تاريخ اليوم

أمثلة:
- 2025-03-15 واليوم 2025-03-10 → 5 أيام متبقية
- 2025-03-15 واليوم 2025-03-16 → -1 يوم (منتهي!)
- 2025-03-15 واليوم 2025-02-15 → 30 يوم متبقية
```

---

### س: هل FEFO إجباري؟
**الجواب:**
- نعم ✅ (محمي بالنظام نفسه)
- لا يمكن تجاوزه
- فائدة: تحمي من الأخطاء البشرية

---

### س: كيف أطبع التقرير؟
**الجواب:**
```
1. افتح تقرير الصلاحيات
2. اضغط Ctrl+P
3. اختر طابعك
4. اختر "حفظ كـ PDF" (اختياري)
```

---

### س: هل يمكن مشاركة التقرير؟
**الجواب:**
- طباعة إلى PDF وإرسال
- الصلاحيات: قد يحتاج صلاحيات admin
- تصدير Excel أسهل للمشاركة

---

## 📚 مراجع إضافية

لمزيد من المعلومات التفصيلية:
- اقرأ **[EXPIRY_TRACKING_GUIDE.md](EXPIRY_TRACKING_GUIDE.md)** - دليل كامل شامل
- اقرأ **[EXPIRY_SYSTEM_UPDATES.md](EXPIRY_SYSTEM_UPDATES.md)** - التفاصيل التقنية
- اقرأ **[REPORTS_IMPLEMENTATION.md](REPORTS_IMPLEMENTATION.md)** - إعدادات التقارير

---

## 🎯 الخلاصة (الجزء الثاني)

نظام تتبع الصلاحيات الآن:
✅ تلقائي وذكي
✅ يفرض FEFO بصرامة
✅ سهل الاستخدام
✅ موفر للوقت والخسائر
✅ آمن وموثق

---

**استمتع باستخدام النظام المحسّن!** 🎉