# 📚 توثيق نظام تعديل العقار - نظام الأسئلة

## 🎯 **نظرة عامة**

تم إنشاء نظام ذكي لتعديل العقار بناءً على **سيناريوهات متعددة** تغطي جميع حالات الاستخدام:

```
زر التعديل في view_properties.php
         ↓
prepare_edit_property.php (صفحة الفحص والأسئلة)
         ↓
    ┌────┴────┐
    │ الأسئلة │
    └────┬────┘
         ├─→ تغيير المالك فقط
         ├─→ تغيير/إضافة الصفة القانونية فقط
         ├─→ تغيير كليهما
         └─→ تعديل العقار مباشرة (بدون تغيير)
         ↓
edit_property_simple.php (تعديل بيانات العقار)
```

---

## 📁 **الملفات المنشأة**

### 1. **`prepare_edit_property.php`** - صفحة الفحص الأولية ✅

**الوظيفة:**
- نقطة الدخول الرئيسية لتعديل العقار
- عرض اسم العقار من `main_title`
- فحص الكيان القانوني الحالي (8 حقول محتملة)
- عرض أسئلة ذكية حسب الحالة

**المدخلات:**
```php
GET prepare_edit_property.php?property_id=123
```

**سير العمل:**
```
1. جلب بيانات العقار + المالك
2. فحص الكيانات القانونية (8 حقول):
   - judicial_guardian_id
   - office_owner_id  
   - establishment_owner_id
   - company_liquidator_id
   - company_representative_id
   - waqf_supervisor_id
   - agency_agent_id
   - minor_guardian_id
3. تحديد: هل يوجد كيان حالي؟
4. عرض الأسئلة
```

**الأسئلة:**

#### **سؤال 1: تغيير المالك؟**
```
┌──────────────────────────────────────────┐
│ 👤 هل تود تغيير المالك؟                 │
├──────────────────────────────────────────┤
│ المالك الحالي:                          │
│ ✓ أحمد محمد                             │
│ 📱 0501234567                            │
├──────────────────────────────────────────┤
│ [نعم، أريد تغيير المالك]               │
│ [لا، الإبقاء على المالك الحالي]        │
└──────────────────────────────────────────┘
```

**الإجراءات:**
- **نعم** → الانتقال إلى `change_property_owner.php`
- **لا** → الانتقال للسؤال التالي

---

#### **سؤال 2: تغيير/إضافة الصفة القانونية؟**

**حالة 1: يوجد كيان قانوني حالي**
```
┌──────────────────────────────────────────┐
│ 💼 هل تود تغيير الصفة القانونية؟       │
├──────────────────────────────────────────┤
│ الصفة القانونية الحالية:               │
│ 🏢 مكتب عقاري                           │
├──────────────────────────────────────────┤
│ [نعم، أريد التغيير]                    │
│ [لا، الإبقاء على الصفة الحالية]        │
└──────────────────────────────────────────┘
```

**حالة 2: لا يوجد كيان قانوني**
```
┌──────────────────────────────────────────┐
│ 💼 هل تود إضافة صفة قانونية للعقار؟     │
├──────────────────────────────────────────┤
│ ℹ️ لا توجد صفة قانونية مسجلة حالياً     │
│ الصفة القانونية تحدد العلاقة القانونية │
│ للمؤجر بالعقار (وكيل، وصي، إلخ).       │
├──────────────────────────────────────────┤
│ [نعم، أريد الإضافة]                    │
│ [لا، المتابعة بدون صفة قانونية]         │
└──────────────────────────────────────────┘
```

**الإجراءات:**
- **نعم** → الانتقال إلى `change_property_entity.php`
- **لا** → عرض الإجراءات النهائية

---

#### **الإجراءات النهائية**
```
┌──────────────────────────────────────────┐
│ ✅ جاهز للمتابعة!                        │
├──────────────────────────────────────────┤
│ اختر الإجراء المناسب:                   │
│                                          │
│ [📝 تعديل بيانات العقار]                │
│                                          │
│ [← العودة إلى قائمة العقارات]           │
└──────────────────────────────────────────┘
```

