# تحليل شامل: الوساطة العقارية (Brokerage Contracts)

## 📋 نظرة عامة

الوساطة العقارية هي **عقد بين المكتب العقاري (الوسيط) والمالك** لتسهيل عملية بيع أو إيجار العقار مقابل عمولة. جدول `brokerage_contracts` يوثق هذه العلاقة التجارية.

**الهدف:** تسجيل وتتبع عقود الوساطة بين المكاتب العقارية والملاك، مع حساب العمولات ورسوم الإدارة.

---

## 🏢 جدول `brokerage_contracts` - الهيكل الكامل

### الحقول الأساسية:

```sql
CREATE TABLE `brokerage_contracts` (
  `id` int(11) NOT NULL COMMENT 'الرقم التسلسلي لعقد الوساطة',
  `contract_number` varchar(50) NOT NULL COMMENT 'رقم العقد الفريد',
  `owner_usercode` int(11) NOT NULL COMMENT 'usercode المالك من جدول المستخدمين',
  `client_usercode` int(11) NOT NULL COMMENT 'usercode العميل (المستأجر أو المشتري)',
  `property_id` int(11) DEFAULT NULL COMMENT 'رقم العقار المرتبط بالعقد (properties.id)',
  `contract_id` int(11) DEFAULT NULL COMMENT 'رقم العقد الفعلي إن وجد (contracts.id)',
  `contract_type` enum('sale','rental','management','other') NOT NULL COMMENT 'نوع الوساطة',
  `commission_type` enum('fixed','percentage','mixed') NOT NULL COMMENT 'نوع العمولة',
  `commission_value` decimal(12,2) NOT NULL DEFAULT 0.00 COMMENT 'قيمة العمولة أو النسبة',
  `commission_currency` varchar(3) NOT NULL DEFAULT 'SAR' COMMENT 'عملة العمولة',
  `start_date` date NOT NULL COMMENT 'تاريخ بداية العقد',
  `end_date` date DEFAULT NULL COMMENT 'تاريخ نهاية العقد',
  `management_fee` decimal(12,2) DEFAULT 0.00 COMMENT 'رسوم إدارة العقار',
  `management_fee_cycle` enum('monthly','quarterly','yearly','once') DEFAULT NULL COMMENT 'دورية رسوم الإدارة',
  `documentation_status` enum('not_documented','documented','pending') NOT NULL DEFAULT 'not_documented',
  `documentation_platform` enum('ejari','wosata','other') DEFAULT NULL COMMENT 'المنصة المستخدمة للتوثيق',
  `notes` text DEFAULT NULL COMMENT 'ملاحظات إضافية',
  `status` enum('active','expired','cancelled','rejected','completed') NOT NULL DEFAULT 'active',
  `created_at` timestamp NOT NULL DEFAULT current_timestamp(),
  `updated_at` timestamp NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),
  `office_id` int(11) DEFAULT NULL COMMENT 'office.id المكتب الوسيط'
)
```

---

## 🔗 العلاقات (Foreign Keys)

### 1. العلاقة مع المالك (`owner_usercode`):
```sql
brokerage_contracts.owner_usercode → users.usercode
```
- **الوصف:** يربط عقد الوساطة بالمالك
- **نوع العلاقة:** CASCADE (عند حذف المالك، يتم حذف عقود الوساطة)

### 2. العلاقة مع العميل (`client_usercode`):
```sql
brokerage_contracts.client_usercode → users.usercode
```
- **الوصف:** يربط عقد الوساطة بالعميل (المستأجر أو المشتري)
- **نوع العلاقة:** CASCADE

### 3. العلاقة مع العقار (`property_id`):
```sql
brokerage_contracts.property_id → properties.id
```
- **الوصف:** يربط عقد الوساطة بالعقار
- **نوع العلاقة:** SET NULL (عند حذف العقار، يتم تعيين القيمة إلى NULL)

