# نظام قراءة واستيراد العقود من PDF - دليل كامل

## 📋 نظرة عامة

تم إنشاء نظام متكامل لقراءة عقود PDF من المنصة الحكومية واستيرادها تلقائياً إلى النظام مع معالجة كاملة للكيانات القانونية.

---

## ✅ الميزات المنفذة

### 1. زر "قراءة عقد PDF" في صفحة الاستيراد
- **الملف**: `import_contracts.php`
- **الموقع**: قسم الأزرار العلوي بجانب زر "تحديث"
- **الوظيفة**: توجيه المستخدم إلى صفحة رفع PDF

### 2. صفحة قراءة العقد من PDF
- **الملف**: `contract_readpdf.php`
- **الميزات**:
  - واجهة رفع ملفات PDF بتصميم أخضر متناسق
  - دعم drag & drop للملفات
  - استخراج تلقائي لبيانات العقد (106 حقل)
  - عرض البيانات المستخرجة للمراجعة
  - استيراد فوري بنفس منطق الاستيراد من قاعدة البيانات الخارجية

### 3. دوال استخراج البيانات من PDF
- **الملف**: `contract_readpdf.php`
- **الدالة الرئيسية**: `extractContractDataFromText($text)`
- **الحقول المغطاة**:
  - بيانات العقد (رقم، نوع، تواريخ)
  - بيانات المالك (اسم، هوية، جوال، بريد)
  - بيانات ممثل المالك (للكيانات القانونية)
  - بيانات المستأجر (شركة أو فرد)
  - بيانات الوسيط (المكتب العقاري)
  - بيانات العقار (صك، موقع، نوع، استخدام)
  - بيانات الوحدة (مساحة، عدادات، تأثيث)
  - البيانات المالية (إيجار، تأمين، ضريبة)
  
### 4. نظام معالجة الكيانات القانونية
- **الملف**: `handle_legal_entities.php`
- **الدوال الرئيسية**:
  - `determineEntityType($contract_data)` - تحديد نوع الكيان من البيانات
  - `extractEntityData($contract_data, $entity_type)` - استخراج بيانات الكيان
  - `createOrLinkEntity($connect, $entity_data, $entity_type)` - إنشاء أو ربط الكيان
  - `linkEntityToProperty($connect, $property_id, $entity_type, $entity_id)` - ربط الكيان بالعقار
  - `processLegalEntity($connect, $contract_data, $property_id)` - دالة مجمعة للمعالجة الكاملة

- **أنواع الكيانات المدعومة** (8 أنواع):
  1. وصي قضائي (`judicial_guardian`)
  2. مالك مكتب (`office_owner`)
  3. مالك مؤسسة (`establishment_owner`)
  4. مصفي شركة (`company_liquidator`)
  5. ممثل شركة (`company_representative`)
  6. مشرف وقف (`waqf_supervisor`)
  7. وكيل وكالة (`agency_agent`)
  8. ولي قاصر (`minor_guardian`)

### 5. التكامل مع نظام الاستيراد
- **الملفات المحدثة**:
  - `import_contracts_api.php` - إضافة معالجة الكيان للاستيراد العادي
  - `contract_readpdf.php` - إضافة معالجة الكيان لاستيراد PDF
  
- **المنطق**:
  - بعد إنشاء العقار، يتم فحص بيانات العقد للكشف عن كيان قانوني
  - إذا وُجد كيان، يتم إنشاؤه أو ربطه في الجدول المناسب
  - يتم ربط الكيان بالعقار عبر الحقل المناسب في `properties`
  - المكتب الحالي يحصل على الصلاحية دائماً (`office_id`)

### 6. واجهة عرض الكيانات القانونية
- **الملف**: `import_contract_details.php`
- **الموقع**: تحت بطاقة المالك
- **المحتوى**:
  - رسالة تنبيه صفراء (warning) عند اكتشاف كيان
  - عرض نوع الكيان بالعربية
  - عرض اسم الممثل ورقم هويته وجواله
  - رسالة توضيحية بأن الكيان سيُربط تلقائياً

