# دليل ربط منصة Leadership Artery مع NELC / FutureX

مرجع رسمي: [nelc/NELC-Integration](https://github.com/nelc/NELC-Integration)

---

## ما هي NELC؟ وإيه الغرض منها؟

**NELC** اختصار لـ **المركز الوطني للتعليم الإلكتروني** (National eLearning Center) — جهة حكومية سعودية تابعة لمنظومة التعليم، مهمتها **تنظيم وحوكمة التعليم والتدريب الإلكتروني** داخل المملكة.

### بتعمل إيه بالظبط؟

1. **وضع المعايير واللوائح** لمنصات التعليم الإلكتروني ومقدّمي الخدمات التعليمية.
2. **تأهيل واعتماد** الجهات ومقدّمي المنصات والأدوات التعليمية قبل السماح لهم بالعمل رسمياً.
3. **متابعة وتوثيق التعلم** عبر المنصة الوطنية **FutureX** — تجمع بيانات عن تسجيل المتعلمين، تقدّمهم، إكمالهم للمحتوى، وإصدار الشهادات.
4. **إثبات الاعتماد للجمهور** — مثل شارة التحقق على موقع المنصة التي تؤكد أن الجهة مسجّلة ومعتمدة.

### إيه علاقتها بمنصتنا؟

منصتنا (LMS) منصة تعليمية **خاصة ومستقلة** — لكن حسب لوائح التعليم الإلكتروني في السعودية، الجهات التي تقدّم برامج تعليمية أو تدريبية **عن بُعد** مطلوب منها **التكامل التقني** مع FutureX التابعة لـ NELC، وليس مجرد وجود موقع تعليمي منفصل.

### ليه التكامل مهم؟

| الغرض | الشرح |
|-------|--------|
| **امتثال تنظيمي** | إثبات أن المنصة تعمل ضمن الإطار المعتمد في المملكة |
| **شفافية التعلم** | NELC تستطيع التحقق من أن بيانات المتعلمين والإنجازات حقيقية وموثّقة |
| **ثقة المستفيدين** | الشارة والاعتماد يطمئنان الطالب والجهة أن المنصة ليست عشوائية |
| **توحيد البيانات** | إرسال أحداث التعلم بصيغة موحّدة (xAPI) بدل أن كل منصة تحتفظ ببيانات معزولة |

### FutureX vs NELC

- **NELC** = الجهة المنظِّمة والمُصدِرة للمعايير والاعتماد.
- **FutureX** = المنصة الوطنية للتعليم الإلكتروني — الوسيط التقني الذي تُرسل إليه بيانات التعلم وتُعرض من خلاله خدمات الربط والتوثيق.

> **باختصار:** NELC ليست بديلاً لمنصتنا — هي **الجهة الخارجية الرسمية** التي تُشرف على التعليم الإلكتروني في السعودية، وتطلب من المنصات المعتمدة أن تُثبت هويتها (الشارة) وأن تُرسل بيانات التعلم (xAPI) بطريقة موحّدة وقابلة للتحقق.

---

## 1) فيه حاجتين مش واحدة

| | شارة التوثيق (Badge) | الربط التقني (xAPI → LRS) |
|---|---|---|
| **الهدف** | إظهار أن المنصة معتمدة للزوار | إرسال أحداث التعلم لـ NELC |
| **محتاج username/password؟** | لا | نعم (من Backend فقط) |
| **محتاج staging endpoint؟** | لا | نعم للاختبار أولاً |
| **وضعنا الحالي** | الكود جاهز في الفرونت | **غير مُنفَّذ بعد** في Laravel |

---

## 2) شارة التوثيق (اللي عندنا دلوقتي)

### الملفات
- `LMS Front/src/configs/nelcBadge.js` — تفعيل/إيقاف الشارة
- `LMS Front/src/components/shared/NelcVerificationBadge.jsx` — عرض الـ iframe
- الفوتر + أسفل يمين الشاشة (عند التفعيل)

### البيانات المطلوبة
| البيان | القيمة عندنا |
|--------|----------------|
| كود الكيان (Entity Code) | `Eft4BeAiMY0OdfoL` |
| رابط الشارة | `https://services.futurex.sa/entity-badge?code=...` |
| دومين المنصة المسجّل | رابط الموقع الرسمي على الإنتاج |

### التفعيل
في `nelcBadge.js`:
```js
export const NELC_BADGE_ENABLED = true;
```
ثم: `npm run build` ورفع `dist`.

### NELC هتبص على إيه للشارة؟
- الشارة ظاهرة على الموقع الحي
- الحالة تظهر **«معتمدة»** مش «غير موثق»
- الدومين مربوط بالكود عند FutureX

---

## 3) الربط التقني الكامل (xAPI) — المطلوب من NELC

اطلب من فريق التكامل ([integration@elc.edu.sa](mailto:integration@elc.edu.sa)):

| البيان | الاستخدام |
|--------|-----------|
| **Username** | مصادقة Basic Auth على LRS |
| **Password** | مصادقة Basic Auth على LRS |
| **Staging endpoint** | اختبار الإرسال قبل الإنتاج |
| **Production endpoint** | بعد نجاح الاختبار والموافقة |
| **Platform key** | مثل `MGMT-003` — يُرسل في كل statement تحت `context.platform` |
| **اسم المنصة الرسمي (عربي + إنجليزي)** | في `https://nelc.gov.sa/extensions/platform` |

> **مهم:** المصادقة لازم تكون من **Laravel Backend** فقط — ممنوع من الفرونت.

### إعدادات مقترحة في `.env` (بعد استلام البيانات)
```env
NELC_LRS_ENABLED=false
NELC_LRS_STAGING_URL=
NELC_LRS_PRODUCTION_URL=
NELC_LRS_USERNAME=
NELC_LRS_PASSWORD=
NELC_PLATFORM_KEY=
NELC_PLATFORM_NAME_AR="معهد شريان القيادة للتدريب"
NELC_PLATFORM_NAME_EN="Leadership Artery Training Institute"
NELC_LMS_URL=https://your-domain.com
```

---

## 4) رحلة المتعلم — الأحداث اللي NELC بتتوقعها

ترتيب تقريبي (كل حدث **مرة واحدة** فقط لكل متعلم/محتوى):

| # | Verb | متى يُرسل | مثال object |
|---|------|-----------|-------------|
| 1 | `registered` | تسجيل/شراء الدورة | course |
| 2 | `initialized` | أول دخول فعلي للمحتوى | course |
| 3 | `watched` | مشاهدة 90% من الفيديو (تلقائياً عند الانتهاء) | video |
| 4 | `completed` | إكمال درس / وحدة / module | lesson / module |
| 5 | `attended` | حضور حصة مباشرة (إن وُجدت) | virtual classroom |
| 6 | `attempted` | محاولة اختبار | quiz / assessment |
| 7 | `progressed` | بعد درس / وحدة / اختبار | course (نسبة في score) |
| 8 | `completed` | إكمال الدورة | course |
| 9 | `rated` | تقييم الدورة | course |
| 10 | `earned` | إصدار الشهادة | certificate |

---

## 5) البيانات اللي المنصة لازم تبعتها

### المتعلم (Actor)
| الحقل | مطلوب NELC | عندنا في المنصة | ملاحظة |
|-------|------------|-----------------|--------|
| `actor.name` | هوية فريدة (هوية/إقامة) | `users.national_id` | لازم 10 أرقام تبدأ بـ 1 أو 2 أو 4 |
| `actor.mbox` | البريد | `users.email` | موجود |
| الاسم الكامل | في extensions | `users.name` | موجود |
| الجوال | في extensions | `country_code` + `phone` | موجود |
| الجنسية | في extensions | `users.nationality` | موجود |
| تاريخ الميلاد | في extensions | `users.birth_date` | موجود |

### الدورة (Object)
| الحقل | مطلوب NELC | عندنا | ملاحظة |
|-------|------------|-------|--------|
| معرّف فريد ثابت | URL pattern | `courses.id` / slug | لازم صيغة ثابتة مثل `{domain}/course/{id}` |
| الاسم | نعم | `courses` (مترجم) | موجود |
| الوصف | نص كامل **بدون HTML** | وصف الدورة | راجع إن مفيش tags HTML |
| المدة | ISO 8601 | مدة الدورة | قد تحتاج حساب/تخزين |
| رابط البرنامج | `program_url` | صفحة الدورة | موجود |
| المدرب | `context.instructor` | `courses.user` | لازم اسم حقيقي |

### الفيديو / الدرس / الاختبار
| الحدث | عندنا | فجوة محتملة |
|-------|-------|-------------|
| مشاهدة فيديو | `ViewVideoController` + جدول `views` | حالياً يُسجّل عند **أول مشاهدة** — NELC تطلب **90%** من المدة |
| تقدم الدورة | حساب من الفيديوهات + الاختبارات | لا يُرسل xAPI بعد |
| الاختبارات | `UserExam` / `AnswerUser` | يحتاج ربط بـ `attempted` |
| الشهادة | `CertificatesService` + `certificates` | يحتاج رابط عام للتحقق في `jws-certificate-location` |

---

## 6) NELC هتبص على إيه عند التحقق؟

### اختبار الاتصال (Staging)
1. إرسال statement تجريبي → استجابة **HTTP 200** + **UUID** في الرد
2. ده يؤكد الاتصال بالـ LRS فقط — مش التكامل الكامل

### اختبار رحلة تعلم كاملة (Validation)
بمتعلم **جديد** ودورة **جديدة** (بدون بيانات قديمة):

- [ ] تسجيل في الدورة (`registered`)
- [ ] بدء المحتوى (`initialized`)
- [ ] مشاهدة الفيديوهات (`watched` — 90%)
- [ ] إكمال دروس/وحدات (`completed`)
- [ ] محاولات الاختبارات (`attempted` + score)
- [ ] تقدم (`progressed`)
- [ ] إكمال الدورة (`completed`)
- [ ] التقييم (`rated`) إن وُجد
- [ ] الشهادة (`earned`) + رابط التحقق

بعدها ترسل لـ NELC: **رقم هوية المتعلم + الإيميل + معرّف المحتوى**.

### أخطاء شائعة يرفضونها
- وصف الدورة فيه HTML
- إرسال نفس الحدث مرتين
- `platform key` ناقص أو غلط
- فيديو يُعتبر «مشاهَد» بزر يدوي بدل انتهاء التشغيل
- بيانات مدرب وهمية
- مصادقة من الفرونت

---

## 7) خطة الربط في مشروعنا (Laravel)

### المرحلة 1 — التحضير
1. استلام بيانات Staging من NELC
2. إضافة متغيرات `.env`
3. تثبيت [nelc/laravel-lrs-package](https://github.com/nelc/laravel-lrs-package) أو إرسال HTTP مباشر للـ LRS

### المرحلة 2 — ربط الأحداث
| حدث NELC | نقطة الربط المقترحة في الكود |
|----------|------------------------------|
| `registered` | بعد تأكيد الطلب / `PurchaseCourseAction` |
| `initialized` | أول فتح لصفحة الدرس `LessonPage` / API |
| `watched` | تتبع تقدم الفيديو (Bunny player) — **يحتاج تطوير** |
| `attempted` | بعد تسليم الاختبار |
| `completed` (course) | `StudentCourseCertificateChecker` أو منطق إكمال الدورة |
| `earned` | `CertificatesService` عند إصدار الشهادة |
| `progressed` | بعد كل درس/وحدة/اختبار |

### المرحلة 3 — الاختبار والإنتاج
1. Staging + رحلة كاملة → إيميل لـ NELC
2. بعد الموافقة → تفعيل Production endpoint
3. تفعيل الشارة على الإنتاج (`NELC_BADGE_ENABLED = true`)

> **تفاصيل الاختبار:** راجع [`docs/NELC-STAGING-CHECKLIST.md`](NELC-STAGING-CHECKLIST.md)

### ملفات التنفيذ في المشروع
| الطبقة | المسار |
|--------|--------|
| Config | `config/nelc.php` |
| الخدمات | `app/Services/Nelc/*` |
| السجلات | `app/Models/Nelc/NelcStatement.php` |
| الإرسال | `app/Jobs/SendNelcStatementJob.php` |
| التشخيص | `php artisan nelc:diagnose` |
| تتبع الفيديو (فرونت) | `LMS Front/src/hooks/useVideoProgressReporting.js` |
| مشغل الفيديو | `LMS Front/src/components/shared/Video/VideoContainer.jsx` |

---

## 8) الخلاصة السريعة

| السؤال | الجواب |
|--------|--------|
| الشارة محتاجة username/password؟ | **لا** |
| الربط التقني محتاجهم؟ | **نعم** |
| إحنا جاهزين للربط التقني؟ | **لا** — البيانات والأحداث موجودة جزئياً، لكن مفيش إرسال xAPI |
| أهم فجوة تقنية؟ | تتبع مشاهدة الفيديو 90% + إرسال الـ statements من Backend |
| مين نتواصل معاه؟ | integration@elc.edu.sa — k.alraymi@elc.edu.sa |

---

## 9) روابط مفيدة

- [دليل xAPI الرسمي](https://github.com/nelc/NELC-Integration)
- [Laravel LRS Package](https://github.com/nelc/laravel-lrs-package)
- [Laravel Helpers](https://github.com/nelc/laravel-lrs-helpers)
- [Postman Collection](https://github.com/nelc/NELC-Integration/blob/main/MyFutureX.postman_collection.json)
- [بوابة التكامل FutureX](https://integration-futurex.nelc.gov.sa/en)