### 4. العلاقة مع العقد الفعلي (`contract_id`):
```sql
brokerage_contracts.contract_id → contracts.id
```
- **الوصف:** يربط عقد الوساطة بالعقد الفعلي (عقد الإيجار أو البيع)
- **نوع العلاقة:** SET NULL (عند حذف العقد، يتم تعيين القيمة إلى NULL)

### 5. العلاقة مع المكتب العقاري (`office_id`):
```sql
brokerage_contracts.office_id → office.id
```
- **الوصف:** يربط عقد الوساطة بالمكتب الوسيط
- **نوع العلاقة:** SET NULL (عند حذف المكتب، يتم تعيين القيمة إلى NULL)

---

## 📊 أنواع العقود (Contract Types)

### 1. **`sale`** - بيع:
- **الوصف:** وساطة لبيع العقار
- **العمولة:** تُحسب عادة كنسبة مئوية من سعر البيع
- **مثال:** عمولة 2% من سعر البيع (500,000 ريال × 2% = 10,000 ريال)

### 2. **`rental`** - إيجار:
- **الوصف:** وساطة لإيجار العقار
- **العمولة:** تُحسب عادة كنسبة مئوية من قيمة الإيجار السنوي أو الشهري
- **مثال:** عمولة 7.5% من الإيجار الشهري (10,000 ريال × 7.5% = 750 ريال)

### 3. **`management`** - إدارة:
- **الوصف:** وساطة لإدارة العقار (إدارة مستمرة)
- **العمولة:** رسوم إدارة شهرية أو سنوية
- **مثال:** رسوم إدارة 500 ريال شهرياً

### 4. **`other`** - أخرى:
- **الوصف:** أنواع أخرى من الوساطة
- **العمولة:** حسب الاتفاق

---

## 💰 أنواع العمولات (Commission Types)

### 1. **`fixed`** - ثابتة:
- **الوصف:** عمولة مبلغ ثابت
- **مثال:** `commission_value = 5000` ريال
- **الاستخدام:** عمولة ثابتة بغض النظر عن قيمة الصفقة

### 2. **`percentage`** - نسبة مئوية:
- **الوصف:** عمولة كنسبة مئوية من قيمة الصفقة
- **مثال:** `commission_value = 7.50` (يعني 7.5%)
- **الاستخدام:** عمولة نسبية حسب قيمة الصفقة
- **حساب العمولة:**
  ```php
  $commission = ($contract_value * $commission_value) / 100;
  ```

### 3. **`mixed`** - مزيج:
- **الوصف:** عمولة ثابتة + نسبة مئوية
- **مثال:** 1000 ريال ثابت + 5% من قيمة الصفقة
- **الاستخدام:** عمولة مركبة

---

## 📅 رسوم الإدارة (Management Fees)

### دورية الرسوم (`management_fee_cycle`):

1. **`monthly`** - شهري:
   - تُحسب كل شهر
   - مثال: 500 ريال/شهر

2. **`quarterly`** - ربع سنوي:
   - تُحسب كل 3 أشهر
   - مثال: 1,500 ريال/ربع سنة

3. **`yearly`** - سنوي:
   - تُحسب مرة واحدة في السنة
   - مثال: 6,000 ريال/سنة

4. **`once`** - مرة واحدة:
   - تُحسب مرة واحدة فقط
   - مثال: 2,000 ريال

---

## 📝 حالة التوثيق (Documentation Status)

### 1. **`not_documented`** - غير موثق:
- **الوصف:** العقد لم يتم توثيقه إلكترونياً بعد
- **الحالة الافتراضية:** نعم

### 2. **`documented`** - موثق:
- **الوصف:** تم توثيق العقد إلكترونياً
- **المنصات:** إيجار (Ejari)، وساطة (Wosata)، أخرى

### 3. **`pending`** - قيد التوثيق:
- **الوصف:** العقد قيد عملية التوثيق
- **الحالة:** في الانتظار

### المنصات (`documentation_platform`):
- **`ejari`** - منصة إيجار (المنصة الرسمية لتوثيق عقود الإيجار)
- **`wosata`** - منصة وساطة (منصة توثيق الوساطة العقارية)
- **`other`** - منصات أخرى

