# التقرير الفني والمعماري لهندسة نظام Ivory WhatsApp CRM & Marketing Automation (الإصدار 2.0)

مرحباً بك في وثيقة المعمارية الهندسية والتقنية التفصيلية لمنصة **Ivory WhatsApp CRM** في إصدارها الثاني المطور (V2.0). يقدم هذا الملف شرحاً دقيقاً للبنية التحتية، قواعد البيانات، طبقات معالجة المهام غير المتزامنة، آليات البث اللحظي، ومعالجة الاستثناءات والأخطاء لضمان تشغيل عالي الاستقرار ومقاوم للضغط العالي (High-Throughput).

---

## 1. البنية التقنية الأساسية وإضافات الإصدار الثاني (Technology Stack)

تم ترقية البنية التحتية للنظام بالكامل في الإصدار 2.0 لتعمل وفق منهجية معمارية حديثة تتفادى التزامن الخانق وتدعم تحديث الواجهات لحظياً دون تحميل إضافي على خوادم قاعدة البيانات.

### أ. الواجهة الخلفية والتشغيل (Backend & Job Processing)
- **PHP 8.2+**: اللغة الأساسية للمشروع لتوظيف الميزات المتقدمة وتأمين الكود ضد الأخطاء التشغيلية.
- **Laravel 12.x**: الإطار الهيكلي الأساسي، مع الاعتماد المكثف على الميزات التالية:
  - **Laravel Queues (Database Driver)**: تشغيل طوابير معالجة غير متزامنة لمعالجة مهام إرسال الحملات الكبيرة واستدعاءات Meta API المعقدة بالخلفية لضمان عدم تجميد طلبات الويب.
  - **Meta Graph API (v17.0+)**: الواجهة الرسمية المباشرة لإطلاق القوالب التفاعلية، الوسائط المتعددة، وإشارات الرسائل.
- **معالجة الاستثناءات الصارمة**: تطبيق طبقة معالجة أخطاء شاملة تستخدم حواجز `try/catch` وتقوم بتدوين أسباب الفشل الفنية في قاعدة البيانات مع إرجاع حالات `failed` دقيقة للرسائل لمنع الفشل الصامت.

### ب. الواجهة الأمامية والاتصال اللحظي (Frontend & Real-time Sync)
- **Laravel Blade & TailwindCSS v4**: لبناء واجهة مستخدم ذات جماليات معاصرة ونظام ألوان متناسق بالكامل.
- **Pusher / WebSockets Integration**: تم إلغاء نظام الاقتراع القصير المنهك (Short Polling) بالكامل، والاستعاضة عنه باتصالات مقابس مستقرة لتمرير أحداث الرسائل، حالات القراءة والتسليم، وتحديثات الوسوم اللحظية للمتصفح خلال أجزاء من الثانية.
- **نظام إتمام الردود بـ JavaScript**: محرك إكمال تلقائي مدمج بـ Vanilla JS يلتقط الاختصارات `/` ويدعم حركة الأسهم والتحكم بلوحة المفاتيح بشكل كامل.

---

## 2. مخطط العلاقات وهياكل جداول قاعدة البيانات المحدثة (Schema & Relationships)

تم إجراء تحسينات جوهرية على هيكل قاعدة البيانات لتدعم تصنيفات العملاء المتعددة (Many-to-Many) وتخزين الردود والوسوم وقوانين ساعات العمل:

```mermaid
erDiagram
    users ||--o{ contacts : "assigned_to"
    users ||--o{ messages : "sent_by"
    contacts ||--o{ messages : "has"
    whatsapp_templates ||--o{ messages : "referenced_by"
    contacts }o--o{ tags : "contact_tag (Pivot)"
    
    users {
        bigint id PK
        string name
        string email UK
        string password
        string role "admin|agent"
        timestamps created_at_updated_at
    }

    contacts {
        bigint id PK "Indexed"
        string phone UK "Indexed"
        string name
        bigint assigned_to FK "users.id"
        timestamps created_at_updated_at
    }

    tags {
        bigint id PK
        string name UK
        string color
        timestamps created_at_updated_at
    }

    contact_tag {
        bigint id PK
        bigint contact_id FK "contacts.id (Cascade)"
        bigint tag_id FK "tags.id (Cascade)"
        timestamps created_at_updated_at
    }

    messages {
        bigint id PK
        string whatsapp_message_id UK "Indexed"
        bigint contact_id FK "contacts.id"
        bigint user_id FK "users.id"
        string direction "inbound|outbound"
        string type "text|template|image|document|audio|video"
        text content NULL
        string status "sent|delivered|read|failed|received"
        text error_log NULL "Logs API failures"
        timestamps created_at_updated_at
    }

    settings {
        bigint id PK
        string key UK "Indexed"
        text value NULL
        timestamps created_at_updated_at
    }

    quick_replies {
        bigint id PK
        string shortcut UK "Indexed"
        string title
        text body
        timestamps created_at_updated_at
    }
```

### أ. الجداول الجديدة والمعدلة بالتفصيل (V2.0 Database Additions)

#### 1. جدول الوسوم [tags](file:///c:/laragon/www/whatsapp/88_server/database/migrations/2026_05_19_141715_create_tags_table.php)
يخزن التصنيفات المتاحة ديناميكياً في النظام مع ألوانها السداسية عشر المخصصة.
- `id` (BigInt, Primary Key): المعرف الفريد للوسم.
- `name` (String, Unique): اسم الوسم الفريد (مثل: عميل مهتم، تم الشراء، VIP).
- `color` (String): كود اللون التنسيقي للوسم (مثال: `#EF4444`).

