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

## 🎯 نظرة عامة

يوفر نظام تتبع الصلاحيات في Adly إدارة شاملة لصلاحية المنتجات عبر جميع العمليات (الأرصدة الافتتاحية، المشتريات، المبيعات، المرتجعات). يعتمد النظام على **نظام FEFO الصارم (First Expire First Out)** الذي يضمن بيع الدفعات الأقدم صلاحية أولاً.

---

## 🔧 كيفية تفعيل نظام الصلاحيات

### الخطوة 1️⃣: تحديد المنتجات ذات الصلاحية

1. انتقل إلى **المنتجات** (Products)
2. افتح المنتج الذي تريد تفعيل الصلاحية له
3. في قسم **معلومات أساسية**، ستجد:
   ```
   ✅ هل يتطلب تاريخ صلاحية؟ (Expiry Date Required)
   ```
4. فعّل الخيار بالنقر على المربع
5. احفظ التغييرات

**ملاحظة:** بعد تفعيل هذا الخيار، سيصبح حقل تاريخ الصلاحية **إجباري** في جميع العمليات على هذا المنتج.

---

## 📋 المنتجات المدعومة

نظام الصلاحيات يعمل بشكل كامل مع:

### 1️⃣ الأرصدة الافتتاحية (Opening Balances)
```
الفائدة:
- تحديد صلاحية الرصيد الحالي بدقة
- دعم نفس المنتج برصيد متعدد مع صلاحيات مختلفة
- رصيد افتتاحي بدون تاريخ صلاحية محدد (NULL) مدعوم للبيانات القديمة
```

**خطوات الإدخال:**
1. انتقل إلى **الأرصدة الافتتاحية**
2. أنشئ رصيد جديد
3. اختر منتج مفعّل للصلاحية
4. سيظهر حقل **تاريخ الصلاحية** تلقائياً
5. أدخل الكمية وتاريخ الصلاحية
6. احفظ

---

### 2️⃣ المشتريات (Purchases)
```
الفائدة:
- تتبع تاريخ انتهاء الصلاحية من الموردين مباشرة
- إدارة دفعات متعددة من نفس المنتج
- توثيق آمن لكل دفعة
```

**خطوات الإدخال:**
1. انتقل إلى **المشتريات**
2. أنشئ فاتورة شراء جديدة
3. أضف بند (item) من منتج مفعّل للصلاحية
4. سيظهر حقل **تاريخ الصلاحية** تحت الكمية
5. أدخل تاريخ الصلاحية كما أرسله الموردون
6. أكمل إدخال باقي التفاصيل واحفظ

---

### 3️⃣ المبيعات (Sales) - مع FEFO الصارم
```
الفائدة:
- فرض نظام FEFO تلقائياً
- منع بيع دفعات حديثة عند وجود دفعات أقدم
- ضمان الامتثال للمعايير الصحية و الجودة
```

**خطوات الإدخال:**
1. انتقل إلى **المبيعات**
2. أنشئ فاتورة مبيعات جديدة
3. أضف بند من منتج مفعّل للصلاحية
4. **ستظهر قائمة الدفعات المتاحة** مرتبة بالأقدم أولاً:
   ```
   مثال:
   [ 2025-12-31 - الكمية المتاحة: 100 ]
   [ 2026-03-15 - الكمية المتاحة: 50 ]
   [ 2026-06-30 - الكمية المتاحة: 75 ]
   ```
5. النظام سيختار **تلقائياً** الدفعة الأقدم (2025-12-31)
6. إذا حاولت تغيير الاختيار يدوياً:
   - ستظهر رسالة تحذيرية: "يجب اختيار أقدم تاريخ صلاحية متاح (2025-12-31)"
   - سيتم إعادة ضبط الحقل تلقائياً
7. احفظ الفاتورة

---

### 4️⃣ مرتجعات المشتريات (Purchase Returns)
```
الفائدة:
- تتبع دقيق لدفعات المرتجعات
- حفظ تاريخ الصلاحية الأصلي للمنتج المرتجع
```

**خطوات الإدخال:**
1. انتقل إلى **مرتجعات المشتريات**
2. أنشئ مرتجع جديد أو اختر فاتورة شراء أصلية
3. عند إضافة بند، سيظهر حقل **تاريخ الصلاحية**
4. أدخل نفس تاريخ الصلاحية من الفاتورة الأصلية
5. احفظ

