# دليل الاختبار - نظام استيراد العقود من PDF

## 🧪 خطوات الاختبار الكاملة

### المرحلة 1: التحضير والإعداد

#### 1.1 تثبيت المكتبات
```bash
cd C:\xampp\htdocs\00
composer require smalot/pdfparser
```

**أو** تثبيت pdftotext (طريقة بديلة):
- Windows: حمّل من https://www.xpdfreader.com/download.html
- أضف إلى PATH

#### 1.2 إنشاء جداول الكيانات القانونية
```bash
# في phpMyAdmin أو MySQL command line:
mysql -u root -p faradjwb_farsak < sql/create_legal_entities_tables.sql
```

**أو** نفّذ الملف مباشرة في phpMyAdmin:
1. افتح phpMyAdmin
2. اختر قاعدة `faradjwb_farsak`
3. انتقل إلى تبويب "SQL"
4. افتح الملف `sql/create_legal_entities_tables.sql`
5. انسخ والصق المحتوى
6. اضغط "تنفيذ"

#### 1.3 التحقق من الجداول
```sql
-- تأكد من إنشاء جميع الجداول
SHOW TABLES LIKE '%guardian%';
SHOW TABLES LIKE '%agent%';
SHOW TABLES LIKE '%representative%';

-- تأكد من إضافة الأعمدة في properties
DESCRIBE properties;
```

يجب أن تشاهد 8 أعمدة جديدة في `properties`:
- `judicial_guardian_id`
- `office_owner_id`
- `establishment_owner_id`
- `company_liquidator_id`
- `company_representative_id`
- `waqf_supervisor_id`
- `agency_agent_id`
- `minor_guardian_id`

---

### المرحلة 2: اختبار قراءة PDF

#### 2.1 إنشاء ملف PDF اختباري
استخدم المحتوى من `sample_contract_format.txt`:
1. افتح `sample_contract_format.txt`
2. انسخ المحتوى إلى Word
3. احفظه كـ PDF: `test_contract.pdf`
4. أو استخدم أي عقد حقيقي من منصة إيجار

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

#### 2.3 اختبار رفع PDF
1. يجب أن تفتح صفحة `contract_readpdf.php`
2. اسحب ملف PDF أو اضغط لاختياره
3. ارفع الملف

**النتيجة المتوقعة:**
- يتم قراءة الملف ✅
- تظهر رسالة نجاح أو خطأ واضحة ✅
- إذا نجحت القراءة، تُعرض بيانات مستخرجة ✅

---

### المرحلة 3: اختبار استخراج البيانات

#### 3.1 مراجعة البيانات المستخرجة
بعد رفع PDF، يجب أن تظهر:
- رقم العقد ✅
- نوع العقد ✅
- بيانات المالك (اسم، هوية، جوال) ✅
- بيانات المستأجر ✅
- بيانات العقار ✅
- البيانات المالية ✅

#### 3.2 تعديل البيانات (اختياري)
- يمكنك تعديل أي حقل قبل الحفظ
- تحقق من صحة التواريخ
- تأكد من الأرقام

#### 3.3 حفظ واستيراد
1. اضغط "حفظ واستيراد العقد"
2. راقب Console و Network في متصفح Chrome (F12)

**النتيجة المتوقعة:**
- رسالة نجاح "تم استيراد العقد بنجاح من ملف PDF" ✅
- تظهر رسالة تحتوي على `contract_id` ✅

---

### المرحلة 4: اختبار معالجة الكيانات القانونية

#### 4.1 تحضير عقد بكيان قانوني
استخدم ملف PDF يحتوي على:
- `lessor_represents_self: لا`
- `lessor_rep_name: اسم الوكيل`
- `lessor_rep_id_type: وكيل وكالة` (أو أي نوع آخر)

#### 4.2 استيراد العقد
1. ارفع الملف في `contract_readpdf.php`
2. تأكد من استخراج بيانات الممثل
3. احفظ واستورد