#### 2. جدول المزامنة الوسيط [contact_tag](file:///c:/laragon/www/whatsapp/88_server/database/migrations/2026_05_19_141720_create_contact_tag_table.php)
يدير علاقة أطراف بأطراف بين جهات الاتصال والوسوم لتجنب تكرار البيانات وسهولة استخراج الإحصائيات.
- `contact_id` (Foreign Key): يشير إلى `contacts.id` مع خاصية `onDelete('cascade')`.
- `tag_id` (Foreign Key): يشير إلى `tags.id` مع خاصية `onDelete('cascade')`.

#### 3. جدول الردود السريعة [quick_replies](file:///c:/laragon/www/whatsapp/88_server/app/Models/QuickReply.php)
يخزن الاختصارات النصية الجاهزة للموظفين.
- `shortcut` (String, Unique, Indexed): الاختصار التقني الذي يبدأ بـ `/` (مثال: `/bank`).
- `title` (String): عنوان الرد التوضيحي.
- `body` (Text): محتوى الرسالة الكاملة التي يتم حقنها.

#### 4. جدول الإعدادات العامة [settings](file:///c:/laragon/www/whatsapp/88_server/app/Models/Setting.php)
جدول إعدادات المفاتيح والقيم لإدارة لوحة التحكم الترحيبية وساعات العمل.
- `key` (String, Unique, Indexed): اسم الإعداد البيئي (مثل `welcome_text`, `work_start`, `ooo_enabled`).
- `value` (Text, Nullable): قيمة الإعداد الحالي.

---

## 3. المعمارية البرمجية وتدفق البيانات الفني (Advanced Data Flow)

### أ. محرك معالجة المهام غير المتزامنة (Asynchronous Queue Architecture)
عند رغبة المدير في إرسال حملة بث تسويقية أو رسالة جماعية:
1. يقوم `CampaignController` بحساب المعرفات المستهدفة واستدعاء ميثود التقسيم لتقليل الضغط على الذاكرة.
2. يتم دفع كائنات المهام `SendCampaignMessage` مباشرة لطابور قاعدة البيانات `jobs` عبر دالة `dispatch()`.
3. يقوم عمال الطوابير (Queue Workers) المشتغلين بالخلفية على السيرفر بالتقاط المهام واحدة تلو الأخرى، صياغة الطلبات، إرسالها لـ Meta API، تسجيل النتيجة وتحديث حالة الرسالة.
4. يضمن ذلك حماية خادم الويب من أي تعليق أو تجاوز لزمن التنفيذ المتاح (PHP Max Execution Time).

### ب. البث اللحظي عبر المقابس (WebSocket Broadcasting Engine)
تم إلغاء نظام طلب الاستعلام كل 3 ثوانٍ المنهك لقاعدة البيانات واستبداله بالتدفق اللحظي التالي:
1. عند وصول أي إشارة من ويب هوك ميتا (رسالة جديدة، أو تحديث حالة رسالة لـ `delivered` أو `read`):
2. يقوم `WhatsAppWebhookController` بمعالجة وتحديث البيانات في الجداول.
3. يطلق النظام حدث لارافل يدعم البث (ShouldBroadcast) يسمى `MessageStatusUpdated` أو `NewMessageReceived`.
4. يقوم لارافل ببث الحدث عبر بروتوكول WebSockets مباشرة إلى متصفح العميل المفتوح.
5. يستقبل كود جافا سكريبت في الواجهة الحدث ويعدل شجرة الـ DOM والعدادات وعلامات القراءة الزرقاء فوراً دون تحميل صفحات أو استعلامات متكررة.

### ج. فهارس قاعدة البيانات والتحسين الفني (Database Indexing & Tuning)
لضمان معالجة فورية ومطابقة سريعة لأرقام الهواتف تحت الضغط العالي، تم دمج فهارس مخصصة (Database Indexes):
- إضافة فهرس فريد وثنائي على حقل `phone` في جدول `contacts`.
- إضافة فهرس بحثي على حقل `whatsapp_message_id` في جدول `messages` لتسريع مطابقة حالات استلام ميتا بالخلفية.
- فهارس مفاتيح الربط الخارجي `assigned_to` و `key` و `shortcut` لضمان أداء استعلامات فائق السرعة وجلب فوري لقوائم جهات الاتصال الخاصة بالوكيل.

### د. جدار متانة اتصالات API الاستثنائية (API Robustness & Db Log Shield)
تم توفير مستويات متقدمة لحماية الاتصال السحابي بميتا:
- تغليف دوال الاستدعاء الخارجي بـ `try/catch` متداخل لصد حالات انقطاع الاتصال أو تجاوز وقت استجابة سيرفرات ميتا (Network Timeouts).
- في حال إرجاع ميتا لرمز خطأ (مثل عدم وجود رصيد، أو رقم هاتف غير صالح): يقوم النظام بالتقاط كود الخطأ، تحديث سجل حالة الرسالة إلى `failed` فوراً، وحقن نص الخطأ التفصيلي الوارد من ميتا داخل حقل `error_log` في جدول الرسائل للاستعراض وتلافي المشاكل الإدارية دون حدوث فشل صامت.