بناء نظام تذاكر دعم فني ذكي بكلود AI — من الصفر للإنتاج

HELPDESK SYSTEM — DATABASE SCHEMA
===================================

[tickets]
  id (UUID PK)
  ticket_number (UNIQUE, T-2026-00001)
  subject
  description (text)
  status (new/open/pending/resolved/closed)
  priority (critical/high/medium/low)
  category (bug/feature/billing/general/technical)
  subcategory
  channel (email/whatsapp/web_form/api/phone)
  customer_id (FK → customers)
  assigned_to (FK → agents, nullable)
  team_id (FK → teams, nullable)
  first_response_at (timestamp, nullable)
  resolved_at (timestamp, nullable)
  closed_at (timestamp, nullable)
  sla_breach_at (timestamp)
  satisfaction_score (1-5, nullable)
  satisfaction_comment (text)
  ai_category_confidence (float 0-1)
  ai_suggested_article_id (FK → kb_articles, nullable)
  tags (JSON array)
  created_at / updated_at

[ticket_messages]
  id (UUID PK)
  ticket_id (FK)
  author_type (customer/agent/system/ai)
  author_id (nullable)
  body (text)
  is_internal_note (boolean)
  attachments (JSON array of file paths)
  created_at

[ticket_activities]
  id / ticket_id / action / performed_by / data (JSON) / created_at

[customers]
  id / name / email / phone / company / plan_tier / language_preference
  total_tickets / satisfaction_avg / created_at

[agents]
  id / user_id / team_id / skills (JSON array) / max_tickets
  current_tickets_count / is_available / languages (JSON array)

[teams]
  id / name / description / sla_policy_id

[sla_policies]
  id / name / priority / first_response_hours / resolution_hours
  business_hours_only (boolean) / escalation_rules (JSON)

[kb_articles]
  id / title / content / category / tags / views / helpful_count
  is_public / created_by / published_at

[canned_responses]
  id / title / body / category / shortcut / usage_count

// app/Services/TicketAIAnalyzer.php
// البرومبت لكلود لكتابة هذا الكلاس كاملاً:

"اكتب PHP Service يستخدم Claude API لتحليل تذاكر الدعم الفني:

class TicketAIAnalyzer {
    public function analyze(Ticket $ticket): TicketAnalysisResult
    // المطلوب:
    // 1. إرسال نص التذكرة + سياق العميل لـ Claude API
    // 2. استرداد: category, subcategory, priority, sentiment
    // 3. البحث في قاعدة المعرفة عن مقال مطابق
    // 4. توليد رد أولي مقترح إذا المشكلة شائعة
    // 5. تحديد هل تحتاج لتدخل بشري فوري أم لا
    // 6. إعادة DTO بنتائج التحليل مع confidence scores

    البرومبت المُرسَل لـ Claude:
    ---
    أنت محلل دعم فني متخصص. حلّل هذه التذكرة وأرجع JSON:
    {
      'category': string,
      'subcategory': string,
      'priority': 'critical|high|medium|low',
      'sentiment': 'angry|frustrated|neutral|positive',
      'language': 'ar|en|mixed',
      'needs_immediate_human': boolean,
      'suggested_solution': string | null,
      'confidence': float
    }

    التذكرة: {$ticket->subject} \n {$ticket->description}
    العميل: {$customer->name} - باقة {$customer->plan_tier}
    تاريخ المشاكل السابقة: {$ticket->customer_ticket_history}
    ---
    استخدم claude-3-5-sonnet واستخرج JSON بدقة."
}

-- البرومبت لكتابة SLAManager Service --
"اكتب SLAManager Service في Laravel يُدير:

1. calculateSLADeadlines(Ticket $ticket):
   - يأخذ SLA Policy للعميل حسب خطته
   - يحسب first_response_deadline و resolution_deadline
   - يراعي Business Hours (السبت-الخميس 9ص-6م توقيت الرياض)
   - يستثني الإجازات الرسمية السعودية

2. checkBreaches() — Laravel Scheduled Job كل 5 دقائق:
   - يفحص التذاكر المفتوحة
   - يُرسل تنبيهاً للوكيل عند: 75% من الوقت انقضى
   - يُرسل تنبيهاً للمشرف عند: 90% من الوقت انقضى
   - يُصعّد التذكرة لـ Team Lead عند: انتهاء الوقت دون حل

3. escalateTicket(Ticket $ticket, string $reason):
   - ينقل التذكرة للمشرف
   - يُسجّل سبب التصعيد
   - يُرسل واتساب فورياً للمسؤول
   - يُعلم العميل أن تذكرته بيد الفريق المتخصص

