# شرح نظام التعامل مع ملف Excel

## 📊 ميزات النظام الجديد

تم إضافة نظام متكامل للتعامل مع ملف Excel (db.xlsx) يوفر:

✅ **حفظ البيانات** - تصدير جميع البيانات من قاعدة البيانات إلى Excel  
✅ **التعديل** - تحديث البيانات في Excel وقاعدة البيانات  
✅ **الحذف** - حذف السجلات مع التحديث التلقائي  
✅ **الاستيراد** - استيراد البيانات من Excel إلى قاعدة البيانات  

---

## 🔌 API Endpoints

### 1. تصدير البيانات إلى Excel
```
GET /api/excel/export
```
**الوصف:** تصدير جميع البيانات من قاعدة البيانات إلى ملف `db.xlsx`

**الرد:**
```json
{
  "success": true,
  "path": "server/data/db.xlsx",
  "message": "تم تصدير البيانات بنجاح"
}
```

---

### 2. تحميل ملف Excel
```
GET /api/excel/download
```
**الوصف:** تحميل ملف `db.xlsx` على الجهاز

**الاستخدام:** يتم تحميل الملف تلقائياً

---

### 3. استيراد البيانات من Excel
```
POST /api/excel/import
```
**الوصف:** استيراد البيانات من ملف Excel وإضافتها أو تحديثها في قاعدة البيانات

**الرد:**
```json
{
  "success": true,
  "stats": {
    "imported": 5,
    "updated": 2,
    "errors": 0
  },
  "message": "تم استيراد 5 سجل جديد وتحديث 2 سجل"
}
```

---

### 4. تحديث سجل وحفظه في Excel
```
PUT /api/excel/update/:table/:id
```
**المتغيرات:**
- `table` - اسم الجدول (branches, employees, suppliers, categories, products, sales, inventory)
- `id` - رقم السجل

**مثال:**
```
PUT /api/excel/update/employees/1
```

**البيانات:**
```json
{
  "name": "أحمد محمد",
  "phone": "0501234567",
  "position": "مدير"
}
```

**الرد:**
```json
{
  "success": true,
  "message": "تم تحديث السجل بنجاح"
}
```

---

### 5. حذف سجل من Excel والقاعدة
```
DELETE /api/excel/delete/:table/:id
```
**المتغيرات:**
- `table` - اسم الجدول
- `id` - رقم السجل

**مثال:**
```
DELETE /api/excel/delete/employees/1
```

**الرد:**
```json
{
  "success": true,
  "message": "تم حذف السجل بنجاح من employees"
}
```

---

## 📋 محتويات ملف Excel

يحتوي ملف `db.xlsx` على عدة ورقات (Sheets):

| الورقة | الوصف |
|-------|-------|
| **الفروع** | بيانات الفروع (branches) |
| **الموظفون** | بيانات الموظفين (employees) |
| **الموردون** | بيانات الموردين (suppliers) |
| **الأقسام** | بيانات الأقسام (categories) |
| **المنتجات** | بيانات المنتجات (products) |
| **المبيعات** | بيانات المبيعات (sales) |
| **المخزون** | بيانات المخزون (inventory) |

---

## 🚀 كيفية الاستخدام

### خطوة 1: تصدير البيانات الحالية

استدعي الـ API:
```
GET http://localhost:3000/api/excel/export
```

سيتم إنشاء ملف `db.xlsx` في مجلد `server/data/`

### خطوة 2: تحميل الملف

استدعي الـ API:
```
GET http://localhost:3000/api/excel/download
```

سيتم تحميل الملف على جهازك

### خطوة 3: تعديل البيانات

يمكنك تعديل البيانات مباشرة في ملف Excel:
- فتح الملف بـ Excel أو Google Sheets
- تعديل البيانات
- حفظ الملف

### خطوة 4: استيراد البيانات المعدلة

ضع الملف المعدل في مجلد `server/data/` باسم `db.xlsx` ثم استدعي:
```
POST http://localhost:3000/api/excel/import
```

سيتم تحديث قاعدة البيانات تلقائياً

---

## 💡 ملاحظات مهمة

1. **معرف فريد:** استخدم حقل `code` كمعرف فريد للبيانات
2. **عند التحديث:** إذا كان `code` موجوداً، سيتم تحديث السجل
3. **عند الإضافة:** إذا كان `code` جديداً، سيتم إضافة سجل جديد
4. **التصديق:** تأكد من صحة البيانات قبل الاستيراد
5. **النسخ الاحتياطية:** احتفظ بنسخة احتياطية قبل الاستيراد

---

## 📝 أمثلة استخدام

### إضافة موظف جديد عبر Excel

1. حمّل ملف Excel
2. ادخل البيانات في ورقة "الموظفون":
   ```
   code: E001
   name: محمد علي
   position: مدير
   phone: 0501234567
   email: m.ali@example.com
   ```
3. استورد الملف بـ API

### تحديث بيانات موظف

1. استدعي `GET /api/excel/update/employees/1` بـ:
   ```json
   {
     "name": "محمد علي محمود",
     "phone": "0505555555"
   }
   ```
2. سيتم التحديث في الفور وحفظه في Excel

### حذف موظف

```
DELETE /api/excel/delete/employees/1
```

السجل سيُحذف من القاعدة و Excel معاً

---

## 🛠️ المتطلبات المثبتة

✅ `xlsx` - مكتبة Excel للـ Node.js  
✅ `express` - خادم الويب  
✅ `better-sqlite3` - قاعدة البيانات

كل شيء مثبت بالفعل!

---

## ❓ استكشاف الأخطاء

| المشكلة | الحل |
|--------|------|
| ملف Excel غير موجود | استدعِ `/api/excel/export` أولاً |
| البيانات لم تُحدّث | تأكد من استخدام `code` الصحيح |
| خطأ في الاستيراد | تحقق من صيغة البيانات والأعمدة |
| لا يوجد سجلات | تأكد من وجود بيانات في قاعدة البيانات |

---

**تم الإنشاء بنجاح! ✅**
