# 🏢 نظام سندات الصرف المتكامل - النسخة النهائية

## 🚀 التثبيت السريع

### **1️⃣ إضافة office_id**
```
http://localhost/0f/users/office/receipts/add_office_id_column.php
```

### **2️⃣ إنشاء جداول الكيانات والعملاء**
```
http://localhost/0f/users/office/receipts/install_office_entities.php
```

### **3️⃣ إنشاء جدول البنوك**
```
http://localhost/0f/users/office/receipts/install_bank_table.php
```

### **4️⃣ افتح الصفحة**
```
http://localhost/0f/users/office/receipts/add_sand_new.php
```

---

## 📋 الميزات الكاملة

### **أ) سند صرف للمؤجرين/المستأجرين:**
```
1. [مؤجر ✓] [مستأجر] - تبديل
2. اسم المالك/المستأجر
   └─ 🔍 بحث متقدم (اسم، هوية، جوال)
3. رقم العقد
4. فئة السند (إيجار، صيانة، عمولة...)
5. مبلغ الصرف
6. طريقة الدفع + البنك (تلقائي)
7. البيان
8. [حفظ]

النتيجة:
✓ بيانات المالك/المستأجر
✓ بيانات العقد والعقار
✓ جدول الدفعات السابقة
✓ ملخص العقد (إجمالي، مدفوع، متبقي)
```

---

### **ب) سند صرف عام:**
```
1. اسم الكيان [Select ▼]
   └─ ⚙️ إدارة الكيانات
       ├─ 🔍 بحث (اسم، رقم، جوال، نوع)
       ├─ + إضافة كيان جديد
       │   └─ + إضافة عملاء
       ├─ ✏️ تعديل
       └─ 🗑️ حذف
2. اسم العميل [Select ▼] (من عملاء الكيان)
3. فئة السند (11 خيار)
4. مبلغ الصرف
5. طريقة الدفع + البنك
6. البيان
7. [حفظ]
```

---

## 🗄️ الجداول

### **1. receipts_voucher - جدول موحد للسندات**
```sql
- للمؤجرين: to_party_type='owner', contract_id=10
- للمستأجرين: to_party_type='tenant', contract_id=10
- للسندات العامة: to_party_type='office', contract_id=NULL
```

### **2. office_entities - الكيانات الخاصة بالمكتب**
```sql
- office_id: رقم المكتب (للعزل)
- entity_type: company|establishment|individual...
- entity_name: اسم الكيان
- bank_name + account_number
```

### **3. entity_clients - عملاء كل كيان**
```sql
- entity_id: رقم الكيان
- client_name: اسم العميل
- client_id_number: رقم الهوية
- mobile: رقم الجوال
```

---

## 🎯 فئات السندات (11 فئة)

| # | الفئة | الاستخدام |
|---|-------|-----------|
| 1 | إيجار | دفعات إيجار |
| 2 | عمولة | عمولات وساطة |
| 3 | صيانة | صيانة عامة |
| 4 | تأمين | مبالغ مستردة |
| 5 | خدمات | كهرباء/ماء/غاز |
| 6 | تأمين | بوالص تأمين |
| 7 | رسوم قانونية | محامين |
| 8 | تجديدات | أعمال تجديد |
| 9 | نظافة | خدمات نظافة |
| 10 | أمن وحراسة | أمن المباني |
| 11 | أخرى | متنوعة |

---

## 🏢 أنواع الكيانات (5 أنواع)

| # | النوع | مثال |
|---|-------|------|
| 1 | شركة | شركة ABC للصيانة |
| 2 | مؤسسة | مؤسسة XYZ للنظافة |
| 3 | فرد | محمد السعيد (وسيط) |
| 4 | جهة حكومية | بلدية الرياض |
| 5 | أخرى | نوع مخصص |

---

## 💡 سيناريوهات الاستخدام

### **سيناريو 1: إضافة كيان جديد مع عملائه**
```
1. Tab: سند صرف عام
2. اسم الكيان: [⚙️ إدارة الكيانات]
3. [+ إضافة كيان جديد]
4. املأ بيانات الكيان:
   - نوع: شركة
   - اسم: شركة ABC للصيانة
   - رقم السجل: 1234567890
   - جوال: 0501234567
   - بنك: الراجحي
   - حساب: SA123...
5. قسم العملاء:
   [+ إضافة عميل]
   - عميل 1: محمد علي - 9876543210 - 0509876543
   - عميل 2: أحمد سعد - 5555555555 - 0505555555
6. [حفظ الكيان + 2 عميل]
7. الكيان محفوظ الآن ✓
```

---