---

### 2. **`change_property_owner.php`** - تغيير المالك ✅

**الوظيفة:**
- عرض قائمة الملاك المسجلين لدى المكتب
- بحث بالاسم/الهوية/الجوال
- زر "إضافة مؤجر جديد" (يفتح صفحة منفصلة)
- تحديث `woner_id` في جدول `properties`

**سير العمل:**
```
1. عرض قائمة الملاك
2. البحث/الاختيار
3. الضغط على "حفظ وتغيير المالك"
4. تحديث قاعدة البيانات:
   - البحث عن woner.id حيث owner_id = المختار AND office_id = المكتب
   - UPDATE properties SET woner_id = woner.id WHERE id = property_id
5. العودة إلى prepare_edit_property.php
```

**كود التحديث:**
```php
// البحث عن woner.id المناسب
$check_query = "SELECT id FROM woner WHERE owner_id = ? AND office_id = ?";
$check_stmt = $pdo->prepare($check_query);
$check_stmt->execute([$new_owner_id, $office_id]);
$woner_row = $check_stmt->fetch(PDO::FETCH_ASSOC);

if ($woner_row) {
    // تحديث العقار
    $update_query = "UPDATE properties SET woner_id = ? WHERE id = ? AND office_id = ?";
    $update_stmt = $pdo->prepare($update_query);
    $update_stmt->execute([$woner_row['id'], $property_id, $office_id]);
}
```

---

### 3. **`change_property_entity.php`** - تغيير/إضافة الصفة القانونية ✅

**الوظيفة:**
- عرض قائمة الصفات القانونية (8 أنواع)
- إدخال بيانات الصفة المختارة
- خيار إزالة الصفة القانونية (إذا كانت موجودة)
- حفظ عبر API

**الصفات المدعومة:**
```
1. وصي/ولي قضائي        → judicial_guardian_id
2. مكتب عقاري           → office_owner_id
3. مالك مؤسسة           → establishment_owner_id
4. مصفي شركة            → company_liquidator_id
5. ممثل شركة            → company_representative_id
6. مشرف وقف             → waqf_supervisor_id
7. وكيل (وكالة)         → agency_agent_id
8. ولي قاصر            → minor_guardian_id
```

**سير العمل:**
```
1. عرض الصفة الحالية (إن وجدت)
2. اختيار صفة جديدة من القائمة
3. إدخال بيانات الصفة
4. الضغط على "حفظ والمتابعة"
5. حفظ عبر update_property_entity_api.php
6. العودة إلى prepare_edit_property.php
```

---

### 4. **`update_property_entity_api.php`** - API تحديث الكيان ✅

**الوظيفة:**
- API لإضافة/تحديث/إزالة الكيان القانوني

**المدخلات:**
```json
POST update_property_entity_api.php
Content-Type: application/json

{
  "property_id": 123,
  "action": "update_entity",
  "entity_type": "office_owner",
  "entity_data": {
    "license_number": "123456",
    "office_name": "مكتب النور",
    "issued_from": "وزارة التجارة"
  }
}
```

**الإجراءات المدعومة:**

#### **أ) `action: "update_entity"` - إضافة/تحديث كيان**
```sql
1. إزالة جميع الكيانات القديمة:
   UPDATE properties SET 
      judicial_guardian_id = NULL,
      office_owner_id = NULL,
      ... (كل الحقول) ...
   WHERE id = property_id

2. إدراج الكيان الجديد في الجدول المناسب:
   INSERT INTO legal_entity_{type} (...) VALUES (...)
   
3. الحصول على entity_id = LAST_INSERT_ID()

4. تحديث العقار:
   UPDATE properties SET {type}_id = entity_id WHERE id = property_id
```

#### **ب) `action: "remove_entity"` - إزالة كيان**
```sql
UPDATE properties SET 
   judicial_guardian_id = NULL,
   office_owner_id = NULL,
   ... (كل الحقول) ...
WHERE id = property_id AND office_id = office_id
```

**الاستجابة:**
```json
{
  "success": true,
  "message": "تم حفظ الصفة القانونية بنجاح",
  "entity_id": 456
}
```

