# نظام استيراد العقود من المنصة الحكومية

## نظرة عامة
هذا النظام يسمح للمكاتب العقارية باستيراد العقود المسجلة في المنصة الحكومية (قاعدة بيانات `realestate_platform`) إلى نظام B (`faradjwb_farsak`) بشكل تلقائي.

## المكونات الرئيسية

### 1. ملفات الاتصال
- **external_db_connect.php**: إدارة الاتصال بقاعدة البيانات الخارجية `realestate_platform`
  - يوفر كلاس `ExternalDatabaseManager` للاتصال الآمن
  - يدعم التحقق من الاتصال واختباره

### 2. وظائف إدارة المستخدمين
- **create_or_link_user.php**: إنشاء أو ربط الملاك والمستأجرين
  - `createOrLinkOwner()`: التحقق من المالك عبر الهوية الوطنية وإنشائه إذا لم يكن موجوداً
  - `createOrLinkTenant()`: التحقق من المستأجر عبر الهوية الوطنية وإنشائه إذا لم يكن موجوداً
  - ربط تلقائي مع جداول `woner` و `tenant`

### 3. وظائف إدارة العقارات
- **create_or_link_property.php**: إنشاء أو ربط العقارات
  - `createOrLinkProperty()`: البحث عن العقار عبر رقم الصك
  - `createNewProperty()`: إنشاء عقار جديد من بيانات العقد الحكومي
  - التحقق من ملكية العقار للمكتب

### 4. تحويل البيانات (Mapping)
- **map_contract_fields.php**: تحويل حقول العقد من `zxcontract` إلى `contracts`
  - `mapContractFields()`: تحويل جميع الحقول المالية والتواريخ
  - `calculateContractStatus()`: حساب حالة العقد (ساري/منتهي)
  - `generateVoucherNumber()`: توليد أرقام السندات
  - `createReceiptVoucher()`: إنشاء سندات القبض
  - `createPaymentVoucher()`: إنشاء سندات الدفع

### 5. واجهة الاستيراد
- **import_contracts.php**: صفحة الاستيراد الرئيسية
  - عرض إحصائيات العقود المتاحة والمستوردة
  - قائمة العقود القابلة للاستيراد
  - أزرار الاستيراد الفردي والجماعي

### 6. API الاستيراد
- **import_contracts_api.php**: معالجة طلبات الاستيراد
  - `importSingleContract()`: استيراد عقد واحد
  - `importAllContracts()`: استيراد جميع العقود المتاحة
  - استخدام PDO Transactions لضمان تكامل البيانات

### 7. التحديث التلقائي
- **update_contracts_from_external.php**: تحديث العقود الموجودة
  - `updateContractsFromExternal()`: مقارنة وتحديث البيانات
  - `updateSingleContractFromExternal()`: تحديث عقد واحد
  - `scheduleContractUpdates()`: جدولة التحديثات (للاستخدام مع Cron)

## سير العمل

### 1. الاستيراد الأولي
```
المستخدم → import_contracts.php
   ↓
جلب العقود من realestate_platform.zxcontract
   ↓
فلترة حسب broker_cr_no = office.commercialRegistrationNumber
   ↓
استبعاد العقود الموجودة مسبقاً
   ↓
عرض القائمة المتاحة
```

### 2. عملية الاستيراد
```
ضغط زر "استيراد" → import_contracts_api.php
   ↓
بدء Transaction
   ↓
createOrLinkOwner() → إنشاء/ربط المالك
   ↓
createOrLinkTenant() → إنشاء/ربط المستأجر
   ↓
createOrLinkProperty() → إنشاء/ربط العقار
   ↓
mapContractFields() → تحويل البيانات
   ↓
INSERT في جدول contracts
   ↓
createReceiptVoucher() → سند قبض
   ↓
createPaymentVoucher() → سند دفع
   ↓
Commit Transaction
```

## Mapping الحقول

### من zxcontract إلى contracts

| zxcontract | contracts | ملاحظات |
|-----------|-----------|---------|
| contract_no | contract_number | رقم العقد الفريد |
| tenancy_start_date | start_date | تاريخ بداية العقد |
| tenancy_end_date | end_date | تاريخ نهاية العقد |
| annual_rent_amount | total_amount | إجمالي المبلغ |
| first_payment_amount | payment | المبلغ المدفوع |
| security_deposit | security_deposit | مبلغ التأمين |
| contract_sealing_date | contract_date | تاريخ التوقيع |
| contract_sealing_date | invoice_date | تاريخ الفاتورة |

### ربط المستخدمين

| zxcontract | users | الجدول المرتبط |
|-----------|-------|---------------|
| lessor_id_no | identity | woner |
| tenant_rep_id_no | identity | tenant |

### ربط العقارات

| zxcontract | properties |
|-----------|-----------|
| title_deed_no | title_deed_number |

## إعدادات قاعدة البيانات الخارجية

في `external_db_connect.php`، قم بتحديث الإعدادات التالية:

```php
private static function getConfig() {
    return [
        'host' => '127.0.0.1',          // عنوان السيرفر
        'database' => 'realestate_platform',  // اسم قاعدة البيانات
        'username' => 'root',           // اسم المستخدم
        'password' => '',               // كلمة المرور
        'charset' => 'utf8mb4',
        'port' => 3306
    ];
}
```

## معالجة الأخطاء

جميع العمليات محمية بـ:
- **PDO Transactions**: لضمان تكامل البيانات
- **Try-Catch Blocks**: لمعالجة الأخطاء
- **Error Logging**: تسجيل جميع الأخطاء في error_log

## الأمان

- التحقق من تسجيل الدخول في جميع الصفحات
- التحقق من ملكية المكتب للعقد عبر `broker_cr_no`
- استخدام Prepared Statements لمنع SQL Injection
- التحقق من صلاحيات المستخدم

## الاستخدام

### 1. الوصول إلى صفحة الاستيراد
```
Sidebar → إدارة العقود → استيراد العقود الحكومية
```

### 2. استيراد عقد واحد
- اضغط على زر "استيراد" بجانب العقد المطلوب
- انتظر رسالة النجاح
- سيتم تحويلك لصفحة العقود

### 3. استيراد جميع العقود
- اضغط على زر "استيراد جميع العقود"
- انتظر حتى تكتمل العملية
- راجع التقرير النهائي

## الجدولة التلقائية (Cron Job)

لتحديث العقود تلقائياً بشكل دوري:

```php
require_once 'external_db_connect.php';
require_once 'update_contracts_from_external.php';
require_once '../includes/db-connect-test.php';

$office_id = 1; // معرف المكتب
$result = scheduleContractUpdates($connect, $external_connect, $office_id);

if ($result['success']) {
    echo "تم التحديث: {$result['updated_count']} عقد";
}
```

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

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

## دعم فني

في حالة وجود مشاكل:
1. راجع `error_log` للأخطاء
2. تحقق من اتصال قاعدة البيانات الخارجية
3. تأكد من صحة السجل التجاري
4. تحقق من صلاحيات قاعدة البيانات

## الإصدار
- **تاريخ الإنشاء**: 2025-11-03
- **الإصدار**: 1.0.0
- **المطور**: B للتطوير العقاري

