# توثيق جداول نظام الصيانة

## نظرة عامة
نظام الصيانة في منصة B العقارية يستخدم عدة جداول مترابطة لإدارة طلبات الصيانة والمناقصات والعروض.

---

## الجداول الرئيسية

### 1. جدول `tenders` (المناقصات العامة)
**الوصف**: جدول عام لحفظ جميع أنواع المناقصات (صيانة، تنظيف، نقل عفش، إلخ)

**الحقول الرئيسية** (من `tenders_save.php`):
- `id` - المعرف الرئيسي
- `user_id` - معرف المستخدم (صاحب الطلب)
- `project_type` - نوع المشروع/عنوان الطلب
- `description` - وصف الطلب (text)
- `budget` - الميزانية المتوقعة (decimal)
- `access_notes` - ملاحظات الوصول (text)
- `region` - المنطقة (varchar)
- `city` - المدينة (varchar)
- `district` - الحي (varchar)
- `map_latitude` - خط العرض (decimal/varchar)
- `map_longitude` - خط الطول (decimal/varchar)
- `is_open` - هل المناقصة مفتوحة (tinyint, default: 1)
- `show_client_info` - إظهار معلومات العميل (tinyint, default: 1)
- `status` - حالة المناقصة (varchar/enum)
  - القيم المحتملة: 'pending', 'open', 'in_progress', 'completed', 'cancelled', 'rejected'
  - أو: 'قيد المناقصة حتى الآن' (القيمة الافتراضية)
- `service_name` - اسم الخدمة (varchar, مثل: 'صيانة')
- `report` - هل يوجد تقرير (tinyint, default: 0)
- `report_description` - وصف التقرير (text, nullable)
- `created_at` - تاريخ الإنشاء (datetime/timestamp)
- `updated_at` - تاريخ التحديث (datetime/timestamp)

**الاستخدام**: 
- يستخدم في `users/user/services/services.php` للإحصائيات
- يستخدم في `users/user/trender/add_request.php` لإنشاء المناقصات
- يتم الحفظ عبر `users/user/api/tenders_save.php`

**العلاقات**:
- مرتبط بـ `tenders_services` (Many-to-Many مع جدول `services`)
- مرتبط بـ `tenders_status` لتتبع تاريخ الحالات

---

### 2. جدول `maintenance_tenders` (مناقصات الصيانة)
**الوصف**: جدول متخصص لمناقصات الصيانة (المرجع من `users/owner/maintenance`)

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `project_type` - نوع المشروع
- `description` - الوصف
- `budget` - الميزانية
- `access_notes` - ملاحظات الوصول
- `region`, `city`, `district` - الموقع
- `map_latitude`, `map_longitude` - الإحداثيات
- `is_open` - حالة الفتح
- `show_client_info` - إظهار معلومات العميل
- `report` - التقرير
- `report_description` - وصف التقرير
- `service_name` - اسم الخدمة
- `property_id` - رقم العقار
- `tenant_id` - رقم المستأجر
- `owner_id` - رقم المالك
- `office_id` - رقم المكتب العقاري
- `service_id` - رقم الخدمة
- `priority` - الأولوية (منخفض، متوسط، عالي، حرج)
- `estimated_cost` - التكلفة التقديرية
- `actual_cost` - التكلفة الفعلية
- `request_date` - تاريخ الطلب
- `completion_date` - تاريخ الإنجاز
- `status` - الحالة (18 حالة مختلفة من 'قيد المناقصة' إلى 'ملغي')

**الحالات المتاحة**:
- قيد المناقصة
- تم استقبال عروض
- تم الإغلاق للعروض
- بانتظار الترسية
- تم ترسية المناقصة
- بانتظار التعاقد
- تم التعاقد
- تم التكليف
- قيد التنفيذ
- تم الإنجاز
- مكتمل
- مغلق
- أغلق بدون تنفيذ
- تم التسوية
- مرفوض من الجهة المنفذة
- مرفوض من صاحب الطلب
- فشل التنفيذ
- ملغي

---

