# دليل استيراد العقود من PDF

## نظرة عامة
تم إنشاء نظام قراءة العقود من ملفات PDF واستيرادها تلقائياً إلى النظام.

## الملفات المضافة

### 1. `contract_readpdf.php`
صفحة رئيسية لرفع ملف PDF العقد واستخراج البيانات منه واستيرادها.

**الوظائف الرئيسية:**
- `extractContractDataFromText($text)` - استخراج بيانات العقد من نص PDF
- `importContractFromArray($zx_contract, ...)` - استيراد العقد من مصفوفة بيانات (نفس منطق الاستيراد الحالي)

### 2. تعديل `import_contracts.php`
تم إضافة زر "قراءة عقد PDF" في قسم الأزرار العلوي يوجه إلى `contract_readpdf.php`.

## متطلبات التشغيل

### خيار 1: استخدام مكتبة PHP (موصى به)
قم بتثبيت مكتبة `smalot/pdfparser` عبر Composer:

```bash
composer require smalot/pdfparser
```

ثم في بداية `contract_readpdf.php` أضف:

```php
require_once __DIR__ . '/../../../vendor/autoload.php';
```

### خيار 2: استخدام أداة pdftotext
إذا كان السيرفر يدعم تشغيل أوامر shell، يمكن تثبيت `poppler-utils`:

**على Ubuntu/Debian:**
```bash
sudo apt-get install poppler-utils
```

**على Windows:**
- قم بتحميل Xpdf tools من: https://www.xpdfreader.com/download.html
- أضف المسار إلى متغيرات البيئة PATH

## خطوات التطوير المتبقية

### 1. تحسين دالة `extractContractDataFromText()`
حالياً الدالة تستخدم regex بسيط. يجب تحسينها بناءً على التنسيق الفعلي لملف PDF:

```php
function extractContractDataFromText($text) {
    $data = [];
    
    // استخراج جميع الحقول الـ 106 من zxcontract
    
    // مثال: رقم العقد
    if (preg_match('/رقم سجل العقد[:\s]+([0-9\/\-]+)/u', $text, $match)) {
        $data['contract_no'] = trim($match[1]);
    }
    
    // بيانات المالك
    if (preg_match('/اسم المالك[:\s]+(.+?)(?=\n|الجنسية)/u', $text, $match)) {
        $data['lessor_name'] = trim($match[1]);
    }
    
    if (preg_match('/رقم الهوية[:\s]+(\d+)/u', $text, $match)) {
        $data['lessor_id_no'] = trim($match[1]);
    }
    
    if (preg_match('/جوال[:\s]+(\+?[\d\s\-]+)/u', $text, $match)) {
        $data['lessor_mobile'] = trim($match[1]);
    }
    
    // بيانات المستأجر
    if (preg_match('/اسم المستأجر[:\s]+(.+?)(?=\n)/u', $text, $match)) {
        $data['tenant_company_name'] = trim($match[1]);
    }
    
    // بيانات العقار
    if (preg_match('/رقم الصك[:\s]+([^\n]+)/u', $text, $match)) {
        $data['title_deed_no'] = trim($match[1]);
    }
    
    if (preg_match('/نوع العقار[:\s]+([^\n]+)/u', $text, $match)) {
        $data['property_type'] = trim($match[1]);
    }
    
    if (preg_match('/استخدام العقار[:\s]+([^\n]+)/u', $text, $match)) {
        $data['property_usage'] = trim($match[1]);
    }
    
    // البيانات المالية
    if (preg_match('/القيمة الإيجارية السنوية[:\s]+([0-9,.]+)/u', $text, $match)) {
        $data['annual_rent_amount'] = floatval(str_replace(',', '', $match[1]));
    }
    
    if (preg_match('/إجمالي قيمة العقد[:\s]+([0-9,.]+)/u', $text, $match)) {
        $data['total_contract_value'] = floatval(str_replace(',', '', $match[1]));
    }
    
    // التواريخ
    if (preg_match('/تاريخ بدء الإيجار[:\s]+(\d{4}-\d{2}-\d{2}|\d{2}\/\d{2}\/\d{4})/u', $text, $match)) {
        $data['tenancy_start_date'] = convertDate($match[1]);
    }
    
    if (preg_match('/تاريخ انتهاء الإيجار[:\s]+(\d{4}-\d{2}-\d{2}|\d{2}\/\d{2}\/\d{4})/u', $text, $match)) {
        $data['tenancy_end_date'] = convertDate($match[1]);
    }
    
    // المزيد من الحقول...
    // يجب إضافة جميع الحقول الـ 106 من zxcontract
    
    return $data;
}

function convertDate($dateStr) {
    // تحويل التاريخ إلى صيغة Y-m-d
    if (preg_match('/(\d{2})\/(\d{2})\/(\d{4})/', $dateStr, $m)) {
        return $m[3] . '-' . $m[2] . '-' . $m[1];
    }
    return $dateStr;
}
```