---

## 🔄 حالات العقد (Status)

### 1. **`active`** - نشط:
- **الوصف:** العقد ساري المفعول
- **الحالة الافتراضية:** نعم
- **الاستخدام:** العقد قيد التنفيذ

### 2. **`expired`** - منتهي:
- **الوصف:** انتهت صلاحية العقد
- **السبب:** `end_date` قد مر
- **الاستخدام:** العقد انتهى تلقائياً

### 3. **`cancelled`** - ملغي:
- **الوصف:** تم إلغاء العقد
- **السبب:** إلغاء من أحد الأطراف
- **الاستخدام:** العقد أُلغي قبل الإتمام

### 4. **`rejected`** - مرفوض:
- **الوصف:** تم رفض العقد
- **السبب:** رفض من المالك أو العميل
- **الاستخدام:** العقد لم يُقبل

### 5. **`completed`** - مكتمل:
- **الوصف:** تم إتمام العقد بنجاح
- **السبب:** اكتملت الصفقة
- **الاستخدام:** العقد اكتمل وتم دفع العمولة

---

## 🔗 العلاقات الكاملة في النظام

### سلسلة العلاقات:

```
office (id)
  ↓
brokerage_contracts (office_id)
  ├── owner_usercode → users (usercode) → woner (owner_id)
  ├── client_usercode → users (usercode) → tenant (usercode)
  ├── property_id → properties (id)
  └── contract_id → contracts (id)
      └── contracts.office_id → office (id)
```

### مثال عملي:

```
المكتب العقاري (office_id = 7)
  ↓
عقد وساطة (brokerage_contracts.id = 1)
  ├── المالك (owner_usercode = 6) → users.usercode = 6
  ├── العميل (client_usercode = 7) → users.usercode = 7
  ├── العقار (property_id = 1) → properties.id = 1
  └── العقد الفعلي (contract_id = 30) → contracts.id = 30
```

---

## 🎯 دور الجدول في النظام

### 1. **تسجيل عقود الوساطة:**
- توثيق العلاقة بين المكتب والمالك
- تسجيل شروط الوساطة (نوع العمولة، القيمة)
- تحديد مدة العقد (start_date, end_date)

### 2. **حساب العمولات:**
- تتبع العمولات المستحقة للمكتب
- حساب العمولات حسب النوع (ثابتة، نسبة، مزيج)
- ربط العمولات بالعقود الفعلية

### 3. **إدارة رسوم الإدارة:**
- تسجيل رسوم الإدارة الشهرية/السنوية
- تتبع دورية الرسوم
- حساب الإيرادات من الإدارة

### 4. **تتبع حالة التوثيق:**
- متابعة حالة توثيق العقود إلكترونياً
- ربط العقود بمنصات التوثيق (إيجار، وساطة)
- ضمان الامتثال القانوني

### 5. **إدارة دورة حياة العقد:**
- تتبع حالة العقد (نشط، منتهي، ملغي...)
- إدارة تواريخ البدء والانتهاء
- تسجيل ملاحظات إضافية

---

## 📋 الجداول المرتبطة

### 1. **`brokerage_contract_service_tags`** - علامات الخدمات:
```sql
CREATE TABLE `brokerage_contract_service_tags` (
  `id` int(11) NOT NULL,
  `brokerage_contract_id` int(11) NOT NULL,
  `service_tag_id` int(11) NOT NULL,
  `created_at` timestamp NOT NULL DEFAULT current_timestamp()
)
```

**العلاقة:**
- `brokerage_contract_id` → `brokerage_contracts.id` (CASCADE)
- `service_tag_id` → `office_service_tags.id` (CASCADE)

**الهدف:** ربط عقد الوساطة بخدمات محددة (مثل: صيانة، تنظيف، إدارة)

---

## 🔄 دورة العمل (Workflow)