#### 4.3 التحقق من إنشاء الكيان
```sql
-- تحقق من إنشاء السجل في الجدول المناسب
SELECT * FROM agency_agents ORDER BY id DESC LIMIT 1;

-- تحقق من ربط الكيان بالعقار
SELECT id, main_title, agency_agent_id 
FROM properties 
WHERE agency_agent_id IS NOT NULL 
ORDER BY id DESC LIMIT 1;
```

**النتيجة المتوقعة:**
- وجود سجل جديد في `agency_agents` (أو جدول الكيان المناسب) ✅
- العقار مرتبط بالكيان عبر `agency_agent_id` ✅

#### 4.4 فحص السجلات
افتح `C:\xampp\apache\logs\error.log` وابحث عن:
```
[Entity] تم تحديد نوع الكيان: agency_agent
[Entity] إنشاء كيان جديد في agency_agents
[Entity] تم إنشاء كيان جديد: agency_agents ID XX
[Entity] تم ربط الكيان agency_agent (ID: XX) بالعقار (ID: YY)
[PDFImport] تم معالجة الكيان القانوني: agency_agent
```

---

### المرحلة 5: اختبار واجهة المراجعة

#### 5.1 فتح صفحة المراجعة
1. افتح `import_contracts.php`
2. اختر عقداً من القائمة
3. اضغط "تفاصيل"

**النتيجة المتوقعة:**
- تفتح صفحة `import_contract_details.php` ✅
- تظهر بيانات المالك والمستأجر ✅

#### 5.2 التحقق من عرض الكيان القانوني
إذا كان العقد يحتوي على كيان:
- يجب أن تظهر رسالة تحذير صفراء تحت بيانات المالك ✅
- تعرض نوع الكيان بالعربية ✅
- تعرض اسم الممثل ورقم هويته ✅
- رسالة توضيحية: "سيتم إنشاء أو ربط هذا الكيان تلقائياً" ✅

#### 5.3 استيراد من الواجهة
1. اختر خيار العقار (موجود أو جديد)
2. اضغط "استيراد العقد"

**النتيجة المتوقعة:**
- نجاح الاستيراد ✅
- إنشاء/ربط الكيان القانوني ✅
- إنشاء العقد والسندات ✅

---

### المرحلة 6: اختبار أنواع الكيانات المختلفة

قم بإنشاء 8 ملفات PDF اختبارية (أو عدّل ملف واحد) لاختبار جميع الأنواع:

#### 6.1 وصي قضائي
```
نوع الهوية: وصي قضائي
```
**الجدول**: `judicial_guardians`
**العمود**: `judicial_guardian_id`

#### 6.2 مالك مكتب
```
نوع الهوية: مالك مكتب
```
**الجدول**: `office_owners`
**العمود**: `office_owner_id`

#### 6.3 مالك مؤسسة
```
نوع الهوية: مالك مؤسسة
```
**الجدول**: `establishment_owners`
**العمود**: `establishment_owner_id`

#### 6.4 مصفي شركة
```
نوع الهوية: مصفي شركة
```
**الجدول**: `company_liquidators`
**العمود**: `company_liquidator_id`

#### 6.5 ممثل شركة
```
نوع الهوية: ممثل شركة
```
**الجدول**: `company_representatives`
**العمود**: `company_representative_id`

#### 6.6 مشرف وقف
```
نوع الهوية: مشرف وقف
```
**الجدول**: `waqf_supervisors`
**العمود**: `waqf_supervisor_id`

#### 6.7 وكيل وكالة
```
نوع الهوية: وكيل وكالة
```
**الجدول**: `agency_agents`
**العمود**: `agency_agent_id`

#### 6.8 ولي قاصر
```
نوع الهوية: ولي قاصر
```
**الجدول**: `minor_guardians`
**العمود**: `minor_guardian_id`

**للتحقق من كل نوع:**
```sql
SELECT * FROM [جدول_الكيان] ORDER BY id DESC LIMIT 1;
SELECT id, main_title, [عمود_الكيان] FROM properties WHERE [عمود_الكيان] IS NOT NULL ORDER BY id DESC LIMIT 1;
```

---

## 🐛 الأخطاء الشائعة وحلولها

### خطأ: "Class not found: Smalot\PdfParser\Parser"
**السبب**: مكتبة PDF غير مثبتة
**الحل**:
```bash
composer require smalot/pdfparser
```

