# توثيق نظام العقود (Contracts System Documentation)

## نظرة عامة
نظام إنشاء وإدارة العقود في `users/office/contracts/create_contract.php` يعتمد على React + Ant Design بنظام خطوات متقدم.

---

## 📋 الحقول الأساسية للعقد

### 1. بيانات الأطراف (Parties)

#### أ) المالك (Owner)
- **المصدر**: يتم جلب الملاك من جدول `woner` المرتبطين بالمكتب
- **الاستعلام**:
```php
SELECT 
    u.usercode AS id,
    u.name,
    u.mobile,
    u.email,
    u.identity,
    u.city,
    u.region,
    u.nationaladdress,
    u.created_at
FROM woner w
INNER JOIN users u ON w.owner_id = u.usercode
WHERE w.office_id = :office_id
ORDER BY u.name ASC
```
- **الحقل في النموذج**: `owner_id` (required)
- **جدول الربط**: `woner` (owner_id → users.usercode, office_id)

#### ب) المستأجر (Tenant)
- **المصدر**: يتم جلب المستأجرين من جدول `tenant` المرتبطين بالمكتب
- **الاستعلام**:
```php
SELECT 
    u.usercode AS id,
    u.name,
    u.mobile,
    u.email,
    u.identity,
    u.city,
    u.region,
    u.created_at
FROM tenant t
INNER JOIN users u ON t.usercode = u.usercode
WHERE t.id_office = :office_id
ORDER BY u.name ASC
```
- **الحقل في النموذج**: `tenant_id` (required)
- **جدول الربط**: `tenant` (usercode → users.usercode, id_office)

#### ج) العقار (Property)
- **المصدر**: يتم جلب العقارات من جدول `properties` المرتبطة بالمكتب
- **الاستعلام**:
```php
SELECT 
    p.id,
    p.main_title,
    p.Region,
    p.governorate,
    p.district,
    p.property_type,
    p.TypeofStrcture,
    p.resthouse_number,
    p.status,
    p.toggle AS is_active,
    p.woner_id,
    p.title_deed_number,
    p.rental_price,
    p.sale,
    p.electrcity,
    p.water,
    p.gas,
    COALESCE(u.name, 'مؤجر غير محدد') AS owner_name
FROM properties p
LEFT JOIN users u ON p.woner_id = u.usercode
WHERE p.office_id = :office_id
ORDER BY p.main_title ASC
```
- **الحقل في النموذج**: `property_id` (required, يعتمد على owner_id)
- **الفلترة**: يتم تصفية العقارات حسب `woner_id` عند اختيار المالك
- **التحقق**: يتم التحقق من أن العقار يتبع للمالك المختار

---

### 2. بيانات العقد الأساسية

| الحقل | النوع | مطلوب | الوصف |
|------|------|-------|-------|
| `contract_number` | string | نعم | رقم العقد (يجب أن يكون فريداً داخل المكتب) |
| `contract_date` | date | نعم | تاريخ إنشاء العقد (افتراضياً: اليوم) |
| `start_date` | date | نعم | تاريخ بداية العقد |
| `start_date_hijri` | string | لا | تاريخ البداية بالهجري |
| `end_date` | date | نعم | تاريخ نهاية العقد |
| `end_date_hijri` | string | لا | تاريخ النهاية بالهجري |

---

### 3. المبالغ المالية

| الحقل | النوع | مطلوب | الوصف |
|------|------|-------|-------|
| `total_amount` | decimal | نعم | إجمالي قيمة العقد |
| `payment` | decimal | نعم | المبلغ المدفوع |
| `remaining_amount` | decimal | محسوب تلقائياً | المبلغ المتبقي (total_amount - payment) |
| `security_deposit` | decimal | لا | الضمان |
| `extra_charges` | decimal | لا | رسوم إضافية |
| `payment_type` | enum | لا | نوع الدفع: 'شهري', 'ربع سنوي', 'نصف سنوي', 'سنوي' |

---

### 4. حالة العقد

| الحقل | النوع | القيم المحتملة | الافتراضي |
|------|------|----------------|----------|
| `status` | enum | 'ساري', 'منتهي', 'ملغى', 'مغادر' | 'ساري' |

---

### 5. ملاحظات

| الحقل | النوع | مطلوب |
|------|------|-------|
| `note` | text | لا |

---

## 📅 جدول الدفعات (Payment Schedule / Installments)

### البنية
يتم إرسال جدول الدفعات كـ مصفوفة `payment_schedule` تحتوي على:

```javascript
[
    {
        due_date: 'YYYY-MM-DD',    // تاريخ استحقاق الدفعة
        amount: 1000.00,            // مبلغ الدفعة
        paid_inty: 0,               // 0 = غير مدفوعة، 1 = مدفوعة
        note: 'ملاحظة اختيارية'     // ملاحظة على الدفعة
    },
    // ... المزيد من الدفعات
]
```

### الحفظ في قاعدة البيانات
يتم حفظ كل دفعة في جدول `contract_installments`:

**الحقول المحفوظة:**
- `contract_id`: رقم العقد
- `installment_no`: رقم الدفعة (تسلسلي)
- `issue_date`: تاريخ الإصدار (يساوي due_date حالياً)
- `due_date`: تاريخ الاستحقاق
- `amount`: مبلغ الدفعة
- `paid_inty`: حالة الدفع (0/1)
- `paid_at`: تاريخ الدفع (null إذا لم تكن مدفوعة)
- `remaining_after`: المبلغ المتبقي بعد هذه الدفعة
- `note`: ملاحظة اختيارية

---

## 📁 مستندات العقد (Contract Documents)

### مكان التخزين
- **المجلد الفعلي**: `users/img/contract_docment/`
- **المسار النسبي**: `users/img/contract_docment/`
- **إنشاء المجلد**: يتم إنشاء المجلد تلقائياً إذا لم يكن موجوداً

### بنية اسم الملف
```
contract_{contract_id}_{timestamp}_{index}.{extension}
```
مثال: `contract_58_1763308925_0.jpg`

### جدول قاعدة البيانات: `contract_docment`

| الحقل | النوع | الوصف |
|------|------|-------|
| `id` | int | المعرف الفريد |
| `contract_id` | int | رقم العقد المرتبط |
| `document_type` | varchar | نوع المستند |
| `original_name` | varchar | اسم الملف الأصلي |
| `file_name` | varchar | اسم الملف الجديد المحفوظ |
| `file_extension` | varchar | امتداد الملف |
| `mime_type` | varchar | نوع الملف (MIME type) |
| `file_size` | int | حجم الملف بالبايت |
| `storage_path` | varchar | المسار النسبي: `users/img/contract_docment/{file_name}` |
| `note` | text | ملاحظة على المستند |
| `uploaded_by` | int | usercode المستخدم الذي رفع المستند |

### أنواع المستندات المدعومة
- `عقد`
- `هوية وطنية`
- `إقامة`
- `صورة عداد كهرباء`
- `صورة عداد ماء`
- `صورة عداد غاز`
- `مستند آخر`

### عملية الرفع
1. **في الواجهة**: يستخدم `Upload.Dragger` من Ant Design
2. **الملفات المقبولة**: PDF والصور فقط (`.pdf, image/*`)
3. **تجهيز البيانات**: يتم تجهيز `FormData` مع:
   - `payload`: JSON يحتوي على بيانات العقد
   - `documents[]`: الملفات نفسها
   - `document_types[]`: نوع كل مستند
   - `document_notes[]`: ملاحظة كل مستند
4. **الحفظ**: يتم نقل الملفات إلى المجلد وحفظ البيانات في `contract_docment`

---

## 🔄 تدفق البيانات (Data Flow)

### 1. جلب البيانات الأولية (PHP)
```php
// في create_contract.php
$owners = [...];        // من woner + users
$properties = [...];    // من properties
$tenants = [...];       // من tenant + users

// تحويل إلى JSON
$owners_json = json_encode($owners, JSON_UNESCAPED_UNICODE);
$properties_json = json_encode($properties, JSON_UNESCAPED_UNICODE);
$tenants_json = json_encode($tenants, JSON_UNESCAPED_UNICODE);
```

### 2. استخدام البيانات في React
```javascript
const ownersData = <?php echo $owners_json; ?>;
const propertiesData = <?php echo $properties_json; ?>;
const tenantsData = <?php echo $tenants_json; ?>;
```

### 3. إرسال البيانات عند الحفظ
```javascript
// تجهيز payload
const payload = {
    contract_number: ...,
    owner_id: ...,
    tenant_id: ...,
    property_id: ...,
    // ... باقي الحقول
    payment_schedule: [...]
};

// إضافة المستندات
const formData = new FormData();
formData.append('payload', JSON.stringify(payload));
contractDocuments.forEach((doc, index) => {
    formData.append('documents[]', doc.file);
    formData.append('document_types[]', doc.type);
    formData.append('document_notes[]', doc.note);
});

// إرسال الطلب
axios.post('create_contract_action.php', formData, {
    headers: { 'Content-Type': 'multipart/form-data' }
});
```

