# ملخص أعمال جلسة 6-7 يوليو 2026 — HalaVoice

> مراجعة شاملة للكود، إصلاحات جذرية، ميزات جديدة، وبحث تنافسي — كل ما يلي منفَّذ ومختبَر ويعمل في الإنتاج.

---

## 1) مراجعة الكود وإصلاح الأخطاء

### أخطاء TypeScript: من 118 خطأ → **صفر**
أبرز الأخطاء كانت **bugs حقيقية وقت التشغيل** وليست مجرد أنواع:

| الخطأ | الأثر قبل الإصلاح |
|-------|-------------------|
| مسارات admin للـwebhooks تستدعي دوال غير موجودة في storage | فشل 100% عند فتح webhooks المستخدم من لوحة الأدمن |
| `HabibiTTSService.testApiKey` تُستدعى كدالة instance وهي static | زر اختبار مفتاح Habibi يفشل دائمًا |
| تفكيك `QueryResult` كمصفوفة في خدمة onboarding | فحص onboarding يفشل **بصمت** لكل مستخدم جديد |
| حالة batch `running` بينما الواجهة تتوقع `in_progress` | لوحة تقدم الحملات لا تظهر |
| استدعاء `googleCalendarService.createEvent` غير الموجودة | مزامنة مواعيد Google Calendar معطلة |
| `webhookDeliveryService.deliver` غير موجودة | إشعارات webhook للمواعيد معطلة — أُضيفت الدالة |

### إضافات (Plugins) كانت تفشل عند كل إقلاع — أُصلحت الأربع
- **debt-collection-compliance**: كانت ناقصة كليًا (بلا index.ts، استيرادات مفقودة، migration بأنواع UUID خاطئة) → أُكملت وأُنشئت جداولها السبعة.
- **arabic-enhancement-kit** و**elevenlabs-fix**: توقيعات لا تطابق عقد الـloader → أعيدت كتابتهما.
- **messaging**: تحذيرات migrations وهمية → نُظف الـmanifest.
- الجميع جُمِّع إلى `.js` (النمط المطلوب في الإنتاج). **9/9 إضافات تُحمَّل نظيفة الآن.**

### انحراف قاعدة البيانات (Schema Drift)
جداول وأعمدة معرّفة في `shared/schema.ts` لكن غير موجودة في القاعدة — كانت تكسر استعلامات agents ومزامنة المواعيد:
- أُنشئت: `groq_credentials`, `habibi_credentials`, `habibi_voices`
- أُضيفت أعمدة agents: `groq_credential_id`, `habibi_voice_id`, `habibi_credential_id`

---

## 2) البحث التنافسي وخطة التحسينات
بحث معمق في المنافسين العالميين (Vapi, Retell, Bland, Synthflow, ElevenLabs Agents) والعرب (NEVOX, Voysera, Dello, Nabrah, KalaMena) ونماذج HuggingFace العربية (SILMA, Lahgtna, Jais-2, ALLaM) وأطر open-source (Pipecat, LiveKit).

📄 **الملف:** `IMPROVEMENT_PLAN_2026-07.md` — خطة من 21 بندًا في 4 مراحل (استقرار → تكافؤ تنافسي → تميّز عربي → نمو).

---

## 3) إضافة جديدة: SAMA Call Enforcement (إنفاذ لوائح ساما على المكالمات)
📁 `plugins/sama-call-enforcement/` — تحويل طبقة بيانات الامتثال إلى **إنفاذ فعلي** بأربع طبقات:

1. **Triggers في قاعدة البيانات** (تعمل مع كل المحركات):
   - منع أي مكالمة صادرة تتجاوز حد المحاولات (10 لكل 30 يومًا — بند 3.1) في وضعي automated/hybrid
   - منع الاتصال بعميل لديه شكوى/اعتراض مفتوح (بند 4.1)
   - توثيق تلقائي لكل مكالمة مكتملة في سجل احتفاظ 10 سنوات (بند 3.1)
2. **حارس دوري (60 ث)**: استبعاد جهات الاتصال المتجاوزة من الحملات قبل الاتصال + **كشف الاعتراض تلقائيًا** في النصوص (عربي/إنجليزي) → شكوى تلقائية + تقييد تواصل
3. **حقن متطلبات ساما في برومبت الوكلاء** (ثنائي اللغة): التعريف الكامل، إشعار التسجيل، حق معاودة الاتصال، التحقق من الهوية، بروتوكول الاعتراض، طلب التقييم (بنود 2.1/3.1)
4. **صفحة تقييم رضا عامة** برابط مُرمّز يُرسل عبر واتساب، والتقييم يُوثَّق تلقائيًا

✅ اختبار تكاملي حقيقي: المكالمة الثالثة فوق الحد **مُنعت** فعليًا مع تسجيل المخالفة في سجل التدقيق.

**التفعيل لأي عميل:** صف في `debt_compliance_users` + بيانات التعريف في `debt_compliance_user_settings`.

---

## 4) تشخيص بطء SILMA + إصلاح Edge TTS جذريًا

### التشخيص
السيرفر **بلا GPU** (Xeon E-2236 فقط) — SILMA نموذج عصبي يحتاج GPU؛ البطء طبيعي وليس عطلًا.