---

### 5️⃣ مرتجعات المبيعات (Sale Returns) - مع FEFO
```
الفائدة:
- ربط الدفعة المرتجعة بالدفعة الأصلية
- FEFO enforcement عند إرجاع المنتجات
```

**خطوات الإدخال:**
1. انتقل إلى **مرتجعات المبيعات**
2. اختر فاتورة مبيعات أصلية
3. النظام **سيحمّل البيانات تلقائياً** بما فيها تاريخ الصلاحية
4. إذا أردت تغيير الدفعة:
   - سيعرض النظام الدفعات المتاحة بترتيب FEFO
   - اختر الدفعة المطلوبة (ملزم باختيار الأقدم)
5. احفظ

---

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

### الوصول إلى التقرير

```
Pages → Expiry Batches Report
أو
المسار المختصر: أيقونة التقارير → Expiry Batches
```

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

| الفلتر | الوصف |
|-------|-------|
| **المنتج** | اختر منتج معين (يعرض فقط المنتجات مفعلة للصلاحية) |
| **المخزن** | حدد المخزن/المستودع المراد الفحص |
| **من تاريخ الصلاحية** | ابدأ من تاريخ صلاحية محدد |
| **إلى تاريخ الصلاحية** | انتهِ عند تاريخ صلاحية محدد |

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

#### 1️⃣ بطاقات الملخص (Summary Cards)
```
┌─────────────────┐
│ إجمالي الدفعات │
│      25        │
└─────────────────┘

┌─────────────────┐
│  إجمالي الكمية │
│    1,250.00    │
└─────────────────┘

┌─────────────────┐
│  منتهية الصلاحية│
│       3        │
└─────────────────┘

┌──────────────────┐
│ قريبة الانتهاء   │
│ (≤ 30 يوم)      │
│       7        │
└──────────────────┘
```

#### 2️⃣ جدول الدفعات (Batches Table)
يعرض جميع الدفعات مع:

| العمود | الوصف | الألوان |
|-------|-------|--------|
| **تاريخ الصلاحية** | التاريخ المحدد للدفعة | - |
| **المنتج** | اسم المنتج و الكود | - |
| **المخزن** | المخزن/المستودع | - |
| **الكمية المتاحة** | الرصيد الحالي | عدد |
| **الحالة** | حالة الصلاحية | 🔴 أحمر (منتهية) / 🟠 أصفر (قريبة) / 🟢 أخضر (جيدة) |
| **الأيام المتبقية** | عدد الأيام حتى الانتهاء | أرقام |
| **أول حركة** | أول تاريخ لهذه الدفعة | تاريخ |
| **آخر حركة** | آخر تاريخ لهذه الدفعة | تاريخ |

#### 3️⃣ المؤشرات اللونية

```
🔴 منتهية الصلاحية (Expired)
   → تاريخ الصلاحية قد مضى بالفعل
   → الإجراء المطلوب: إزالة فوراً من المخزن

🟠 قريبة الانتهاء (Near Expiry)
   → تبقى ≤ 30 يوم على الانتهاء
   → الإجراء المطلوب: بيع أولوية

🟢 جيدة (Good)
   → صلاحية كافية
   → يمكن البيع عادياً
```

---

## 🎯 سيناريوهات الاستخدام

### ✅ سيناريو 1: منتج جديد يتطلب تتبع الصلاحية

```
1. أضف المنتج في قسم المنتجات
2. فعّل خيار "هل يتطلب تاريخ صلاحية؟"
3. أدخل رصيد افتتاحي مع تاريخ صلاحية
4. عند شراء المنتج، أدخل تاريخ الصلاحية من الفاتورة
5. عند البيع، اختر الدفعة الأقدم من القائمة
6. راقب التقرير شهرياً لتحديد الدفعات القريبة
```

### ✅ سيناريو 2: منتج لديك بدون صلاحية محددة

```
1. لا تفعّل خيار الصلاحية
2. ستتم جميع العمليات بدون حقول صلاحية
3. يبقى النظام مسؤول عن الرصيد الإجمالي فقط
```

### ✅ سيناريو 3: تغيير منتج من بدون صلاحية إلى مع صلاحية

