# شرح وسير عمل رحلة التسجيل عبر WhatsApp

تاريخ التحديث: 2026-05-19

هذا الدليل يشرح كيف تتحول محادثة WhatsApp داخل منصة ECOLE ECOIN إلى تسجيل فعلي، دفع عربون، تأكيد مقعد، ثم حضور أول حصة.

## الهدف العملي

الهدف ليس مجرد استقبال رسائل WhatsApp، بل تحويلها إلى مسار مبيعات وتشغيل واضح:

`رسالة WhatsApp` → `Lead` → `تأهيل` → `توصية دورة/فوج` → `إنشاء تسجيل` → `دفع العربون` → `تأكيد المقعد` → `تذكير أول حصة` → `تسجيل الحضور`

## المخطط العام

```mermaid
flowchart TD
    A["رسالة واردة من WhatsApp"] --> B["Webhook يستقبل الرسالة"]
    B --> C["إنشاء/تحديث WhatsAppContact"]
    C --> D["فتح أو تحديث Conversation"]
    D --> E{"هل الرقم معروف؟"}
    E -->|مرتبط بتسجيل| F["ربط المحادثة بـ Enrollment"]
    E -->|مرتبط بطلب مؤسسة| G["ربط المحادثة بـ B2B Lead"]
    E -->|غير معروف| H["إنشاء WhatsApp Lead"]
    H --> I["الموظف يؤهل المحادثة"]
    I --> J["اختيار دورة وفوج مناسب"]
    J --> K["إرسال توصية الدورة"]
    K --> L["إنشاء Registration + Enrollment"]
    L --> M["إنشاء Payment للعربون"]
    M --> N["إرسال تعليمات الدفع"]
    N --> O{"هل تم اعتماد العربون؟"}
    O -->|نعم| P["تأكيد المقعد stage=confirmed"]
    O -->|لا| Q["متابعة payment_pending"]
    P --> R["تذكيرات أول حصة"]
    R --> S{"حضر أول حصة؟"}
    S -->|نعم| T["stage=attended وإغلاق المحادثة"]
    S -->|لا| U["stage=no_show ورسالة متابعة"]
```

## أين تعمل الميزة داخل لوحة التحكم؟

المسار الأساسي:

- Inbox: `/admin/messaging/whatsapp/inbox`
- Conversation: `/admin/messaging/whatsapp/conversations/{conversation}`
- Templates: `/admin/messaging/whatsapp/templates`
- Settings: `/admin/messaging/whatsapp/settings`

في صفحة المحادثة تظهر:

- بيانات جهة الاتصال.
- مرحلة التحويل الحالية.
- الرسائل الواردة والصادرة.
- اختيار الدورة والفوج.
- زر إرسال توصية الدورة.
- إنشاء تسجيل من المحادثة.
- حالة التسجيل والعربون بعد الإنشاء.

## مراحل المحادثة

| Stage | المعنى | متى تستخدم؟ |
|---|---|---|
| `new` | رسالة جديدة | أول رسالة من رقم غير مؤهل |
| `interested` | مهتم | يظهر اهتمام عام بالدراسة |
| `qualified` | مؤهل | الموظف تأكد أن الطالب مناسب |
| `course_recommended` | تمت توصية دورة | بعد إرسال دورة وفوج مناسبين |
| `enrollment_started` | بدأ التسجيل | عند بدء إنشاء التسجيل |
| `payment_pending` | بانتظار العربون | بعد إنشاء Payment للعربون |
| `confirmed` | المقعد مؤكد | بعد اعتماد العربون |
| `attended` | حضر أول حصة | بعد تسجيل الحضور لأول حصة |
| `no_show` | لم يحضر | إذا غاب عن أول حصة |
| `lost` | فرصة ضائعة | إذا أغلق الموظف الفرصة |

## سير العمل اليومي للموظف

1. يفتح الموظف صندوق WhatsApp.
2. يفلتر المحادثات المفتوحة أو غير المعينة.
3. يفتح محادثة جديدة.
4. يضغط `تعيين لي` حتى تصبح المحادثة ضمن مسؤوليته.
5. يقرأ آخر رسالة ويفهم حاجة الطالب.
6. إذا الطالب مناسب، يضغط `تعليم كمؤهل`.
7. يختار الدورة المناسبة.
8. يختار الفوج المناسب حسب المقاعد وتاريخ البداية.
9. يضغط `إرسال توصية الدورة`.
10. إذا وافق الطالب، يدخل الاسم الكامل وطريقة دفع العربون.
11. يضغط `إنشاء تسجيل من المحادثة`.
12. النظام ينشئ التسجيل والعربون ويرسل تعليمات الدفع.
13. بعد اعتماد الدفع من قسم المالية، تتحول المرحلة إلى `confirmed`.
14. بعد حضور أول حصة تتحول المرحلة إلى `attended`.

## ماذا يحدث عند أول رسالة؟

عند وصول رسالة من WhatsApp:

