# 📤 نظام رفع المستندات - سندات الصرف

## 🎯 نظرة عامة

نظام رفع متعدد للمستندات (صور و PDF) مع سندات الصرف، يدعم:
- ✅ رفع متعدد
- ✅ التحقق الأمني الشامل
- ✅ معاينة قبل الرفع
- ✅ إدارة المستندات

---

## 📁 الملفات

### 1. **upload_receipt_document.php**
- **المهمة**: رفع ملف واحد للخادم
- **الطلب**: POST مع FormData
- **المعاملات**:
  - `document`: الملف
  - `uploaded_by`: معرف المستخدم (اختياري)

**مثال على الاستخدام:**
```javascript
const formData = new FormData();
formData.append('document', file);
formData.append('uploaded_by', userCode);

const response = await axios.post('upload_receipt_document.php', formData);
```

### 2. **save_receipt_documents.php**
- **المهمة**: حفظ بيانات المستندات في قاعدة البيانات
- **الطلب**: POST مع JSON
- **المعاملات**:
  - `receipt_voucher_id`: معرف السند
  - `documents`: مصفوفة المستندات

**مثال:**
```javascript
await axios.post('save_receipt_documents.php', {
    receipt_voucher_id: voucherId,
    documents: [
        { name: 'file1.jpg', path: 'users/img/receiptvoucher/doc_123.jpg' },
        { name: 'file2.pdf', path: 'users/img/receiptvoucher/doc_124.pdf' }
    ]
});
```

---

## 🔐 التحقق الأمني

### 1. **الجلسة**
```php
✅ session_start()
✅ التحقق من SESSION_USER_CODE
✅ جلب office_id من قاعدة البيانات
```

### 2. **نوع الملف**
```php
// الامتدادات المسموحة
['jpg', 'jpeg', 'png', 'gif', 'pdf']

// أنواع MIME المسموحة
[
    'image/jpeg',
    'image/jpg', 
    'image/pjpeg',
    'image/png',
    'image/gif',
    'application/pdf',
    'application/x-pdf'
]
```

### 3. **الحجم**
```php
الحد الأقصى: 10 ميجابايت (10 * 1024 * 1024 bytes)
```

### 4. **الصلاحيات**
```php
✅ التحقق من وجود المجلد
✅ التحقق من إمكانية الكتابة
✅ إنشاء المجلد تلقائياً (0755)
```

---

## 📊 تدفق العمل

### **رفع المستندات:**

```
1. المستخدم يختار ملف/ملفات
   ↓
2. التحقق من النوع والحجم (Client-side)
   ↓
3. رفع كل ملف على حدة (upload_receipt_document.php)
   ↓
4. حفظ المسار في State
   ↓
5. عند حفظ السند → حفظ بيانات المستندات (save_receipt_documents.php)
```

### **استرجاع المستندات:**

```
1. جلب السند من قاعدة البيانات
   ↓
2. جلب المستندات المرتبطة من receipt_voucher_documents
   ↓
3. عرض القائمة مع روابط التحميل/المعاينة
```

---

## 🗂️ بنية المجلدات

```
C:\xampp\htdocs\00\
└── users\
    └── img\
        └── receiptvoucher\
            ├── doc_7_1730000000_abc123.jpg
            ├── doc_7_1730000001_def456.pdf
            └── doc_7_1730000002_ghi789.png
```

**تسمية الملفات:**
```
doc_{office_id}_{timestamp}_{unique_id}.{extension}
```

---

## 🧪 الاختبار

### **1. اختبار الإعدادات**
```
URL: http://localhost/0f/users/office/receipts/test_upload_config.php
```

**يفحص:**
- ✅ file_uploads
- ✅ upload_max_filesize
- ✅ post_max_size
- ✅ memory_limit
- ✅ وجود وصلاحيات المجلد

### **2. اختبار الرفع**
```
URL: http://localhost/0f/users/office/receipts/add_sand_new.php
```

**الخطوات:**
1. اختر مؤجر/مستأجر
2. اختر عقد
3. انتقل لقسم "المستندات المرفقة"
4. اضغط على زر الرفع
5. اختر صور أو ملفات PDF
6. تأكد من ظهورها في القائمة

---

## ⚙️ إعدادات PHP

### **في php.ini:**
```ini
file_uploads = On
upload_max_filesize = 20M
post_max_size = 25M
max_execution_time = 300
max_input_time = 300
memory_limit = 256M
```

### **في .htaccess:**
```apache
php_value upload_max_filesize 20M
php_value post_max_size 25M
php_value max_execution_time 300
php_value memory_limit 256M
```

---

## 🐛 حل المشاكل

### **خطأ: "غير مصرح"**
```
السبب: الجلسة غير صالحة
الحل: تأكد من تسجيل الدخول
```

### **خطأ: "نوع الملف غير مدعوم"**
```
السبب: الملف ليس صورة أو PDF
الحل: استخدم JPG, PNG, GIF, أو PDF فقط
```

### **خطأ: "حجم الملف كبير جداً"**
```
السبب: الملف أكبر من 10 ميجابايت
الحل: 
  1. ضغط الصورة
  2. أو رفع إعدادات PHP
```

### **خطأ: "فشل في نقل الملف"**
```
السبب: صلاحيات المجلد
الحل:
  1. تحقق من وجود المجلد
  2. chmod 0755 receiptvoucher/
  3. تأكد من ملكية Apache/www-data
```

---

## 📋 قاعدة البيانات

### **جدول: receipt_voucher_documents**
```sql
CREATE TABLE receipt_voucher_documents (
    id INT AUTO_INCREMENT PRIMARY KEY,
    receipt_voucher_id INT NOT NULL,
    document_name VARCHAR(255),
    document_path VARCHAR(500),
    uploaded_by INT NOT NULL,
    uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (receipt_voucher_id) REFERENCES receipts_voucher(id)
);
```

---

## 🔗 روابط سريعة

- 📊 **الإحصائيات**: اختبر الإعدادات
- 📤 **الرفع**: صفحة سندات الصرف
- 🗃️ **المجلد**: `C:\xampp\htdocs\00\users\img\receiptvoucher\`

---

## 📝 ملاحظات

1. **الأمان**: جميع الملفات تُفحص من حيث النوع والحجم
2. **الأسماء الفريدة**: كل ملف له اسم فريد لتجنب التضارب
3. **الربط بالمكتب**: كل ملف مرتبط بـ office_id
4. **الحذف**: يجب حذف الملفات من القرص عند حذف السند

---

**تاريخ التحديث:** 2025-01-26
**الإصدار:** 2.0