### **سيناريو 2: استخدام كيان محفوظ**
```
1. Tab: سند صرف عام
2. اسم الكيان: [شركة ABC للصيانة ▼]
   → يتم جلب عملاء الشركة تلقائياً
3. اسم العميل: [محمد علي ▼]
4. فئة السند: صيانة
5. مبلغ: 5,000
6. طريقة: تحويل بنكي
7. البنك: الراجحي (معبأ تلقائياً من بيانات الكيان)
8. الحساب: SA123... (معبأ تلقائياً)
9. البيان: صيانة مكيفات
10. [حفظ] ✓
```

---

### **سيناريو 3: البحث عن كيان**
```
1. اسم الكيان: [⚙️ إدارة الكيانات]
2. Modal يفتح
3. 🔍 البحث: "صيانة"
   → النتائج:
     • شركة ABC للصيانة
     • مؤسسة صيانة المباني
     • محمد (فرد - صيانة)
4. [✓ اختر] شركة ABC
5. Modal يُغلق
6. البيانات تُملأ تلقائياً
7. اختر العميل
8. أكمل السند
```

---

## 📊 واجهة إدارة الكيانات

```
┌────────────────────────────────────────────────────┐
│ 🏢 إدارة الكيانات                                 │
├────────────────────────────────────────────────────┤
│ [🔍 ابحث...              ] [+ إضافة كيان جديد]   │
│                                                     │
│ ┌────┬────────────┬──────┬──────┬────────┬───────┐│
│ │نوع │ الكيان     │ رقم  │ جوال │ بنك    │اختر  ││
│ │[فلتر]│           │ سجل  │      │ حساب   │      ││
│ ├────┼────────────┼──────┼──────┼────────┼───────┤│
│ │شركة│ ABC صيانة  │ 123  │ 0501 │الراجحي │✓✏️🗑 ││
│ │    │ (محمد)     │      │      │SA123.. │      ││
│ ├────┼────────────┼──────┼──────┼────────┼───────┤│
│ │مؤسسة│XYZ نظافة  │ 456  │ 0509 │الرياض  │✓✏️🗑 ││
│ └────┴────────────┴──────┴──────┴────────┴───────┘│
│                                                     │
│ الإجمالي: 2 كيان | عرض [10▼] 20 50               │
│                                                     │
│ 💡 نقر مزدوج على الصف للاختيار السريع            │
└────────────────────────────────────────────────────┘
```

---

## 📝 واجهة إضافة كيان + عملاء

```
┌──────────────────────────────────────────┐
│ إضافة كيان جديد                         │
├──────────────────────────────────────────┤
│ نوع الكيان *      اسم الكيان *         │
│ [شركة ▼]          [شركة ABC]            │
│                                           │
│ رقم السجل         رقم الجوال            │
│ [1234567890]      [0501234567]           │
│                                           │
│ اسم البنك         رقم الحساب            │
│ [الراجحي ▼]      [SA123...]             │
│                                           │
│ ملاحظات                                  │
│ [...                                ...] │
│                                           │
│ ┌─────────────────────────────────────┐ │
│ │ 👥 عملاء الكيان   [+ إضافة عميل] │ │
│ ├─────────────────────────────────────┤ │
│ │ عميل 1                          [✗]│ │
│ │ [محمد علي] [987654] [0509876543]  │ │
│ │                                     │ │
│ │ عميل 2                          [✗]│ │
│ │ [أحمد سعد] [555555] [0505555555]  │ │
│ └─────────────────────────────────────┘ │
│                                           │
│ [حفظ الكيان + 2 عميل] [إلغاء]          │
└──────────────────────────────────────────┘
```

---

## 🔄 التدفق الكامل

### **إضافة كيان جديد:**
```
إدارة الكيانات → + إضافة كيان جديد
  ↓
ملء بيانات الكيان
  ↓
+ إضافة عميل (اختياري)
  ↓
إضافة عميل آخر (اختياري)
  ↓
[حفظ الكيان + العملاء]
  ↓
✓ تم الحفظ في:
  - office_entities (الكيان)
  - entity_clients (العملاء)
```

---

### **إصدار سند عام:**
```
اختر الكيان
  ↓ يتم جلب عملاء الكيان تلقائياً
اختر العميل
  ↓
اختر فئة السند
  ↓
املأ البيانات
  ↓
[حفظ]
  ↓
✓ تم الحفظ في receipts_voucher
```

---

## 🔒 الأمان

### **عزل البيانات:**
```sql
-- كل مكتب يرى كياناته فقط
WHERE office_id = ?

-- كل كيان يرى عملاءه فقط  
WHERE entity_id = ?
```

**النتيجة:**
- ✅ المكتب A لا يرى كيانات المكتب B
- ✅ الكيان 1 لا يرى عملاء الكيان 2

---

## 📊 البنية

