بناء نظام إدارة علاقات العملاء (CRM) مخصص بكلود AI — من الفكرة إلى الإنتاج

CRM SYSTEM — ERD (Text Notation)
==================================

[companies]
  id (PK, UUID)
  name / name_ar
  industry / size (SME/Enterprise)
  country / city
  website / linkedin_url
  annual_revenue_estimate
  owner_id (FK → users)
  source (cold_call/referral/inbound/exhibition)
  status (prospect/active/churned/blacklisted)
  tags (JSON)
  created_at / updated_at

[contacts]
  id (PK, UUID)
  company_id (FK → companies, nullable)
  first_name / last_name / full_name_ar
  title / department
  email / phone / whatsapp
  linkedin_url
  owner_id (FK → users)
  is_primary_contact (bool)
  do_not_contact (bool)
  preferred_language (ar/en)
  notes (text)
  last_activity_at
  created_at / updated_at

[pipelines]
  id / name / description
  is_default (bool)
  stages (JSON: [{id, name, probability, position}])
  team_id (FK, nullable)

[deals]
  id (PK, UUID)
  title
  company_id (FK)
  contact_id (FK)
  pipeline_id (FK)
  stage_id (varchar — from pipeline.stages JSON)
  owner_id (FK → users)
  value (decimal)
  currency (SAR/AED/EGP/USD)
  probability (0-100)
  expected_close_date
  actual_close_date
  status (open/won/lost/on_hold)
  lost_reason
  source
  tags (JSON)
  created_at / updated_at

[activities]
  id (PK, UUID)
  type (call/email/whatsapp/meeting/note/task)
  subject
  body (text)
  direction (inbound/outbound — for calls/messages)
  duration_minutes (for calls/meetings)
  outcome (for calls: answered/voicemail/no_answer)
  contact_id (FK)
  deal_id (FK, nullable)
  user_id (FK)
  scheduled_at
  completed_at
  created_at

[email_threads]
  id / message_id (gmail/outlook ID)
  contact_id (FK)
  deal_id (FK, nullable)
  subject / snippet
  from_email / to_emails (JSON)
  received_at / sent_at
  is_read / is_outbound
  raw_content (encrypted)

[whatsapp_messages]
  id / wa_message_id
  contact_id (FK)
  deal_id (FK, nullable)
  direction (inbound/outbound)
  message_type (text/image/document/template)
  content / media_url
  template_name (if template)
  status (sent/delivered/read/failed)
  sent_at / delivered_at / read_at

[tasks]
  id / title / description
  type (follow_up/demo/proposal/call_back)
  priority (low/medium/high/urgent)
  assigned_to (FK → users)
  contact_id / deal_id (FK)
  due_date / completed_at
  is_overdue (computed)

[automation_rules]
  id / name / trigger_event
  conditions (JSON)
  actions (JSON: [{type, params}])
  is_active / runs_count / last_run_at

[custom_fields]
  id / entity_type (contact/deal/company)
  field_key / label_ar / label_en
  field_type (text/number/date/select/multiselect)
  options (JSON, for select types)
  is_required / position

// البرومبت لكلود:
"ابنِ Pipeline Board كاملاً بـ Livewire v3:

1. الواجهة:
   - عمود لكل مرحلة (مرنة — تأتي من DB)
   - كل صفقة بطاقة تحتوي: الاسم، القيمة، العميل،
     تاريخ الإغلاق المتوقع، مؤشر تأخر (أحمر إذا تجاوز X يوماً)
   - drag-and-drop بين المراحل (SortableJS)
   - إجمالي قيمة كل عمود يُحدَّث فورياً

2. عند سحب صفقة لمرحلة جديدة:
   - تحديث stage_id في DB
   - تسجيل Stage Change في activities
   - إطلاق Event يفحص Automation Rules
   - تحديث Livewire بدون Refresh

3. Quick Actions من كل بطاقة:
   - تسجيل مكالمة / إضافة ملاحظة / إنشاء مهمة
   - تغيير المسؤول (Reassign)
   - وضع علامة ربحت/خسرت