---

## 🔄 **سير العمل الكامل (All Scenarios)**

### **السيناريو 1: تعديل العقار مباشرة (بدون تغيير المالك أو الكيان)**
```
prepare_edit_property.php
   ↓
السؤال 1: تغيير المالك؟ → لا
   ↓
السؤال 2: تغيير الكيان؟ → لا
   ↓
الإجراءات النهائية
   ↓
edit_property_simple.php ← تعديل بيانات العقار
```

---

### **السيناريو 2: تغيير المالك فقط**
```
prepare_edit_property.php
   ↓
السؤال 1: تغيير المالك؟ → نعم
   ↓
change_property_owner.php
   ├─ عرض قائمة الملاك
   ├─ بحث/اختيار
   ├─ [+ إضافة مؤجر جديد]
   └─ حفظ → UPDATE properties.woner_id
   ↓
العودة إلى prepare_edit_property.php
   ↓
السؤال 2: تغيير الكيان؟ → لا
   ↓
edit_property_simple.php
```

---

### **السيناريو 3: تغيير/إضافة الصفة القانونية فقط**
```
prepare_edit_property.php
   ↓
السؤال 1: تغيير المالك؟ → لا
   ↓
السؤال 2: تغيير الكيان؟ → نعم
   ↓
change_property_entity.php
   ├─ اختيار نوع الكيان (8 أنواع)
   ├─ إدخال بيانات الكيان
   ├─ [🗑️ إزالة الصفة] (إذا كانت موجودة)
   └─ حفظ → update_property_entity_api.php
   ↓
العودة إلى prepare_edit_property.php
   ↓
edit_property_simple.php
```

---

### **السيناريو 4: تغيير كليهما (المالك + الصفة القانونية)**
```
prepare_edit_property.php
   ↓
السؤال 1: تغيير المالك؟ → نعم
   ↓
change_property_owner.php → حفظ
   ↓
العودة إلى prepare_edit_property.php
   ↓
السؤال 2: تغيير الكيان؟ → نعم
   ↓
change_property_entity.php → حفظ
   ↓
العودة إلى prepare_edit_property.php
   ↓
edit_property_simple.php
```

---

## 📊 **جداول قاعدة البيانات المتأثرة**

### **جدول `properties`**
```sql
-- حقل المالك
woner_id INT(11) → woner.id

-- حقول الكيانات القانونية (8 حقول)
judicial_guardian_id INT(11) → legal_entity_judicial_guardian.id
office_owner_id INT(11) → legal_entity_office_owner.id
establishment_owner_id INT(11) → legal_entity_establishment_owner.id
company_liquidator_id INT(11) → legal_entity_company_liquidator.id
company_representative_id INT(11) → legal_entity_company_representative.id
waqf_supervisor_id INT(11) → legal_entity_waqf_supervisor.id
agency_agent_id INT(11) → legal_entity_agency_agent.id
minor_guardian_id INT(11) → legal_entity_minor_guardian.id
```

### **جدول `woner`**
```sql
id INT(11) PRIMARY KEY AUTO_INCREMENT
owner_id INT(11) → users.usercode (المالك)
office_id INT(11) → office.id (المكتب)
```

### **جداول الكيانات القانونية (8 جداول)**
```sql
legal_entity_judicial_guardian
legal_entity_office_owner
legal_entity_establishment_owner
legal_entity_company_liquidator
legal_entity_company_representative
legal_entity_waqf_supervisor
legal_entity_agency_agent
legal_entity_minor_guardian
```

---

## 🔒 **الأمان والصلاحيات**

### **الفحوصات الأمنية:**
1. ✅ التحقق من تسجيل الدخول
2. ✅ التحقق من نوع المستخدم (مكتب عقاري فقط)
3. ✅ التحقق من `office_id` في الجلسة
4. ✅ التحقق من ملكية العقار: `WHERE p.id = ? AND p.office_id = ?`
5. ✅ عرض الملاك المسجلين لدى المكتب فقط

---

## 🎨 **التصميم والهوية البصرية**

