# 📚 دليل النظام الكامل - تعديل المالك والكيان القانوني

## ✅ **تم الإنجاز بنجاح!**

تم إنشاء نظام متكامل لتعديل المالك والكيان القانوني بشكل منفصل عن تعديل بيانات العقار.

---

## 🎯 **المشكلة التي تم حلها**

### **قبل:**
```
زر تعديل → edit_property_simple.php مباشرة
❌ لا يمكن تغيير المالك
❌ لا يمكن تغيير الكيان القانوني
❌ خلط بين تعديل العقار وتعديل المالك/الكيان
```

### **بعد:**
```
زر تعديل → prepare_edit_property.php (صفحة فحص)
   ↓
أسئلة ذكية:
   1. تغيير المالك؟ → نعم/لا
   2. تغيير/إضافة الكيان القانوني؟ → نعم/لا
   ↓
edit_property_simple.php (تعديل بيانات العقار)

✅ يمكن تغيير المالك فقط
✅ يمكن تغيير الكيان فقط
✅ يمكن تغيير كليهما
✅ يمكن تخطي كل شيء والتعديل مباشرة
```

---

## 📁 **الملفات المنشأة (4 ملفات جديدة)**

### 1️⃣ **`prepare_edit_property.php`** - نقطة الدخول الرئيسية

**الرابط:**
```
GET prepare_edit_property.php?property_id=123
```

**الوظيفة:**
- ✅ جلب اسم العقار من `main_title`
- ✅ جلب بيانات المالك الحالي
- ✅ فحص الكيانات القانونية (8 حقول)
- ✅ عرض سؤالين بشكل تدريجي

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

```
┌─────────────────────────────────────────┐
│ السؤال 1: هل تود تغيير المالك؟        │
├─────────────────────────────────────────┤
│ المالك الحالي: أحمد محمد               │
│ 📱 0501234567                           │
│ 🆔 1234567890                           │
├─────────────────────────────────────────┤
│ [نعم، أريد تغيير المالك]              │
│ [لا، الإبقاء على المالك الحالي]       │
└─────────────────────────────────────────┘
         ↓ (بعد الإجابة)
┌─────────────────────────────────────────┐
│ السؤال 2: هل تود تغيير/إضافة الصفة؟   │
├─────────────────────────────────────────┤
│ الصفة الحالية: مكتب عقاري              │
│ (أو: لا توجد صفة قانونية)              │
├─────────────────────────────────────────┤
│ [نعم، أريد التغيير/الإضافة]           │
│ [لا، الإبقاء/المتابعة بدون صفة]        │
└─────────────────────────────────────────┘
         ↓ (بعد الإجابة)
┌─────────────────────────────────────────┐
│ ✅ جاهز للمتابعة!                      │
├─────────────────────────────────────────┤
│ [📝 تعديل بيانات العقار]              │
│ [← العودة إلى قائمة العقارات]         │
└─────────────────────────────────────────┘
```

**حالة خاصة: عقار بدون مؤجر**
```
المالك الحالي:
┌─────────────────────────────────────────┐
│ 🏢 المكتب العقاري                      │
│ ℹ️ هذا العقار غير مربوط بمؤجر محدد    │
└─────────────────────────────────────────┘
```

---

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

**الرابط:**
```
GET change_property_owner.php?property_id=123
```

**الميزات:**
- ✅ عرض اسم العقار في الأعلى
- ✅ بحث بالاسم/الهوية/الجوال
- ✅ بطاقات تفاعلية للمؤجرين
- ✅ زر "إضافة مؤجر جديد" (يفتح نافذة منفصلة)
- ✅ تحديث فوري في قاعدة البيانات

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

**زر إضافة مؤجر جديد:**
- يفتح `../worners/add_owner.php` في نافذة جديدة
- رسالة توضيحية: "بعد الإضافة عد لهذه الصفحة وحدّثها"

---

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

**الرابط:**
```
GET change_property_entity.php?property_id=123
```

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

**الكيانات القانونية المدعومة:**

| # | النوع | الجدول | الحقل في properties |
|---|-------|--------|---------------------|
| 1 | وصي/ولي قضائي | `legal_entity_judicial_guardian` | `judicial_guardian_id` |
| 2 | مكتب عقاري | `legal_entity_office_owner` | `office_owner_id` |
| 3 | مالك مؤسسة | `legal_entity_establishment_owner` | `establishment_owner_id` |
| 4 | مصفي شركة | `legal_entity_company_liquidator` | `company_liquidator_id` |
| 5 | ممثل شركة | `legal_entity_company_representative` | `company_representative_id` |
| 6 | مشرف وقف | `legal_entity_waqf_supervisor` | `waqf_supervisor_id` |
| 7 | وكيل (وكالة) | `legal_entity_agency_agent` | `agency_agent_id` |
| 8 | ولي قاصر | `legal_entity_minor_guardian` | `minor_guardian_id` |