### خطأ: "Table 'judicial_guardians' doesn't exist"
**السبب**: جداول الكيانات غير منشأة
**الحل**:
```bash
mysql -u root -p faradjwb_farsak < sql/create_legal_entities_tables.sql
```

### خطأ: "Column 'agency_agent_id' not found"
**السبب**: أعمدة الكيانات غير موجودة في `properties`
**الحل**: نفّذ الجزء الأخير من `create_legal_entities_tables.sql`

### خطأ: "لم يتم استخراج أي بيانات من PDF"
**السبب**: PDF ممسوح ضوئياً (صورة) وليس نصاً
**الحل**: 
1. استخدم OCR (Tesseract)
2. أو املأ البيانات يدوياً في النموذج

### خطأ: النص مشوه أو معكوس
**السبب**: مشكلة في ترميز UTF-8
**الحل**:
```php
// في contract_readpdf.php
mb_internal_encoding('UTF-8');
```

---

## ✅ قائمة التحقق النهائية

- [ ] تثبيت مكتبة PDF (composer أو pdftotext)
- [ ] إنشاء جداول الكيانات القانونية (8 جداول)
- [ ] إضافة أعمدة الكيانات في `properties` (8 أعمدة)
- [ ] اختبار رفع PDF
- [ ] اختبار استخراج البيانات
- [ ] اختبار الاستيراد الكامل
- [ ] اختبار معالجة كيان واحد على الأقل
- [ ] التحقق من السجلات في error.log
- [ ] التحقق من إنشاء العقد والسندات
- [ ] اختبار واجهة `import_contract_details.php`
- [ ] التحقق من عرض معلومات الكيان
- [ ] اختبار جميع أنواع الكيانات (اختياري)

---

## 📊 نتائج متوقعة

عند إتمام جميع الاختبارات بنجاح:

### في قاعدة البيانات:
- سجل جديد في `users` (المالك)
- سجل جديد في `woner` (ربط المالك بالمكتب)
- سجل جديد في `users` (المستأجر)
- سجل جديد في `tenant` (ربط المستأجر بالمكتب)
- سجل جديد في `properties` (العقار)
- سجل جديد في جدول الكيان (إن وُجد)
- ربط الكيان في `properties.[entity]_id`
- سجل جديد في `contracts`
- سجل جديد في `receipt_voucher`
- سجل جديد في `payment_voucher`

### في الواجهة:
- رسالة نجاح واضحة ✅
- عرض معرف العقد الجديد ✅
- إمكانية فتح تفاصيل العقد مباشرة ✅

### في السجلات:
```
[PDFImport] بدء استيراد العقد: 20092339744/1-0
[PDFImport] المالك usercode: 116
[PDFImport] المستأجر usercode: 117
[PDFImport] العقار property_id: 111
[Entity] تم تحديد نوع الكيان: agency_agent
[Entity] تم إنشاء كيان جديد: agency_agents ID 5
[Entity] تم ربط الكيان agency_agent (ID: 5) بالعقار (ID: 111)
[PDFImport] تم معالجة الكيان القانوني: agency_agent
[PDFImport] تم استيراد العقد بنجاح
```

---

## 🎓 نصائح للاختبار الفعال

1. **ابدأ بملف بسيط**: استخدم `sample_contract_format.txt` أولاً
2. **راقب السجلات**: افتح `error.log` أثناء الاختبار
3. **استخدم Chrome DevTools**: راقب Network و Console
4. **اختبر خطوة بخطوة**: لا تنتقل للمرحلة التالية قبل نجاح السابقة
5. **احتفظ بنسخة احتياطية**: قبل تشغيل SQL scripts

---

## 📞 الدعم

إذا واجهت أي مشاكل:
1. راجع `PDF_IMPORT_README.md`
2. راجع `INSTALL_PDF_LIBRARY.md`
3. تحقق من `error_log`
4. راجع `CONTRACT_PDF_IMPORT_COMPLETE.md`

**التاريخ**: 2025-11-11  
**الحالة**: جاهز للاختبار ✅