### 7. ملفات التوثيق والإعداد
- **`PDF_IMPORT_README.md`**: دليل شامل لنظام استيراد PDF
- **`INSTALL_PDF_LIBRARY.md`**: تعليمات تثبيت مكتبة قراءة PDF
- **`composer.json`**: ملف Composer لإدارة المكتبات
- **`CONTRACT_PDF_IMPORT_COMPLETE.md`**: (هذا الملف) ملخص كامل للنظام

---

## 🔄 سير العمل الكامل

### سيناريو 1: استيراد من PDF
1. المستخدم يضغط على "قراءة عقد PDF" في `import_contracts.php`
2. يتم توجيهه إلى `contract_readpdf.php`
3. يرفع ملف PDF
4. النظام يستخرج النص باستخدام `smalot/pdfparser` أو `pdftotext`
5. يتم تحليل النص باستخدام regex patterns
6. تُعرض البيانات المستخرجة للمراجعة
7. عند الضغط على "حفظ واستيراد":
   - إنشاء/ربط المالك
   - إنشاء/ربط المستأجر
   - إنشاء/ربط العقار
   - **معالجة الكيان القانوني** (جديد!)
   - إنشاء العقد
   - إنشاء سندات القبض والصرف
   - تأكيد المعاملة

### سيناريو 2: استيراد من قاعدة البيانات الخارجية
1. المستخدم يختار عقداً من `import_contracts.php`
2. يتم عرض `import_contract_details.php` للمراجعة
3. **عرض معلومات الكيان القانوني** (جديد!) إن وُجد
4. عند الضغط على "استيراد":
   - نفس الخطوات أعلاه بما في ذلك معالجة الكيان

---

## 🗂️ هيكل الجداول والعلاقات

### جدول `properties`
يحتوي على 8 أعمدة للكيانات القانونية:
- `judicial_guardian_id` - INT(11), NULL
- `office_owner_id` - INT(11), NULL
- `establishment_owner_id` - INT(11), NULL
- `company_liquidator_id` - INT(11), NULL
- `company_representative_id` - INT(11), NULL
- `waqf_supervisor_id` - INT(11), NULL
- `agency_agent_id` - INT(11), NULL
- `minor_guardian_id` - INT(11), NULL

### جداول الكيانات
يجب التأكد من وجود هذه الجداول:
- `judicial_guardians`
- `office_owners`
- `establishment_owners`
- `company_liquidators`
- `company_representatives`
- `waqf_supervisors`
- `agency_agents`
- `minor_guardians`