**مثال: اختيار "مكتب عقاري"**
```
الحقول التي تظهر:
┌─────────────────────────────────────────┐
│ 💼 بيانات المكتب العقاري               │
├─────────────────────────────────────────┤
│ 🆔 رقم الرخصة: [تملأ تلقائياً]        │
│ 🏢 اسم المكتب: [تملأ تلقائياً]        │
│ 🏛️ صادر من: [_____________]            │
└─────────────────────────────────────────┘
```

**خيار إزالة الكيان:**
```
اختيار: "🗑️ إزالة الصفة القانونية"
   ↓
رسالة تحذير:
┌─────────────────────────────────────────┐
│ ⚠️ تأكيد إزالة الصفة القانونية         │
├─────────────────────────────────────────┤
│ سيتم إزالة الصفة القانونية من هذا     │
│ العقار. المالك سيكون أصالة عن نفسه.   │
└─────────────────────────────────────────┘
```

---

### 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": "وزارة التجارة"
  }
}
```

**الخطوات:**
```sql
BEGIN TRANSACTION;

-- 1. إزالة جميع الكيانات القديمة
UPDATE properties SET 
  judicial_guardian_id = NULL,
  office_owner_id = NULL,
  establishment_owner_id = NULL,
  company_liquidator_id = NULL,
  company_representative_id = NULL,
  waqf_supervisor_id = NULL,
  agency_agent_id = NULL,
  minor_guardian_id = NULL
WHERE id = property_id;

-- 2. إدراج الكيان الجديد
INSERT INTO legal_entity_office_owner (license_number, office_name, issued_from) 
VALUES ('123456', 'مكتب النور العقاري', 'وزارة التجارة');

-- 3. الحصول على ID
SET @entity_id = LAST_INSERT_ID();

-- 4. تحديث العقار
UPDATE properties SET office_owner_id = @entity_id WHERE id = property_id;

COMMIT;
```

#### **ب) إزالة كيان:**
```json
{
  "property_id": 123,
  "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
}
```

---

## 🔄 **الملفات المحدثة**

### **التحديثات على الملفات الموجودة:**

| الملف | التغيير | السطر |
|-------|---------|-------|
| `view_properties.php` | تحديث زر التعديل (2 مكان) | 462, 672 |
| `result_property.php` | تحديث زر التعديل | 565 |
| `view_property.php` | تحديث زر التعديل | 479 |

**التغيير:**
```javascript
// قبل:
edit_property_simple.php?property_id=${property.id}

// بعد:
prepare_edit_property.php?property_id=${property.id}
```

---

## 📊 **السيناريوهات المدعومة (4 سيناريوهات)**

### **السيناريو 1: تعديل العقار فقط** ⚡
```
view_properties.php
   [تعديل] →
prepare_edit_property.php
   السؤال 1: تغيير المالك؟ → [لا]
   السؤال 2: تغيير الكيان؟ → [لا]
   [تعديل بيانات العقار] →
edit_property_simple.php
```

---

### **السيناريو 2: تغيير المالك فقط** 👤
```
view_properties.php
   [تعديل] →
prepare_edit_property.php
   السؤال 1: تغيير المالك؟ → [نعم] →
   
change_property_owner.php
   🔍 البحث
   [+ إضافة مؤجر جديد]
   اختيار مؤجر
   [حفظ وتغيير المالك] →
   UPDATE properties.woner_id
   
prepare_edit_property.php (العودة)
   السؤال 2: تغيير الكيان؟ → [لا]
   [تعديل بيانات العقار] →
   
edit_property_simple.php
```

---

### **السيناريو 3: تغيير/إضافة الكيان فقط** 💼
```
view_properties.php
   [تعديل] →
prepare_edit_property.php
   السؤال 1: تغيير المالك؟ → [لا]
   السؤال 2: تغيير الكيان؟ → [نعم] →
   
change_property_entity.php
   اختيار نوع الكيان (8 أنواع)
   إدخال البيانات
   [حفظ والمتابعة] →
   API: update_property_entity_api.php
   INSERT INTO legal_entity_* + UPDATE properties
   
prepare_edit_property.php (العودة)
   [تعديل بيانات العقار] →
   
edit_property_simple.php
```

---

### **السيناريو 4: تغيير كليهما** 🔄
```
view_properties.php
   [تعديل] →
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