### 3. جدول `maintenance_requests` (طلبات الصيانة)
**الوصف**: جدول لحفظ طلبات الصيانة المباشرة (غير المناقصات)

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `user_id` - معرف المستخدم
- `request_title` - عنوان الطلب
- `request_number` - رقم الطلب
- `property_id` - رقم العقار
- `description` - الوصف
- `region`, `city`, `district` - الموقع
- `status` - الحالة (قيد الانتظار، جارٍ التنفيذ، تم الإنجاز، ملغي)
- `bid_id` - رقم العرض المقبول
- `notes` - ملاحظات
- `contact_time` - وقت التواصل
- `phone` - رقم الهاتف
- `preferred_date` - التاريخ المفضل
- `estimated_cost` - التكلفة التقديرية
- `actual_cost` - التكلفة الفعلية
- `request_date` - تاريخ الطلب
- `completion_date` - تاريخ الإنجاز
- `office_id` - رقم المكتب
- `service_id` - رقم الخدمة
- `request_type` - نوع الطلب (شغل_يد، أغراض_مع_شغل_اليد)
- `map_latitude`, `map_longitude` - الإحداثيات

---

### 4. جدول `maintenance_bids` (عروض الصيانة)
**الوصف**: جدول لحفظ العروض المقدمة من الشركات على طلبات الصيانة

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `maintenance_request_id` - رقم طلب الصيانة
- `company_id` - رقم الشركة
- `offer_amount` - مبلغ العرض
- `offer_bill_id` - رقم فاتورة العرض
- `labor_cost` - تكلفة العمالة
- `items_total` - إجمالي الأغراض
- `total_amount` - المبلغ الإجمالي
- `status` - الحالة (معلق، مقبول، مرفوض، مكتمل)
- `created_at`, `updated_at` - التواريخ

---

### 5. جدول `maintenance_companies` (شركات الصيانة)
**الوصف**: جدول لحفظ معلومات شركات الصيانة وتقييماتها

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `companies_id` - معرف الشركة (يربط بـ users.usercode)
- `company_name` - اسم الشركة
- `contact_phone` - رقم التواصل
- `contact_email` - البريد الإلكتروني
- `specialization` - التخصص (سباكة، كهرباء، تكييف، نجارة، دهان، عام)
- `service_area` - المناطق التي تخدمها (JSON)
- `avg_rating` - متوسط التقييم (0-5)
- `total_requests_completed` - إجمالي الطلبات المكتملة
- `avg_response_time_hours` - متوسط وقت الاستجابة بالساعات
- `reliability_score` - نقاط الموثوقية (0-5)
- `is_active` - هل الشركة نشطة
- `usercode` - كود المستخدم

---

### 6. جدول `maintenance_attachments` (مرفقات الصيانة)
**الوصف**: جدول لحفظ الملفات المرفقة بطلبات الصيانة والعروض

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `maintenance_request_id` - رقم طلب الصيانة
- `bid_id` - رقم العرض
- `message_id` - رقم الرسالة
- `file_name` - اسم الملف
- `file_path` - مسار الملف
- `file_type` - نوع الملف
- `file_size` - حجم الملف بالبايت
- `uploaded_by` - رقم المستخدم الذي رفع الملف
- `uploaded_by_type` - نوع المستخدم (owner, company)
- `created_at` - تاريخ الرفع

---

### 7. جدول `maintenance_messages` (رسائل الصيانة)
**الوصف**: جدول للرسائل بين المالكين والشركات حول طلبات الصيانة

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `maintenance_request_id` - رقم طلب الصيانة
- `sender_id` - رقم المرسل
- `sender_type` - نوع المرسل (owner, company)
- `receiver_id` - رقم المستقبل
- `receiver_type` - نوع المستقبل (owner, company)
- `subject` - موضوع الرسالة
- `message` - محتوى الرسالة
- `is_read` - هل تمت القراءة
- `created_at` - تاريخ الإرسال

---

### 8. جدول `maintenance_reviews` (تقييمات الصيانة)
**الوصف**: جدول لتقييمات خدمات الصيانة

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `maintenance_request_id` - رقم طلب الصيانة
- `company_id` - رقم الشركة
- `reviewer_id` - رقم المقيم
- `reviewer_type` - نوع المقيم (owner, company)
- `rating` - التقييم (1-5)
- `comment` - التعليق
- `is_public` - هل التقييم عام
- `created_at` - تاريخ التقييم

---

### 9. جدول `maintenance_documents` (مستندات الصيانة)
**الوصف**: جدول لحفظ المستندات المتعلقة بالصيانة

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `maintenance_request_id` - رقم طلب الصيانة
- `document_type` - نوع المستند
- `document_path` - مسار المستند
- `uploaded_by` - رقم المستخدم
- `created_at` - تاريخ الرفع

---