### 1. إنشاء عقد وساطة:
```
1. المالك يطلب وساطة من المكتب
   ↓
2. المكتب ينشئ عقد وساطة (brokerage_contracts)
   ↓
3. تحديد نوع الوساطة (بيع، إيجار، إدارة)
   ↓
4. تحديد نوع العمولة (ثابتة، نسبة، مزيج)
   ↓
5. تحديد قيمة العمولة
   ↓
6. تحديد مدة العقد (start_date, end_date)
   ↓
7. حفظ العقد (status = 'active')
```

### 2. تنفيذ الوساطة:
```
1. المكتب يبحث عن عميل (مستأجر أو مشتري)
   ↓
2. إيجاد عميل مناسب
   ↓
3. إنشاء عقد فعلي (contracts)
   ↓
4. ربط عقد الوساطة بالعقد الفعلي (contract_id)
   ↓
5. ربط العميل (client_usercode)
   ↓
6. ربط العقار (property_id)
```

### 3. حساب العمولة:
```
1. تحديد قيمة الصفقة من العقد الفعلي
   ↓
2. حساب العمولة حسب النوع:
   - fixed: commission_value
   - percentage: (contract_value × commission_value) / 100
   - mixed: fixed + percentage
   ↓
3. تسجيل العمولة في السندات المالية
   ↓
4. تحديث حالة العقد (status = 'completed')
```

### 4. إدارة رسوم الإدارة:
```
1. تحديد رسوم الإدارة (management_fee)
   ↓
2. تحديد دورية الرسوم (monthly, quarterly, yearly, once)
   ↓
3. إنشاء سندات قبض دورية
   ↓
4. تتبع المدفوعات
```

### 5. توثيق العقد:
```
1. إتمام الصفقة
   ↓
2. توثيق العقد في المنصة (ejari, wosata)
   ↓
3. تحديث documentation_status = 'documented'
   ↓
4. تحديث documentation_platform
```

---

## 💡 أمثلة عملية

### مثال 1: عقد وساطة إيجار

```sql
INSERT INTO brokerage_contracts (
  contract_number, owner_usercode, client_usercode, property_id, contract_id,
  contract_type, commission_type, commission_value, commission_currency,
  start_date, end_date, office_id, status
) VALUES (
  'BC-2025-001',
  6,                    -- المالك
  7,                    -- المستأجر
  1,                    -- العقار
  30,                   -- العقد الفعلي
  'rental',             -- نوع الوساطة: إيجار
  'percentage',         -- نوع العمولة: نسبة
  7.50,                 -- قيمة العمولة: 7.5%
  'SAR',                -- العملة: ريال سعودي
  '2025-07-16',         -- تاريخ البدء
  '2025-08-12',         -- تاريخ الانتهاء
  7,                    -- المكتب الوسيط
  'active'              -- الحالة: نشط
);
```

**حساب العمولة:**
- قيمة الإيجار الشهري: 10,000 ريال
- العمولة: 10,000 × 7.5% = 750 ريال/شهر
- العمولة السنوية: 750 × 12 = 9,000 ريال

### مثال 2: عقد وساطة بيع

```sql
INSERT INTO brokerage_contracts (
  contract_number, owner_usercode, client_usercode, property_id,
  contract_type, commission_type, commission_value, commission_currency,
  start_date, end_date, office_id, status
) VALUES (
  'BC-2025-002',
  6,                    -- المالك
  8,                    -- المشتري
  2,                    -- العقار
  NULL,                 -- لا يوجد عقد إيجار (بيع مباشر)
  'sale',               -- نوع الوساطة: بيع
  'percentage',         -- نوع العمولة: نسبة
  2.00,                 -- قيمة العمولة: 2%
  'SAR',                -- العملة: ريال سعودي
  '2025-01-01',         -- تاريخ البدء
  '2025-12-31',         -- تاريخ الانتهاء
  7,                    -- المكتب الوسيط
  'active'              -- الحالة: نشط
);
```

**حساب العمولة:**
- سعر البيع: 500,000 ريال
- العمولة: 500,000 × 2% = 10,000 ريال

### مثال 3: عقد إدارة مع رسوم شهرية