```
office (المكتب)
  ↓
office_entities (الكيانات)
  ├── شركة ABC
  │   ├── entity_clients (العملاء)
  │   │   ├── محمد علي
  │   │   └── أحمد سعد
  │   └── receipts_voucher (سندات)
  │
  ├── مؤسسة XYZ
  │   ├── entity_clients
  │   │   └── سعد خالد
  │   └── receipts_voucher
  │
  └── محمد (فرد)
      ├── entity_clients
      │   └── (بدون عملاء)
      └── receipts_voucher
```

---

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

### **مثال 1: شركة صيانة بعملائها**
```
الكيان:
- نوع: شركة
- اسم: شركة الخليج للصيانة
- سجل: 1010101010
- جوال: 0501234567
- بنك: الراجحي
- حساب: SA1234567890123456789012

العملاء:
- محمد علي (مدير المشاريع)
- أحمد سعد (فني صيانة)
- علي حسن (محاسب)

الاستخدام:
- إصدار سند صيانة لمحمد علي
- إصدار سند صيانة لأحمد سعد
```

---

### **مثال 2: وسيط عقاري فردي**
```
الكيان:
- نوع: فرد
- اسم: محمد السعيد
- هوية: 1122334455
- جوال: 0509876543

العملاء:
- (بدون عملاء - يعمل لحسابه)

الاستخدام:
- إصدار سند عمولة لمحمد السعيد
```

---

## 🔍 البحث

### **في الملاك/المستأجرين:**
```
🔍 بحث متقدم
├─ اسم
├─ رقم الهوية
└─ رقم الجوال
```

### **في الكيانات:**
```
⚙️ إدارة الكيانات
🔍 ابحث...
├─ اسم الكيان
├─ رقم السجل/الهوية
├─ رقم الجوال
├─ نوع الكيان
└─ النوع المخصص
```

---

## ✅ قائمة التحقق الكاملة

### **التثبيت:**
- [ ] عمود office_id في receipts_voucher
- [ ] جدول office_entities
- [ ] جدول entity_clients
- [ ] جدول bank

### **الوظائف - الملاك:**
- [ ] تبديل مؤجر/مستأجر
- [ ] بحث متقدم
- [ ] جلب العقود
- [ ] اختيار فئة السند
- [ ] جدول الدفعات السابقة
- [ ] ملخص العقد

### **الوظائف - السند العام:**
- [ ] اختيار الكيان (Select)
- [ ] اختيار العميل (Select)
- [ ] إدارة الكيانات (Modal)
- [ ] بحث في الكيانات
- [ ] إضافة كيان + عملاء
- [ ] تعديل كيان + عملاء
- [ ] حذف كيان
- [ ] اختيار فئة السند

---

## 📁 الملفات

### **الصفحة الرئيسية:**
```
add_sand_new.php (2200+ سطر)
```

### **APIs:**
```
get_office_parties.php       - الملاك/المستأجرين
get_party_contracts.php      - عقود الشخص
get_contract_details.php     - تفاصيل العقد + الدفعات
save_disbursement_voucher.php - حفظ السند (موحد)
manage_entities.php          - إدارة الكيانات (CRUD)
get_entity_clients.php       - جلب عملاء الكيان
```

### **التثبيت:**
```
add_office_id_column.php
install_office_entities.php
install_bank_table.php
```

### **SQL:**
```
sql/create_office_entities_table.sql
sql/create_entity_clients_table.sql
sql/create_bank_table.sql
sql/add_office_id_to_receipts_voucher.sql
```

---

## 🎉 المميزات الفريدة

### **1. نظام كيانات خاص**
```
✓ كل مكتب يسجل كياناته
✓ لا يرى كيانات الآخرين
✓ إضافة عملاء لكل كيان
```

### **2. بحث ذكي مزدوج**
```
✓ بحث في الملاك/المستأجرين
✓ بحث في الكيانات
✓ بحث في عدة حقول
```

### **3. اختيار سريع**
```
✓ Select منسدلة
✓ نقر على "بحث متقدم"
✓ نقر مزدوج
✓ زر "اختر"
```

---

## 📞 الدعم

راجع:
- `INSTALLATION_GUIDE.md` - دليل التثبيت (3 خطوات)
- التحقق من error_log
- Console المتصفح (F12)

---

## 🎊 جاهز!

**افتح:**
```
http://localhost/0f/users/office/receipts/add_sand_new.php
```

**جرب:**
1. سند صرف عام
2. إدارة الكيانات
3. إضافة كيان + عملاء
4. إصدار سند
5. ✓ نجح!

---

**الإصدار النهائي:** 6.0.0  
**التاريخ:** 2025-10-26  
**الحالة:** جاهز للإنتاج ✓