-- العنوان
main_title VARCHAR(250)
```

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

### **جدول `users`**
```sql
usercode INT(11) PRIMARY KEY
name VARCHAR
mobile VARCHAR
email VARCHAR
identity VARCHAR
user_type ENUM('مؤجر', 'مكتب عقاري', ...)
```

---

## 🎨 **التصميم الموحد**

جميع الصفحات تتبع نفس الهوية البصرية:

### **الألوان:**
- **الأخضر الداكن:** `#206843` (الأساسي)
- **الأخضر:** `#28a745` (نجاح)
- **الأصفر:** `#ffc107` (تحذير/معلومات)
- **الرمادي:** `#6c757d` (ثانوي)
- **الأحمر:** `#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. ✅ `SESSION_USER_ID` موجود؟
2. ✅ `user_type === 'مكتب عقاري'`؟
3. ✅ `office_id` موجود في SESSION؟
4. ✅ `property_id` صحيح؟
5. ✅ العقار ينتمي للمكتب؟ `WHERE id = ? AND office_id = ?`

### **منع التسريب:**
```sql
-- ✅ كل استعلام يتحقق من office_id
WHERE p.id = ? AND p.office_id = ?

-- ✅ المالكون المعروضون فقط التابعين للمكتب
WHERE w.office_id = :office_id
```

---

## 🧪 **الاختبار**

### **حالات الاختبار:**

#### **1. عقار بمؤجر محدد:**
```sql
woner_id = 45 (موجود)
woner.owner_id = 123
users.usercode = 123
users.name = "أحمد محمد"
```
**النتيجة المتوقعة:** ✅ يظهر "أحمد محمد" مع بياناته

---

#### **2. عقار بدون مؤجر:**
```sql
woner_id = NULL
```
**النتيجة المتوقعة:** ✅ يظهر "المكتب العقاري - هذا العقار غير مربوط بمؤجر محدد"

---

#### **3. عقار بكيان قانوني:**
```sql
office_owner_id = 78 (موجود)
بقية الكيانات = NULL
```
**النتيجة المتوقعة:** ✅ السؤال 2 يظهر "تغيير" مع عرض الصفة الحالية

---

#### **4. عقار بدون كيان:**
```sql
جميع حقول الكيانات = NULL
```
**النتيجة المتوقعة:** ✅ السؤال 2 يظهر "إضافة" مع رسالة توضيحية

---

## 💡 **نصائح الاستخدام**

### **للمستخدم:**
1. ✅ يمكنك تخطي تغيير المالك والكيان بالضغط على "لا"
2. ✅ يمكنك إضافة مؤجر جديد من نفس الصفحة
3. ✅ التغييرات تُحفظ فوراً عند الضغط على "حفظ"
4. ✅ يمكنك العودة في أي وقت بزر "رجوع"

### **للمطور:**
1. ✅ جميع التحديثات تستخدم Prepared Statements (آمنة)
2. ✅ التحقق من `office_id` في كل استعلام (عزل البيانات)
3. ✅ استخدام Transactions في تحديث الكيانات
4. ✅ تسجيل الأخطاء في `error_log()`

---

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

### **المشكلة الحالية: "المالك الحالي: غير محدد"**

**السبب المحتمل:**
```
العقار رقم 10 قد يكون:
1. woner_id = NULL (لا يوجد مؤجر مسجل)
2. woner_id موجود لكن woner.owner_id لا يطابق أي users.usercode
```

**الحل المطبق:**
```php
// إذا لم يكن هناك مؤجر، استخدم اسم المكتب
if (empty($property['owner_name'])) {
    $property['owner_name'] = 'المكتب العقاري';
    // ... بقية الحقول NULL
}
```

**الآن سيظهر:**
```
المالك الحالي:
┌─────────────────────────────────────────┐
│ 🏢 المكتب العقاري                      │
│ ℹ️ هذا العقار غير مربوط بمؤجر محدد    │
└─────────────────────────────────────────┘
```

---

## 🚀 **جاهز للاستخدام!**

### **للاختبار:**

1. **افتح:**
   ```
   https://localhost/0f/users/office/property/view_properties.php
   ```

2. **اضغط زر "تعديل" على أي عقار**

3. **ستفتح صفحة الفحص:**
   ```
   prepare_edit_property.php?property_id=10
   ```

4. **أجب على الأسئلة حسب حاجتك**

5. **في النهاية اضغط "تعديل بيانات العقار"**

---

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

### **إذا ظهر "غير محدد":**
- هذا يعني أن العقار ليس له مؤجر مسجل في قاعدة البيانات
- الآن سيظهر "المكتب العقاري" بدلاً من "غير محدد" ✅
- يمكنك ربط المالك بالضغط على "نعم، أريد تغيير المالك"

### **لتحديث الصفحة:**
- اضغط `Ctrl + Shift + R` لتحديث قوي
- أو `Ctrl + F5`

---

**🎉 النظام جاهز وكامل!**

**تاريخ الإكمال:** 2025-11-02  
**الإصدار:** 2.0 - نظام الأسئلة الذكي