```
1. فعّل الخيار في المنتج
2. الأرصدة القديمة ستبقى مع NULL (بدون صلاحية محددة)
3. الفاتورات الجديدة ستتطلب صلاحية
4. التقرير سيعرض الدفعات بدون صلاحية تحت "بدون تاريخ صلاحية"
```

---

## 💡 نصائح مهمة

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

```
1. تفعيل الصلاحية للمنتجات الغذائية و الدوائية فقط
2. إدخال تاريخ الصلاحية من فاتورة المورد مباشرة
3. فحص التقرير أسبوعياً للدفعات القريبة من الانتهاء
4. بيع الدفعات القريبة بسرعة قبل الانتهاء
5. إزالة الدفعات المنتهية فوراً من المخزن
```

### 🚨 تجنب الأخطاء الشائعة

```
❌ عدم تفعيل الصلاحية حتى للمنتجات الغذائية
❌ إدخال تاريخ صلاحية خاطئ عند الشراء
❌ محاولة بيع دفعة حديثة قبل الدفعة القديمة
❌ عدم فحص التقرير بانتظام
❌ ترك الدفعات المنتهية في المخزن
```

---

## 📈 مثال عملي

### حالة واقعية: منتج لبن بودرة

```
1️⃣ تفعيل الصلاحية:
   المنتج: لبن بودرة
   ✅ فعّل خيار الصلاحية

2️⃣ رصيد افتتاحي:
   الكمية: 100 صندوق
   تاريخ الصلاحية: 2025-12-31

3️⃣ شراء جديد:
   الكمية: 50 صندوق
   تاريخ الصلاحية: 2026-06-15

4️⃣ الآن لدينا دفعتان:
   ┌─────────────────────────┐
   │ 2025-12-31: 100 صندوق  │ ← سيُباع أولاً (FEFO)
   │ 2026-06-15: 50 صندوق   │ ← سيُباع ثانياً
   └─────────────────────────┘

5️⃣ عند البيع:
   النظام يرغمك على اختيار 2025-12-31
   لا يمكن اختيار 2026-06-15 قبل انتهاء 2025-12-31

6️⃣ التقرير:
   2025-12-31 ← قريبة من الانتهاء (50 يوم متبقي)
   2026-06-15 ← جيدة (170 يوم متبقي)
```

---

## 🔐 الحماية من الأخطاء

النظام يحمي البيانات بعدة طرق:

```
1. ✅ Validation على مستوى العميل (Client-side)
   → إعادة تحديد تلقائي للحقل إذا حاولت اختيار خطأ

2. ✅ Validation على مستوى الخادم (Server-side)
   → فحص صارم عند الحفظ
   → رسالة خطأ واضحة إذا انتهكت القواعد

3. ✅ قاعدة البيانات (Database)
   → حفظ آمن للبيانات
   → منع التكرار غير المقصود
   → تسجيل جميع الحركات
```

---

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

### أسئلة متكررة

**س: لماذا لا أستطيع تغيير تاريخ الصلاحية في المبيعات؟**
- الجواب: لأن نظام FEFO يفرض اختيار الدفعة الأقدم أولاً للامتثال للمعايير الصحية.

**س: هل يمكن حذف دفعة من التقرير؟**
- الجواب: لا، التقرير للعرض فقط. لحذف دفعة، استخدم مرتجعات المخزون.

**س: ماذا لو كان لديّ منتج قديم بدون صلاحية؟**
- الجواب: سيبقى مع NULL، والنظام سيدعمه بدون مشاكل.

**س: كم مرة أفحص التقرير؟**
- الجواب: يومياً أو أسبوعياً على الأقل للمنتجات ذات الصلاحية القصيرة.

---

## ✅ قائمة التحقق

```
قبل البدء:
☐ فعّلت الصلاحية للمنتجات المناسبة
☐ أدخلت أرصدة افتتاحية بتواريخ صحيحة
☐ تدربت على نظام FEFO

أثناء العمل:
☐ أدخل تاريخ الصلاحية من فاتورة المورد
☐ احترم اختيار FEFO عند البيع
☐ فحص التقرير بانتظام

الصيانة:
☐ إزالة الدفعات المنتهية فوراً
☐ بيع الدفعات القريبة بأولوية
☐ توثيق كل تغيير للصلاحية
```

---

**آخر تحديث:** 20 يناير 2026  
**الإصدار:** 1.0.0