استخدم Carbon لحسابات الوقت وQueue للإرسال."

-- برومبت بناء Auto-Response Engine --
"اكتب AutoResponseService يعمل بعد تحليل التذكرة:

المنطق:
إذا ai_confidence > 0.85 AND suggested_solution موجود:
  → أرسل رداً آلياً يحتوي الحل + رابط المقال
  → status = 'pending' (ننتظر تأكيد العميل)
  → إذا لم يرد العميل 48 ساعة → status = 'resolved' تلقائياً

إذا sentiment = 'angry' OR priority = 'critical':
  → أرسل رد تعاطف فوري + أسند للوكيل الأعلى خبرة
  → لا ترد بحل آلي مهما كانت الثقة

الرد الآلي يجب أن:
- يبدأ باسم العميل وتعاطف صادق
- يُلخّص المشكلة المفهومة (لضمان الفهم الصحيح)
- يُقدم الحل بخطوات واضحة
- يطرح سؤالاً للتأكد من حل المشكلة
- يُذكر رقم التذكرة وطريقة التواصل

الأسلوب: عربي واضح، ودود، مهني. لا رسمية مبالغة."

-- برومبت Knowledge Base Search Engine --
"اكتب KnowledgeBaseService يستخدم Embeddings:

1. عند نشر مقال جديد:
   - أرسل محتواه لـ Claude API لتوليد Embedding Vector
   - احفظ الـ Vector في pgvector (Supabase/PostgreSQL)

2. عند تحليل تذكرة جديدة:
   - ولّد Embedding للتذكرة
   - ابحث عن أقرب 3 مقالات بـ Cosine Similarity
   - أرجع المقالات مع درجة التشابه

3. اطلب من كلود: 'هل هذه المقالات تحل مشكلة العميل؟
   إذا نعم، لخّص الحل بأسلوب مباشر موجّه للعميل.'

4. بعد إغلاق كل تذكرة:
   - إذا لم توجد مقالة مناسبة → كلود يُقترح مسودة مقال جديد
   - المشرف يراجعه ويُنشره
   - النظام يتعلم وقاعدة المعرفة تنمو تلقائياً

المكدس: Laravel + OpenAI/Claude Embeddings + pgvector"

-- مؤشرات KPIs الأساسية --

First Response Time (FRT):
  الهدف: < 2 ساعة للأولوية عالية
  < 8 ساعات للأولوية متوسطة
  القياس: متوسط يومي وأسبوعي لكل وكيل

Average Resolution Time (ART):
  الهدف: < 24 ساعة للأولوية عالية
  < 72 ساعة للأولوية متوسطة
  القياس: حسب الفئة والوكيل

Customer Satisfaction Score (CSAT):
  استطلاع 1-5 نجمات بعد إغلاق التذكرة
  الهدف: > 4.2 متوسط
  تنبيه عند تقييم < 3

SLA Breach Rate:
  نسبة التذاكر التي انتهت مهلتها دون حل
  الهدف: < 5%
  تقرير أسبوعي للإدارة

Auto-Resolution Rate:
  نسبة التذاكر التي حُلّت بالرد الآلي
  الهدف: > 35%
  مقياس كفاءة قاعدة المعرفة

Agent Productivity:
  تذاكر مُحلّة / يوم / وكيل
  متوسط وقت معالجة التذكرة
  معدل تذاكر مُعادة للحل

-- برومبت تكامل واتساب للدعم الفني --
"اكتب WhatsApp Integration للنظام:

1. Webhook Receiver:
   - استقبال رسائل واتساب Business API
   - تحديد العميل من رقم الهاتف
   - إنشاء تذكرة جديدة أو إضافة رسالة للتذكرة المفتوحة
   - إرسال رد استلام فوري برقم التذكرة

2. Message Formatter:
   - تذاكر جديدة → رسالة واتساب للوكيل المُسنَد
   - اقتراب SLA → واتساب للمشرف
   - تقييم رضا العميل عبر واتساب بدلاً من الإيميل

3. Two-way Sync:
   - ردود الوكيل من لوحة التحكم → واتساب للعميل
   - ردود العميل على واتساب → تُضاف للتذكرة
   - Media attachments تُحفظ في Storage

الـ Template Messages المطلوبة:
- تأكيد استلام التذكرة: 'تم استلام طلبك رقم {ticket_number}'
- تحديث الحالة: 'تم حل مشكلتك. هل أنت راضٍ عن الحل؟'
- استطلاع CSAT: 'كيف تُقيّم تجربة دعمنا من 1-5؟'"