### 2. إضافة حقول النموذج اليدوي
في حالة فشل القراءة التلقائية، يجب عرض نموذج كامل لإدخال جميع الحقول يدوياً:

```html
<div class="form-section">
    <h3><i class="fas fa-user"></i> بيانات المالك</h3>
    <div class="row">
        <div class="col-md-4 mb-3">
            <label class="form-label">اسم المالك</label>
            <input type="text" class="form-control" name="lessor_name" required>
        </div>
        <div class="col-md-4 mb-3">
            <label class="form-label">الجنسية</label>
            <input type="text" class="form-control" name="lessor_nationality">
        </div>
        <div class="col-md-4 mb-3">
            <label class="form-label">رقم الهوية</label>
            <input type="text" class="form-control" name="lessor_id_no" required>
        </div>
        <!-- المزيد من الحقول... -->
    </div>
</div>

<div class="form-section">
    <h3><i class="fas fa-building"></i> بيانات المستأجر</h3>
    <!-- حقول المستأجر -->
</div>

<div class="form-section">
    <h3><i class="fas fa-home"></i> بيانات العقار</h3>
    <!-- حقول العقار -->
</div>

<div class="form-section">
    <h3><i class="fas fa-money-bill-wave"></i> البيانات المالية</h3>
    <!-- الحقول المالية -->
</div>
```

### 3. إضافة تخزين في zxcontract (اختياري)
إذا كنت تريد حفظ البيانات في جدول `zxcontract` الخارجي أولاً:

```php
// في دالة importContractFromArray()
// بعد التحقق من البيانات وقبل البدء في الاستيراد:

if ($external_connect) {
    // إدراج في zxcontract أولاً
    $stmt = $external_connect->prepare("
        INSERT INTO zxcontract (
            contract_no, contract_type, lessor_name, lessor_id_no,
            tenant_company_name, title_deed_no, property_type,
            annual_rent_amount, total_contract_value, 
            tenancy_start_date, tenancy_end_date,
            broker_cr_no, created_at
        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW())
    ");
    
    $stmt->execute([
        $zx_contract['contract_no'],
        $zx_contract['contract_type'],
        $zx_contract['lessor_name'],
        $zx_contract['lessor_id_no'],
        $zx_contract['tenant_company_name'],
        $zx_contract['title_deed_no'],
        $zx_contract['property_type'],
        $zx_contract['annual_rent_amount'],
        $zx_contract['total_contract_value'],
        $zx_contract['tenancy_start_date'],
        $zx_contract['tenancy_end_date'],
        $office_cr
    ]);
    
    $zx_contract['id'] = $external_connect->lastInsertId();
}
```

### 4. معالجة الكيانات القانونية
يجب التحقق من وجود كيان قانوني للمؤجر (وصي قضائي، مالك مكتب، إلخ) وربطه بالعقار:

```php
// في دالة importContractFromArray()
// بعد إنشاء العقار:

if (!empty($zx_contract['lessor_rep_name']) && !empty($zx_contract['lessor_rep_id_type'])) {
    // يوجد كيان قانوني
    $entity_type = determineEntityType($zx_contract['lessor_rep_id_type']);
    
    if ($entity_type) {
        // إنشاء أو ربط الكيان
        $entity_id = createOrLinkEntity($connect, $zx_contract, $entity_type);
        
        // ربط الكيان بالعقار
        $entity_field = $entity_type . '_id'; // مثل: judicial_guardian_id
        $stmt = $connect->prepare("UPDATE properties SET $entity_field = ? WHERE id = ?");
        $stmt->execute([$entity_id, $property_id]);
    }
}

function determineEntityType($rep_id_type) {
    $mapping = [
        'وصي قضائي' => 'judicial_guardian',
        'مالك مكتب' => 'office_owner',
        'مالك مؤسسة' => 'establishment_owner',
        'مصفي شركة' => 'company_liquidator',
        'ممثل شركة' => 'company_representative',
        'مشرف وقف' => 'waqf_supervisor',
        'وكيل وكالة' => 'agency_agent',
        'ولي قاصر' => 'minor_guardian'
    ];
    
    return $mapping[$rep_id_type] ?? null;
}
```

## الاختبار

### 1. اختبار رفع ملف PDF
1. افتح `http://localhost/0f/users/office/contracts/import_contracts.php`
2. اضغط على زر "قراءة عقد PDF"
3. قم برفع ملف PDF تجريبي

### 2. اختبار الاستخراج
تحقق من أن البيانات المستخرجة صحيحة ومطابقة لمحتوى PDF.

### 3. اختبار الاستيراد
تحقق من:
- إنشاء/ربط المالك
- إنشاء/ربط المستأجر
- إنشاء/ربط العقار
- إنشاء العقد
- إنشاء سندات القبض والصرف

## الأمان

### 1. التحقق من نوع الملف
```php
$finfo = finfo_open(FILEINFO_MIME_TYPE);
$mimeType = finfo_file($finfo, $tmpPath);
finfo_close($finfo);

if ($mimeType !== 'application/pdf') {
    throw new Exception('نوع الملف غير صحيح');
}
```

### 2. حد حجم الملف
في `php.ini` أو في بداية السكريبت:
```php
ini_set('upload_max_filesize', '10M');
ini_set('post_max_size', '10M');
```

### 3. تنظيف البيانات
```php
function sanitizeExtractedData($data) {
    $clean = [];
    foreach ($data as $key => $value) {
        $clean[$key] = trim(strip_tags($value));
    }
    return $clean;
}
```

## الصيانة والتطوير المستقبلي

### 1. دعم OCR للملفات الممسوحة ضوئياً
استخدم Tesseract OCR:
```bash
sudo apt-get install tesseract-ocr tesseract-ocr-ara
```

### 2. دعم صيغ أخرى (Word, Image)
- استخدم PHPWord لملفات Word
- استخدم Intervention Image مع Tesseract للصور

### 3. تحسين دقة الاستخراج
- استخدم Machine Learning لتحديد الحقول تلقائياً
- أنشئ قوالب (templates) لأنواع مختلفة من العقود

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

1. **تنسيق PDF**: يجب أن يكون الـ PDF الحكومي بتنسيق ثابت ومتسق لضمان دقة الاستخراج.

2. **الترميز**: تأكد من دعم اللغة العربية في مكتبة PDF المستخدمة.

3. **الأداء**: معالجة ملفات PDF كبيرة قد تستغرق وقتاً - فكر في معالجة غير متزامنة (Queue) للملفات الكبيرة.

4. **السجلات**: تم إضافة سجلات تفصيلية (`error_log`) لتتبع عملية الاستيراد.

5. **المعاملات**: يتم استخدام Database Transactions لضمان سلامة البيانات.

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

للمساعدة في:
- كتابة regex patterns للحقول
- تثبيت المكتبات
- تحسين دقة الاستخراج

يرجى الرجوع إلى التوثيق الكامل في:
- `IMPORT_SYSTEM_README.md` - دليل نظام الاستيراد الشامل
- `SYSTEM_COMPLETE_GUIDE.md` - دليل النظام الكامل