### **الألوان:**
- **الأخضر الداكن:** `#206843` (اللون الأساسي)
- **الأخضر الفاتح:** `#28a745` (النجاح)
- **الأزرق:** `#17a2b8` (المعلومات)
- **الأصفر:** `#ffc107` (التحذير)
- **الأحمر:** `#dc3545` (الخطر/الإزالة)

### **الخلفية:**
```css
background: #ffffff;
background-image: 
    linear-gradient(45deg, #f8fafc 25%, transparent 25%),
    linear-gradient(-45deg, #f8fafc 25%, transparent 25%),
    linear-gradient(45deg, transparent 75%, #f8fafc 75%),
    linear-gradient(-45deg, transparent 75%, #f8fafc 75%);
background-size: 60px 60px;
```

---

## 📝 **أمثلة على الحالات**

### **مثال 1: عقار بمؤجر فقط (بدون كيان)**
```
البيانات الحالية:
- المالك: أحمد محمد (usercode: 123)
- woner_id: 45 (woner.id)
- جميع حقول الكيانات: NULL

الأسئلة:
1. تغيير المالك؟
2. إضافة صفة قانونية؟ ← "إضافة" وليس "تغيير"
```

### **مثال 2: عقار بمؤجر + مكتب عقاري**
```
البيانات الحالية:
- المالك: أحمد محمد
- office_owner_id: 78
- بقية الكيانات: NULL

الأسئلة:
1. تغيير المالك؟
2. تغيير الصفة القانونية؟ ← "تغيير" لأن office_owner_id موجود
```

### **مثال 3: عقار بمؤجر + وكالة**
```
البيانات الحالية:
- المالك: أحمد محمد
- agency_agent_id: 99
- بقية الكيانات: NULL

الأسئلة:
1. تغيير المالك؟
2. تغيير الصفة القانونية؟ ← "تغيير"
   - خيار إضافي: [🗑️ إزالة الصفة القانونية]
```

---

## ✅ **مميزات النظام**

### **1. المرونة التامة:**
- ✅ يمكن تغيير المالك فقط
- ✅ يمكن تغيير الكيان فقط
- ✅ يمكن تغيير كليهما
- ✅ يمكن تخطي كل شيء والذهاب للتعديل مباشرة

### **2. الذكاء:**
- ✅ يفحص وجود كيان قانوني تلقائياً
- ✅ يعرض "تغيير" أو "إضافة" حسب الحالة
- ✅ يعرض خيار "إزالة الكيان" فقط إذا كان موجود

### **3. سهولة الاستخدام:**
- ✅ أسئلة واضحة
- ✅ أزرار كبيرة ملونة
- ✅ رسائل توضيحية
- ✅ تأكيدات قبل الإجراءات المهمة

### **4. الأمان:**
- ✅ التحقق من الصلاحيات في كل صفحة
- ✅ استعلامات محمية ضد SQL Injection
- ✅ عزل البيانات بين المكاتب

---

## 🚀 **كيفية الاستخدام**

### **للمستخدم (المكتب العقاري):**

1. **افتح قائمة العقارات:**
   ```
   https://localhost/0f/users/office/property/view_properties.php
   ```

2. **اضغط زر "تعديل" على أي عقار:**
   ```
   → ستفتح prepare_edit_property.php?property_id=123
   ```

3. **أجب على الأسئلة:**
   - هل تريد تغيير المالك؟ [نعم/لا]
   - هل تريد تغيير/إضافة الصفة القانونية؟ [نعم/لا]

4. **اختر الإجراء:**
   - تعديل بيانات العقار → `edit_property_simple.php`
   - العودة → `view_properties.php`

---

## 📈 **التحسينات المستقبلية**

- [ ] عرض تاريخ التعديلات (Audit Log)
- [ ] إشعارات للمؤجر عند التغيير
- [ ] دعم تعدد الملاك
- [ ] معاينة قبل الحفظ
- [ ] التراجع عن التغييرات

---

**تاريخ الإنشاء:** 2025-11-02  
**الإصدار:** 2.0 (نظام الأسئلة المنفصل)  
**الحالة:** ✅ جاهز للاستخدام والاختبار