### Edge TTS كان معطوبًا بثلاث طبقات — أُصلحت كلها
1. حزمة `edge-tts@1.0.1` قديمة ترفضها مايكروسوفت (403) → استُبدلت بـ`msedge-tts@2.0.6` (تدعم توكن Sec-MS-GEC الجديد)
2. **قاعدة البيانات مزروعة بأصوات وهمية/متقاعدة** (Naayf, Hoda, Taim, Noura, Fahed لا تنتج صوتًا) → استُبدلت بـ**32 صوتًا عربيًا حقيقيًا بـ16 لهجة** (سعودي، مصري، إماراتي، كويتي، قطري، بحريني، عماني، عراقي، أردني، لبناني، سوري، يمني، ليبي، تونسي، جزائري، مغربي)
3. الصوت الافتراضي كان المتقاعد Naayf → أصبح `ar-SA-HamedNeural`، والخدمة تجلب قائمة الأصوات الحية من مايكروسوفت تلقائيًا

✅ **النتيجة المقاسة:** توليد جملة عربية في **1.2 ثانية** مجانًا (كان الطلب يفشل 403 كليًا). مفتاح ElevenLabs في القاعدة وُجد منتهيًا (401) — يحتاج تجديدًا منك.

---

## 5) تكامل RunPod GPU (للصوت)
- **خدمة** `server/services/runpod-tts.ts` بوضعين: **Serverless** (دفع بالثانية) و**Pod** (GPU دائم أو **أي جهاز شخصي** — يقبل أي URL)
- ربط تلقائي مع SILMA بأولوية: endpoint العميل ← RunPod/الجهاز الشخصي ← CPU المحلي (fallback تلقائي)
- **بطاقة أدمن** في Voice AI: تفعيل، اختيار الوضع، المفتاح (مُخفى)، اختبار اتصال
- 📁 `runpod-worker/`: كود worker جاهز للنشر (handler.py + Dockerfile + دليل عربي كامل بالأسعار)
- **التوصية:** Serverless A4000 ($0.58/ساعة) للصوت، أو Pod A5000 ($0.27/ساعة) للصوت+LLM

📄 **خطة الجهاز الشخصي:** `PERSONAL_GPU_SERVER_PLAN.md` (مواصفات من $1,100 حتى $3,500 — استرداد التكلفة خلال 5-6 أشهر مقابل الاستئجار)

---

## 6) تكامل Custom LLM (LM Studio / خادم ذاتي الاستضافة)
ثلاث مراحل كاملة:

1. **إعداد عام (أدمن):** بطاقة "Custom LLM" في Voice AI — رابط الخادم + اسم النموذج + مفتاح اختياري + اختبار يعرض النماذج المحمّلة فعليًا
2. **توجيه الطلبات** — 4 نقاط دمج مع fallback تلقائي لـGPT-4o:
   - ردود واتساب الآلية (كان الرابط ثابتًا لـOpenAI)
   - منفّذ تدفقات واتساب
   - تحليلات المكالمات
   - تقييم العملاء المحتملين (CRM)
3. **تخصيص لكل عميل:** جدول `user_custom_llm` + تبويب "Custom LLM" في إعدادات المستخدم (بالعربية) — يكتب العميل IP خادمه (`http://IP:1234/v1`)

**الأولوية:** endpoint العميل ← الافتراضي العام ← السحابي. ✅ اختُبر بخادم LM Studio محاكى: الحل، الأولوية، ومحادثة فعلية عبر الـendpoint المخصص.

⚠️ **حدود:** المكالمات الصوتية اللحظية تبقى سحابية (LM Studio لا يدعم Realtime API).

---

## 7) إصلاح بنية تشغيلية حرجة: PM2 daemon مزدوج
اكتُشف **اثنان PM2 God Daemon** (`/root/.pm2` و`/home/pakchoi/.pm2`) يديران نسخًا مكررة من نفس التطبيقات:
- نصف طلبات الموقع كان يخدمها **كود قديم** (تذبذب 401/404 عشوائي)
- halavoice-whatsapp منهار 143 مرة في daemon، وjadwaai منهارة 438 مرة في الآخر (صراع منافذ)

**الحل المنفَّذ:** حذف النسخ المكررة المعطوبة فقط + `pm2 save` للـdaemonين. ✅ **التحقق النهائي:** مستمع واحد على 5003، استجابات متسقة 12/12، وكل المواقع (halavoice, jadwaai, whatsapp) سليمة.

---

## الملفات المرجعية المنشأة
| الملف | المحتوى |
|-------|---------|
| `IMPROVEMENT_PLAN_2026-07.md` | خطة التحسينات (21 بندًا / 4 مراحل) + مصادر البحث |
| `PERSONAL_GPU_SERVER_PLAN.md` | خطة الجهاز الشخصي (صوت + LLM) + أسعار RunPod + مواصفات العتاد |
| `runpod-worker/README.md` | دليل نشر الـGPU worker خطوة بخطوة |
| `WORK_SUMMARY_2026-07-06.md` | هذا الملف |

## توصيات معلقة (تحتاج قرارك)
1. **تجديد مفتاح ElevenLabs** (الحالي منتهٍ — 401)
2. **نقل كلمة مرور قاعدة البيانات** من CLAUDE.md/التوثيق وتدويرها
3. **تقسيم حزمة الواجهة** (6.1MB) — أولوية أداء
4. تشغيل التطبيق دائمًا عبر `pm2 restart agentlabs` فقط (لا `node dist/index.js` يدويًا) لتجنب عودة العمليات اليتيمة
5. بقية بنود خطة التحسينات (اختبار الوكلاء، المراقبة الحية، اللهجات...)