4. فلاتر:
   - حسب المسؤول / الفريق / المصدر / الفترة الزمنية
   - خيار عرض 'الخاصة بي فقط' افتراضياً

5. أداء: Lazy Load للصفقات في كل عمود،
   تحميل 20 صفقة أولاً ثم التمرير لتحميل المزيد"

// app/Services/WhatsAppCRMService.php
// البرومبت لكلود:

"اكتب WhatsAppCRMService كاملاً يتعامل مع:

1. إرسال رسالة من سياق صفقة أو اتصال:
   - Template Messages لأنواع مختلفة:
     * تأكيد الاجتماع
     * إرسال عرض السعر (مع رابط PDF)
     * متابعة بعد عرض
     * تذكير موعد
   - رسائل حرة (للمحادثات الجارية فقط)
   - حفظ كل رسالة في whatsapp_messages + activities

2. استقبال الردود (Webhook):
   - ربط الرسالة الواردة بالاتصال عبر رقم الهاتف
   - إذا لم يُعثر على اتصال — إنشاء Unassigned Message
     تظهر كـ notification للفريق لمعالجتها
   - تحديث last_activity_at للاتصال والصفقة المرتبطة
   - تشغيل Automation Rules إذا كانت trigger=message_received

3. Inbox موحّد داخل CRM:
   - عرض كل محادثات الواتساب مرتبة بالأحدث
   - Badge بعدد غير المقروءة
   - واجهة Chat بسيطة بدون مغادرة النظام

4. معالجة الأخطاء:
   - Retry مع Exponential Backoff للإرسال الفاشل
   - تسجيل الحالة في whatsapp_messages.status
   - تنبيه للمستخدم إذا فشل الإرسال نهائياً"

// البرومبت لكلود:
"ابنِ Email Sync System:

1. OAuth2 مع Gmail وOutlook للمستخدمين
   (كل مستخدم يربط صندوق بريده الشخصي)

2. Background Sync:
   - Job يُشغَّل كل 5 دقائق يجلب رسائل جديدة
   - يُطابق الرسائل بجهات الاتصال عبر عنوان البريد
   - إذا وجد مطابقة — يُضيف thread لـ email_threads
     ويُسجل activity من نوع 'email'
   - يُحدّث last_activity_at للاتصال والصفقة

3. Send from CRM:
   - يُرسل البريد من حساب Gmail/Outlook للمستخدم
   (ليس من عنوان عام — المستلم يرى اسم المندوب)
   - حفظ نسخة في Sent threads
   - ربط تلقائي بالصفقة النشطة للاتصال

4. Threading:
   - عرض سلسلة المحادثة كاملة في سياق الاتصال
   - Collapse للرسائل القديمة — عرض آخر 3 ظاهراً
   - زر 'رد' يفتح Composer داخل CRM"

// مثال قواعد أتمتة جاهزة للاستخدام:

Rule 1: "تذكير الصفقات الراكدة"
  Trigger: deal_no_activity
  Condition: days_since_last_activity >= 5 AND stage != 'won' AND stage != 'lost'
  Actions:
    - create_task: {title: "متابعة {deal.title}", due: "tomorrow", assigned_to: deal.owner}
    - send_notification: {to: deal.owner, message: "صفقة {deal.title} بدون نشاط منذ {days} أيام"}

Rule 2: "إشعار الصفقات الكبيرة"
  Trigger: deal_stage_changed
  Condition: deal.value >= 50000 AND new_stage == 'proposal_sent'
  Actions:
    - send_notification: {to: sales_manager, message: "صفقة كبيرة في مرحلة العرض: {deal.title} — {deal.value}"}
    - create_task: {title: "مراجعة عرض السعر مع المدير", assigned_to: deal.owner}