```sql
INSERT INTO brokerage_contracts (
  contract_number, owner_usercode, property_id,
  contract_type, commission_type, commission_value,
  management_fee, management_fee_cycle,
  start_date, end_date, office_id, status
) VALUES (
  'BC-2025-003',
  6,                    -- المالك
  3,                    -- العقار
  'management',         -- نوع الوساطة: إدارة
  'fixed',             -- نوع العمولة: ثابتة
  0.00,                 -- لا توجد عمولة (فقط رسوم إدارة)
  500.00,               -- رسوم الإدارة: 500 ريال
  'monthly',            -- دورية الرسوم: شهري
  '2025-01-01',         -- تاريخ البدء
  '2025-12-31',         -- تاريخ الانتهاء
  7,                    -- المكتب الوسيط
  'active'              -- الحالة: نشط
);
```

**حساب الإيرادات:**
- رسوم الإدارة الشهرية: 500 ريال
- الإيرادات السنوية: 500 × 12 = 6,000 ريال

---

## 🔐 قواعد الأمان والصلاحيات

### 1. التحقق من ملكية المكتب:
```php
// التحقق من أن المكتب مرتبط بعقد الوساطة
SELECT * FROM brokerage_contracts 
WHERE id = :brokerage_id 
  AND office_id = :office_id;
```

### 2. التحقق من ملكية المالك:
```php
// التحقق من أن المالك مرتبط بعقد الوساطة
SELECT * FROM brokerage_contracts 
WHERE id = :brokerage_id 
  AND owner_usercode = :owner_usercode;
```

### 3. التحقق من العلاقة مع العقار:
```php
// التحقق من أن العقار مرتبط بالمكتب
SELECT * FROM brokerage_contracts bc
JOIN properties p ON bc.property_id = p.id
WHERE bc.id = :brokerage_id 
  AND p.office_id = :office_id;
```

---

## 📈 الإحصائيات المتوقعة

### لمكتب واحد (متوسط):
- **عقود الوساطة النشطة:** 50 عقد
- **عقود الإيجار:** 40 عقد (80%)
- **عقود البيع:** 5 عقود (10%)
- **عقود الإدارة:** 5 عقود (10%)
- **العمولات الشهرية:** 50,000 ريال
- **رسوم الإدارة الشهرية:** 10,000 ريال

### لـ 100 مكتب:
- **عقود الوساطة النشطة:** 5,000 عقد
- **عقود الإيجار:** 4,000 عقد
- **عقود البيع:** 500 عقد
- **عقود الإدارة:** 500 عقد
- **العمولات الشهرية:** 5,000,000 ريال
- **رسوم الإدارة الشهرية:** 1,000,000 ريال

---

## 🎯 الخلاصة

### المبادئ الأساسية:
1. ✅ **كل عقد وساطة مرتبط بمكتب** (`office_id`)
2. ✅ **يربط المالك والعميل والعقار** (owner_usercode, client_usercode, property_id)
3. ✅ **يمكن ربطه بعقد فعلي** (`contract_id`)
4. ✅ **يدعم أنواع متعددة** (بيع، إيجار، إدارة)
5. ✅ **يدعم أنواع عمولات متعددة** (ثابتة، نسبة، مزيج)
6. ✅ **يدعم رسوم إدارة دورية** (شهري، ربع سنوي، سنوي)
7. ✅ **يتتبع حالة التوثيق** (موثق، غير موثق، قيد التوثيق)

### العلاقات الرئيسية:
```
brokerage_contracts
  ├── office_id → office (المكتب الوسيط)
  ├── owner_usercode → users (المالك)
  ├── client_usercode → users (العميل)
  ├── property_id → properties (العقار)
  └── contract_id → contracts (العقد الفعلي)
```

### أنواع الوساطة:
1. **بيع** - وساطة لبيع العقار
2. **إيجار** - وساطة لإيجار العقار
3. **إدارة** - إدارة مستمرة للعقار
4. **أخرى** - أنواع أخرى

---

**تاريخ الإنشاء:** 2025-01-25
**آخر تحديث:** 2025-01-25