**هيكل عام لكل جدول**:
```sql
CREATE TABLE entity_table_name (
    id INT(11) PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(150) NOT NULL,
    id_type VARCHAR(50),
    id_number VARCHAR(30) NOT NULL,
    mobile VARCHAR(30),
    email VARCHAR(150),
    -- حقول خاصة بكل نوع
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_id_number (id_number)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

---

## 📝 خطوات التثبيت والإعداد

### 1. تثبيت مكتبة PDF
اختر إحدى الطريقتين:

**أ) باستخدام Composer (موصى به)**
```bash
cd C:\xampp\htdocs\00
composer require smalot/pdfparser
```

**ب) باستخدام pdftotext**
- Windows: حمّل Xpdf tools وأضفه للـ PATH
- Linux: `sudo apt-get install poppler-utils`

### 2. التحقق من الجداول
```sql
-- التحقق من وجود جداول الكيانات
SHOW TABLES LIKE '%guardian%';
SHOW TABLES LIKE '%agent%';
SHOW TABLES LIKE '%representative%';
```

### 3. إضافة الأعمدة إلى properties (إن لم تكن موجودة)
```sql
ALTER TABLE properties 
ADD COLUMN IF NOT EXISTS judicial_guardian_id INT(11) NULL,
ADD COLUMN IF NOT EXISTS office_owner_id INT(11) NULL,
ADD COLUMN IF NOT EXISTS establishment_owner_id INT(11) NULL,
ADD COLUMN IF NOT EXISTS company_liquidator_id INT(11) NULL,
ADD COLUMN IF NOT EXISTS company_representative_id INT(11) NULL,
ADD COLUMN IF NOT EXISTS waqf_supervisor_id INT(11) NULL,
ADD COLUMN IF NOT EXISTS agency_agent_id INT(11) NULL,
ADD COLUMN IF NOT EXISTS minor_guardian_id INT(11) NULL;
```

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

---

## 🔍 فحص الأخطاء (Debugging)

### سجلات النظام
تحقق من السجلات في:
- `C:\xampp\apache\logs\error.log`
- `C:\xampp\htdocs\00\error_log`

### رسائل السجل
ابحث عن رسائل تبدأ بـ:
- `[PDFImport]` - عمليات استيراد PDF
- `[Import]` - عمليات استيراد عادية
- `[Entity]` - معالجة الكيانات القانونية

### أمثلة:
```
[Entity] تم تحديد نوع الكيان: agency_agent
[Entity] إنشاء كيان جديد في agency_agents
[Entity] تم إنشاء كيان جديد: agency_agents ID 5
[Entity] تم ربط الكيان agency_agent (ID: 5) بالعقار (ID: 111)
[PDFImport] تم معالجة الكيان القانوني: agency_agent
```

---

## 🎨 التخصيص والتطوير

### تحسين دقة استخراج PDF
في `contract_readpdf.php`, دالة `extractContractDataFromText()`:
- احصل على نسخة من PDF الحكومي الفعلي
- افتحه في محرر نصوص واستخرج التنسيق
- عدّل regex patterns لتطابق التنسيق بدقة

مثال:
```php
// إذا كان التنسيق الفعلي: "رقم العقد: 20092339744/1-0"
if (preg_match('/رقم العقد:\s*([0-9\/\-]+)/u', $text, $match)) {
    $data['contract_no'] = trim($match[1]);
}
```

### إضافة كيان قانوني جديد
1. أضف الجدول الجديد في قاعدة البيانات
2. أضف العمود في `properties`
3. عدّل `determineEntityType()` لإضافة keywords
4. أضف case في `insertEntityByType()`
5. أضف الترجمة في `$entityNames` في `import_contract_details.php`

### دعم OCR للملفات الممسوحة
```bash
sudo apt-get install tesseract-ocr tesseract-ocr-ara
```

```php
// في contract_readpdf.php
if ($isScannedPDF) {
    exec("tesseract contract.pdf output -l ara", $output);
    $text = file_get_contents('output.txt');
}
```

---

## 📊 إحصائيات الأداء

### حجم الكود المضاف
- **handle_legal_entities.php**: ~450 سطر
- **contract_readpdf.php**: ~750 سطر
- **تعديلات على ملفات موجودة**: ~150 سطر
- **ملفات توثيق**: ~600 سطر

**الإجمالي**: ~1950 سطر من الكود والتوثيق

### دوال جديدة
- 7 دوال لمعالجة الكيانات
- 3 دوال لاستيراد PDF
- 1 دالة شاملة تدمج 106 حقل

---

## ✨ الخلاصة

تم إنجاز نظام متكامل يشمل:
1. ✅ زر في صفحة الاستيراد يؤدي إلى قراءة PDF
2. ✅ صفحة `contract_readpdf.php` لرفع واستخراج البيانات
3. ✅ دوال استخراج شاملة لـ 106 حقل
4. ✅ معالجة ذكية للكيانات القانونية (8 أنواع)
5. ✅ تكامل كامل مع نظام الاستيراد الموجود
6. ✅ واجهة عرض معلومات الكيان في صفحة المراجعة
7. ✅ توثيق شامل وتعليمات التثبيت
8. ✅ ملف composer.json لإدارة المكتبات

**النظام جاهز للاستخدام فور تثبيت مكتبة PDF!**

---

## 📞 الدعم والمساعدة

للمساعدة أو الاستفسارات:
- راجع `PDF_IMPORT_README.md` للتفاصيل الفنية
- راجع `INSTALL_PDF_LIBRARY.md` لمشاكل التثبيت
- تحقق من السجلات (error_log) لتتبع الأخطاء
- راجع التوثيق الكامل في `SYSTEM_COMPLETE_GUIDE.md`

**تاريخ الإنشاء**: 2025-11-11  
**الحالة**: ✅ مكتمل وجاهز للاستخدام