Rule 3: "رسالة ترحيب تلقائية"
  Trigger: contact_created
  Condition: contact.source == 'website_form'
  Actions:
    - send_whatsapp: {template: "welcome_new_lead", contact: contact}
    - create_task: {title: "اتصال ترحيبي بـ {contact.name}", due: "in_2_hours"}

// البرومبت لكلود:
"ابنِ Automation Engine قائم على Events:
1. AutomationRule Model مع conditions وactions JSON
2. AutomationEngine Service يُقيّم الـ Conditions بـ Rule Engine بسيط
3. ActionExecutor يُنفّذ كل نوع من Actions (create_task, send_whatsapp, send_email, update_deal, notify_user)
4. واجهة Filament لبناء Rules بدون كود (مثل Zapier بسيط)
5. AutomationLog لتسجيل كل تنفيذ ونتيجته"

// البرومبت لكلود:
"اكتب 6 Dashboard Widgets بـ Filament:

1. Pipeline Value Widget:
   - إجمالي قيمة الصفقات المفتوحة مُجمَّع بالمرحلة
   - Weighted Pipeline (القيمة × الاحتمالية)
   - مقارنة بنفس الفترة الشهر الماضي

2. Win Rate Widget:
   - نسبة الفوز خلال آخر 30/90 يوم
   - مصفوفة Win Rate: بالمرحلة التي خُسرت فيها الصفقات
   - تحليل أسباب الخسارة (lost_reason)

3. Sales Rep Leaderboard:
   - ترتيب المندوبين: عدد الصفقات المربوحة / إجمالي القيمة
   - معدل الأنشطة اليومية (مكالمات + رسائل + اجتماعات)
   - Trend: تحسن أو تراجع مقارنة بالشهر الماضي

4. Revenue Forecast Widget:
   - تنبؤ إيرادات الشهر القادم بناءً على Weighted Pipeline
   - نطاق: التفاؤلي (كل صفقة في المرحلة المتقدمة تُربح)
     الواقعي (الاحتمالية الفعلية) والمتشائم (50% من الواقعي)

5. Activity Summary Widget:
   - إجمالي الأنشطة اليوم / هذا الأسبوع (مكالمات، رسائل، اجتماعات)
   - مقارنة بالأسبوع الماضي
   - التوزيع: من الأكثر نشاطاً في الفريق

6. Deal Velocity Widget:
   - متوسط الوقت من فتح الصفقة إلى الإغلاق (بالأيام)
   - التوزيع بالمرحلة: كم يوماً تبقى الصفقات في كل مرحلة
   - تحديد نقاط الاحتقان في الـ Pipeline"

// بنية API للموبايل — Mobile-First Design
// البرومبت لكلود:

"صمّم API Layer محسّن للموبايل:

1. Endpoints الأساسية للموبايل:
   GET /api/mobile/dashboard    → ملخص اليوم (مهام + أنشطة + صفقات)
   GET /api/mobile/my-deals     → صفقاتي مع Quick Actions
   GET /api/mobile/contacts/search → بحث سريع بالاسم/هاتف
   POST /api/mobile/activities/quick-log → تسجيل نشاط بنقرة
   GET /api/mobile/inbox        → رسائل واتساب وبريد غير مقروءة

2. Quick Log (الميزة الأكثر استخداماً):
   بنقرتين يُسجّل المندوب:
   - 'اتصلت بـ X ولم يرد' (نوع + نتيجة بدون نص)
   - 'اجتمعت مع X — إيجابي، سأرسل عرضاً' (ملاحظة صوتية تُحوَّل لنص)
   - 'انتهيت من اجتماع X — مدة 45 دقيقة'

3. Offline Support:
   Local SQLite يخزن صفقات ومهام اليوم
   Sync Queue لتسجيل الأنشطة أثناء انقطاع الإنترنت
   Auto-sync عند استعادة الاتصال

4. Push Notifications:
   - صفقة جديدة مُسنَدة لك
   - مهمة تستحق اليوم (reminder صباحي)
   - رد عميل على واتساب/بريد
   - صفقة راكدة تحتاج متابعة"