- يتم التحقق من Webhook.
- يتم حفظ payload الخام في `whatsapp_webhook_events`.
- يتم منع التكرار عبر `provider_message_id`.
- يتم إنشاء أو تحديث `whatsapp_contacts`.
- يتم فتح `whatsapp_conversations`.
- إذا كانت الرسالة تتضمن كلمات مثل `دورة` أو `تسجيل` أو `formation` يتم إنشاء `whatsapp_leads`.

مثال:

رسالة الطالب:

```text
سلام، أريد التسجيل في دورة صيانة الحاسوب
```

النتيجة:

- Contact برقم الهاتف.
- Conversation مفتوحة.
- Lead من نوع `course`.
- Stage = `new`.

## توصية الدورة والفوج

من داخل المحادثة يختار الموظف:

- Course.
- Cohort.

ثم يرسل النظام رسالة توصية تحتوي على:

- اسم الدورة.
- اسم الفوج.
- تاريخ البداية.
- السعر.
- دعوة لاستكمال التسجيل.

بعد الإرسال:

- `whatsapp_leads.desired_course_id` يتم تحديثه.
- `whatsapp_leads.desired_cohort_id` يتم تحديثه.
- `whatsapp_conversations.stage = course_recommended`.
- يتم إنشاء رسالة outbound في timeline.
- يتم إنشاء رسالة Outbox آمنة.

## إنشاء التسجيل من المحادثة

عند موافقة الطالب:

يدخل الموظف:

- الاسم الكامل.
- طريقة الدفع: مكتب، تحويل/CCP، BaridiMob.
- يتأكد من الدورة والفوج المختارين.

ثم يضغط:

`إنشاء تسجيل من المحادثة`

النظام ينشئ:

- `registrations`
- `enrollments`
- `payments`

ويستخدم نفس سياسة العربون الموجودة في الفوج عبر:

`BillingPlanFactory`

هذا مهم لأن العربون لا يكتب يدويًا داخل WhatsApp، بل يأتي من منطق الدفع الرسمي في النظام.

## سياسة العربون

عند إنشاء التسجيل من WhatsApp:

- إذا الفوج لديه عربون ثابت، يستخدمه النظام.
- إذا الفوج يعتمد دفع كامل، يصبح العربون هو المبلغ الكامل.
- إذا يوجد balance، يتم حفظه داخل Enrollment.

الحقول المهمة:

- `total_amount_dzd`
- `deposit_required_dzd`
- `deposit_paid_dzd`
- `balance_due_dzd`
- `payment_stage`

## اعتماد الدفع

عندما يعتمد قسم المالية الدفع:

- يتم إطلاق حدث `PaymentConfirmed`.
- Listener الخاص برحلة WhatsApp يبحث عن المحادثة المرتبطة.
- يحول المرحلة إلى `confirmed`.
- يجهز رسالة تأكيد المقعد.
- يسجل event باسم `deposit_confirmed`.

النتيجة للموظف:

- يرى المحادثة في مرحلة `المقعد مؤكد`.
- يعرف أن الطالب جاهز لأول حصة.

## الحضور وأول حصة

عندما يسجل الأستاذ حضور الطالب في أول حصة:

- Attendance Workflow يكتشف أنها أول حصة.
- يتم تحديث `first_session_attended_at`.
- يتم تحديث WhatsApp stage إلى `attended`.
- يتم تعليم المحادثة كمحلولة.

إذا لم يحضر الطالب:

- يمكن استخدام `markNoShow`.
- تتحول المرحلة إلى `no_show`.
- يتم تجهيز رسالة متابعة للطالب.

## الصلاحيات

| Permission | الاستخدام |
|---|---|
| `whatsapp.inbox.view` | رؤية صندوق المحادثات |
| `whatsapp.conversations.reply` | الرد على المحادثات |
| `whatsapp.conversations.assign` | تعيين المحادثة لموظف |
| `whatsapp.templates.send` | إرسال توصية أو قالب |
| `whatsapp.enrollment.create` | إنشاء تسجيل من المحادثة |
| `whatsapp.enrollment.link` | ربط تسجيل قائم لاحقًا |
| `whatsapp.settings.manage` | إدارة إعدادات WhatsApp |

ملاحظة مهمة:

موظف الدعم يمكنه متابعة المحادثة والرد، لكن لا يجب منحه إنشاء التسجيل إلا إذا كان مخولًا بذلك.

## سيناريو تجربة كامل

### بيانات الاختبار

- رقم الطالب: `213665303336`
- الرسالة: `سلام أريد التسجيل في دورة`
- الدورة: صيانة الحاسوب
- الفوج: Groupe WhatsApp
- العربون: 5000 DZD

### الخطوات