### 4. معالجة البيانات في Backend (PHP)
```php
// في create_contract_action.php
// 1. قراءة payload من $_POST['payload']
// 2. التحقق من صلاحيات الملاك والمستأجرين والعقارات
// 3. إدخال العقد في contracts
// 4. إدخال الدفعات في contract_installments
// 5. حفظ المستندات في contract_docment
```

---

## ✅ التحقق من الصلاحيات

### 1. التحقق من المالك
```php
SELECT 1 FROM woner 
WHERE owner_id = :owner_id AND office_id = :office_id
```

### 2. التحقق من العقار
```php
SELECT woner_id FROM properties 
WHERE id = :property_id AND office_id = :office_id
```
+ التأكد من أن العقار يتبع للمالك المختار

### 3. التحقق من المستأجر
```php
SELECT 1 FROM tenant 
WHERE usercode = :tenant_id AND id_office = :office_id
```

### 4. التحقق من رقم العقد (تفادي التكرار)
```php
SELECT id FROM contracts 
WHERE contract_number = :contract_number AND office_id = :office_id
```

---

## 📊 الجداول المستخدمة

### 1. `contracts` - الجدول الرئيسي
يحتوي على جميع بيانات العقد الأساسية

### 2. `contract_installments` - جدول الدفعات
يحتوي على جدول الدفعات المرتبط بالعقد

### 3. `contract_docment` - جدول المستندات
يحتوي على معلومات المستندات المرفقة بالعقد

### 4. `woner` - جدول الملاك
يربط الملاك بالمكاتب (owner_id, office_id)

### 5. `tenant` - جدول المستأجرين
يربط المستأجرين بالمكاتب (usercode, id_office)

### 6. `properties` - جدول العقارات
يربط العقارات بالمكاتب والمالكين (id, office_id, woner_id)

### 7. `users` - جدول المستخدمين
يحتوي على بيانات الملاك والمستأجرين

---

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

1. **جميع العمليات داخل Transaction**: يتم استخدام `beginTransaction()` و `commit()` / `rollBack()` لضمان سلامة البيانات

2. **التحقق من Office ID**: يتم التحقق من `office_id` من `$_SESSION` أو من جدول `office` بناءً على `user_id`

3. **التواريخ الافتراضية**: إذا لم يتم تحديد تاريخ، يتم استخدام تاريخ اليوم كافتراضي

4. **حساب المبلغ المتبقي**: يتم حسابه تلقائياً إذا لم يتم تحديده (`total_amount - payment`)

5. **تنسيق الملفات**: يتم تنظيف امتداد الملف من أي أحرف غير آمنة قبل الحفظ

6. **المسار النسبي**: يتم حفظ `storage_path` كمسار نسبي (`users/img/contract_docment/{file_name}`) وليس مساراً مطلقاً

---

## 🔍 مثال على بنية البيانات المرسلة

```json
{
    "contract_number": "CONTRACT-2024-001",
    "owner_id": 123,
    "tenant_id": 456,
    "property_id": 789,
    "contract_date": "2024-01-15",
    "start_date": "2024-02-01",
    "start_date_hijri": "1445-07-21",
    "end_date": "2025-01-31",
    "end_date_hijri": "1446-07-01",
    "total_amount": 12000.00,
    "payment": 3000.00,
    "remaining_amount": 9000.00,
    "security_deposit": 2000.00,
    "extra_charges": 500.00,
    "payment_type": "شهري",
    "status": "ساري",
    "note": "ملاحظة على العقد",
    "payment_schedule": [
        {
            "due_date": "2024-02-01",
            "amount": 1000.00,
            "paid_inty": 1,
            "note": "دفعة أولى"
        },
        {
            "due_date": "2024-03-01",
            "amount": 1000.00,
            "paid_inty": 0,
            "note": ""
        }
    ]
}
```

---

## 📍 الملفات الرئيسية

- `create_contract.php`: الواجهة الأمامية (React)
- `create_contract_action.php`: معالج إنشاء العقد (PHP Backend)
- `contract_view.php`: صفحة عرض تفاصيل العقد
- `edit_contract.php`: صفحة تعديل العقد

---

## 🗂️ مجلدات المستندات

```
users/
└── img/
    └── contract_docment/        ← مستندات العقود هنا
        ├── contract_58_1763308925_0.jpg
        └── ...
```

---

تم إنشاء هذا التوثيق في: 2024
آخر تحديث: 2024