### 10. جدول `maintenance_invoices` (فواتير الصيانة)
**الوصف**: جدول لحفظ فواتير الصيانة

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `maintenance_request_id` - رقم طلب الصيانة
- `company_id` - رقم الشركة
- `invoice_number` - رقم الفاتورة
- `amount` - المبلغ
- `status` - الحالة
- `created_at` - تاريخ الإنشاء

---

### 11. جدول `tenders_services` (خدمات المناقصات)
**الوصف**: جدول ربط بين المناقصات والخدمات (Many-to-Many)

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `tender_id` - رقم المناقصة
- `service_id` - رقم الخدمة
- `created_at` - تاريخ الربط

---

### 12. جدول `tenders_status` (حالات المناقصات)
**الوصف**: جدول لتتبع تاريخ تغيير حالات المناقصات والعروض

**الحقول الرئيسية**:
- `id` - المعرف الرئيسي
- `tender_id` - رقم المناقصة
- `bid_id` - رقم العرض (اختياري)
- `status` - الحالة
- `reason` - سبب تغيير الحالة
- `changed_by` - رقم المستخدم الذي غيّر الحالة
- `changed_by_role` - دور المستخدم
- `created_at` - تاريخ التغيير

---

## العلاقات بين الجداول

```
tenders (المناقصات العامة)
  ├── tenders_services (ربط الخدمات)
  └── tenders_status (تتبع الحالات)

maintenance_tenders (مناقصات الصيانة)
  ├── maintenance_bids (العروض)
  │   └── maintenance_attachments (المرفقات)
  ├── maintenance_messages (الرسائل)
  ├── maintenance_reviews (التقييمات)
  ├── maintenance_documents (المستندات)
  └── maintenance_invoices (الفواتير)

maintenance_requests (طلبات الصيانة المباشرة)
  ├── maintenance_bids (العروض)
  └── maintenance_attachments (المرفقات)

maintenance_companies (شركات الصيانة)
  ├── maintenance_bids (العروض المقدمة)
  └── maintenance_reviews (التقييمات)
```

---

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

1. **جدول `tenders`**: جدول عام يستخدم لجميع أنواع المناقصات (صيانة، تنظيف، نقل عفش)
2. **جدول `maintenance_tenders`**: جدول متخصص لمناقصات الصيانة فقط (المرجع من owner)
3. **جدول `maintenance_requests`**: يستخدم للطلبات المباشرة (غير المناقصات)
4. **الفرق بين `tenders` و `maintenance_tenders`**:
   - `tenders`: جدول عام بسيط للمستخدمين العاديين
   - `maintenance_tenders`: جدول متقدم للمالكين مع تفاصيل أكثر (property_id, tenant_id, owner_id, office_id)

---

## الاستخدام في الكود

### في `users/user/services/services.php`:
```php
SELECT COUNT(*) FROM tenders WHERE user_id = ? AND status IN ('pending', 'open', 'in_progress')
```

### في `users/user/trender/add_request.php`:
```php
INSERT INTO tenders (user_id, project_type, description, budget, ...)
```

### في `users/owner/maintenance/`:
```php
SELECT * FROM maintenance_tenders WHERE owner_id = ?
SELECT * FROM maintenance_bids WHERE maintenance_request_id = ?
```

---

## الحالات (Status) المستخدمة

### في `tenders`:
- pending, open, in_progress, completed, cancelled, rejected

### في `maintenance_tenders`:
- قيد المناقصة
- تم استقبال عروض
- تم الإغلاق للعروض
- بانتظار الترسية
- تم ترسية المناقصة
- بانتظار التعاقد
- تم التعاقد
- تم التكليف
- قيد التنفيذ
- تم الإنجاز
- مكتمل
- مغلق
- أغلق بدون تنفيذ
- تم التسوية
- مرفوض من الجهة المنفذة
- مرفوض من صاحب الطلب
- فشل التنفيذ
- ملغي

---

## الجداول المساعدة

### `tenant_reports` (بلاغات المستأجرين)
- يستخدم في `users/owner/maintenance/`
- يحتوي على `report_type` يمكن أن يكون 'maintenance'
- مرتبط بـ `contracts`, `properties`, `users`

---

## الخلاصة

النظام يستخدم:
1. **`tenders`** - للمستخدمين العاديين (مناقصات عامة)
2. **`maintenance_tenders`** - للمالكين (مناقصات صيانة متخصصة)
3. **`maintenance_requests`** - للطلبات المباشرة
4. **`maintenance_bids`** - للعروض المقدمة
5. **جداول مساعدة** - للرسائل، المرفقات، التقييمات، الفواتير