1. أرسل رسالة WhatsApp إلى رقم المدرسة.
2. افتح `/admin/messaging/whatsapp/inbox`.
3. افتح المحادثة الجديدة.
4. اضغط `تعيين لي`.
5. اضغط `تعليم كمؤهل`.
6. اختر الدورة والفوج.
7. اضغط `إرسال توصية الدورة`.
8. أدخل اسم الطالب.
9. اختر طريقة الدفع.
10. اضغط `إنشاء تسجيل من المحادثة`.
11. افتح ملف التسجيل وتأكد من وجود Payment للعربون.
12. اعتمد العربون من لوحة المالية.
13. ارجع للمحادثة وتأكد أن stage أصبحت `confirmed`.
14. في أول حصة سجل الطالب حاضرًا.
15. تأكد أن stage أصبحت `attended`.

## ما الذي يجب أن يراه المدير؟

المدير يجب أن يستطيع قياس:

- عدد Leads الجديدة من WhatsApp.
- عدد المؤهلين.
- عدد توصيات الدورات.
- عدد التسجيلات المنشأة.
- عدد العربون بانتظار الدفع.
- عدد المقاعد المؤكدة.
- عدد الذين حضروا أول حصة.
- عدد No-show.
- عدد الفرص الضائعة.

هذه القياسات يمكن استخراجها من:

- `whatsapp_conversations.stage`
- `whatsapp_leads.status`
- `payments.status`
- `enrollments.first_session_attended_at`

## رسائل WhatsApp المستخدمة

القوالب التي يجب أن تكون موجودة:

- `whatsapp_lead_welcome`
- `whatsapp_qualification_question`
- `whatsapp_course_recommendation`
- `whatsapp_enrollment_created`
- `whatsapp_deposit_payment_instructions`
- `whatsapp_transfer_upload_request`
- `whatsapp_seat_confirmed`
- `whatsapp_attendance_confirm_request`
- `whatsapp_attendance_24h`
- `whatsapp_attendance_3h`
- `whatsapp_no_show_followup`
- `whatsapp_lost_followup`

لتثبيت القوالب:

```bash
php artisan db:seed --class=WhatsAppTemplatesSeeder
```

## قواعد أمنية وتشغيلية

- لا يتم إنشاء تسجيل إلا بصلاحية `whatsapp.enrollment.create`.
- لا يتم إرسال API خارجي إجباريًا؛ Outbox يبقى fallback آمن.
- لا يتم تسجيل Access Token في logs.
- كل رسالة outbound تظهر في timeline.
- كل إجراء مهم يسجل event داخل `whatsapp_conversation_events`.
- رقم الهاتف يخزن بصيغة دولية جزائرية مثل `213XXXXXXXXX`.

## حالات يجب الانتباه لها

- إذا الطالب أرسل من رقم مختلف عن رقم التسجيل القديم، قد لا يتم الربط تلقائيًا.
- إذا لم توجد سياسة عربون واضحة في الفوج، قد يستخدم النظام المبلغ الكامل كعربون.
- إذا كان Meta Cloud API في وضع template-only، يجب استخدام القوالب المعتمدة خارج نافذة 24 ساعة.
- no-show الآلي يحتاج جدولة لاحقة إذا أردنا تشغيله بدون تدخل الموظف.

## أوامر التحقق

```bash
php artisan migrate
php artisan db:seed --class=WhatsAppTemplatesSeeder
php artisan db:seed --class=WhatsAppEnrollmentJourneyDemoSeeder
php artisan test tests\Feature\WhatsApp\WhatsAppEnrollmentJourneyTest.php --stop-on-failure
```

## Seeder تجريبي لرؤية كل المراحل

إذا أردت رؤية كل مراحل الرحلة داخل صندوق WhatsApp بدون انتظار رسائل حقيقية، شغل:

```bash
php artisan db:seed --class=WhatsAppEnrollmentJourneyDemoSeeder
```

سينشئ هذا الـ seeder محادثة لكل مرحلة:

- `new`: رسالة جديدة لم تتحول بعد.
- `interested`: طالب مهتم ويسأل عن الأوقات.
- `qualified`: طالب مناسب تم تأهيله.
- `course_recommended`: تم إرسال توصية الدورة والفوج.
- `enrollment_started`: بدأ تجهيز التسجيل.
- `payment_pending`: التسجيل موجود والعربون بانتظار الدفع.
- `confirmed`: العربون معتمد والمقعد مؤكد.
- `attended`: الطالب حضر أول حصة.
- `no_show`: الطالب لم يحضر أول حصة ويحتاج متابعة.
- `lost`: فرصة مغلقة أو مؤجلة.

بيانات العرض تستخدم أرقامًا مثل `213660700001` إلى `213660700010`، وتستخدم prefix واضح مثل `DEMO-WA-*` حتى تعرف أنها بيانات تجريبية.

## خلاصة التشغيل

هذه الرحلة تجعل WhatsApp قناة تسجيل رسمية داخل ECOLE ECOIN، لا مجرد دردشة منفصلة. كل محادثة تتحول إلى سجل قابل للقياس، وكل تسجيل يستخدم نفس منطق العربون والدفع والحضور الموجود في النظام، وهذا يحمي الفريق من ضياع المتابعات أو تسجيل طلاب خارج المسار الرسمي.