# دمج دروس زون التفاعلية في منصة الدلفين

## نظرة سريعة
وحدة مستقلة: استوديو معلمة + مشغّل طالب مع شخصية **دلفي 3D** تنطق اسم الطفل. تُدمج عبر iframe/SDK أو REST + Webhook.

## روابط مهمة
| الصفحة | المسار |
|---|---|
| الرئيسية | `/` |
| استوديو المعلمة | `/studio` |
| مشغّل الطالب | `/play/:lessonId` |
| تضمين | `/embed/:lessonId?student=NAME&studentId=ID&token=...` |
| SDK | `/zon-lessons-sdk.js` |
| صحة الخدمة | `GET /api/health` |

مفتاح API الافتراضي للتجربة: `zon-demo-key-change-me` — غيّره بمتغير البيئة `ZON_API_KEY`.

## 1) تضمين iframe
```html
<iframe
  src="https://YOUR_HOST/embed/seed-grade1-add-to-10?student=سارة&studentId=stu_123"
  allow="microphone; autoplay"
  style="width:100%;height:720px;border:0;border-radius:16px">
</iframe>
```

## 2) SDK &#x202B;postMessage&#x202C;
```html
<script src="https://YOUR_HOST/zon-lessons-sdk.js"></script>
<div id="lesson" style="height:720px"></div>
<script>
  ZonLessons.embed({
    container: '#lesson',
    baseUrl: 'https://YOUR_HOST',
    lessonId: 'seed-grade1-add-to-10',
    student: 'سارة',
    studentId: 'stu_123',
    onEvent(ev) {
      // ev.type: lesson_started | answer | star_awarded | lesson_completed
      console.log(ev);
      // أرسل للدلفين / احفظ التقدم
    }
  });
</script>
```

أحداث SDK من المشغّل:
- `lesson_started` — `{ sessionId, student }`
- `answer` — `{ stepId, answer, is_correct }`
- `star_awarded` — `{ stars, delta }`
- `lesson_completed` — `{ stars, sessionId }`

## 3) REST &#x202B;مختصر&#x202C;
```
GET  /api/lessons?published=1
GET  /api/lessons/:id
POST /api/lessons                 # X-API-Key
POST /api/lessons/:id/steps       # X-API-Key
POST /api/steps/:id/video         # multipart video + X-API-Key
PUT  /api/steps/:id               # X-API-Key
POST /api/lessons/:id/reorder     # {order:[stepIds]} + X-API-Key
POST /api/lessons/:id/publish
POST /api/sessions                # {lesson_id, student_name, student_id}
POST /api/sessions/:id/attempt
POST /api/sessions/:id/complete
POST /api/tts                     # {text, voice?} → audio/mpeg
POST /api/settings/webhook        # {url} + X-API-Key
GET  /api/analytics/:lessonId     # X-API-Key
```

مثال إنشاء درس:
```bash
curl -X POST https://YOUR_HOST/api/lessons \
  -H "X-API-Key: zon-demo-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{"title":"الجمع حتى 5","grade":"الصف الأول"}'
```

مثال TTS باسم الطفل:
```bash
curl -X POST https://YOUR_HOST/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"أهلاً سارة! أنا دلفي"}' -o sara.mp3
```

## 4) Webhook إلى الدلفين
اضبط:
```bash
curl -X POST https://YOUR_HOST/api/settings/webhook \
  -H "X-API-Key: zon-demo-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://dolphin.example/hooks/zon-lessons"}'
```
أو متغير البيئة `DOLPHIN_WEBHOOK_URL`.

الجسم المرسل JSON مثل:
```json
{ "event": "lesson_completed", "session": { "id":"...", "student_name":"سارة", "stars":6, "completed":1 } }
```

## 5) Docker
```bash
docker compose up -d --build
# المنفذ 8787 — اربط خلف HTTPS/نفق Cloudflare للكاميرا
```

## 6) متغيرات البيئة
| المتغير | المعنى |
|---|---|
| `PORT` | افتراضي 8787 |
| `ZON_API_KEY` | مفتاح استوديو/إدارة |
| `DOLPHIN_WEBHOOK_URL` | رابط استقبال النتائج |
| `EDGE_TTS` | مسار ثنائي edge-tts |

## 7) سير المعلمة &#x202B;مختصر&#x202C;
1. `/studio` + API Key  
2. أنشئ درسًا → أضف خطوات  
3. برومتر + عدّ 3-2-1 + تسجيل كاميرا  
4. علامات زمنية: «دلفي يقول» أو «أوقف واسأل» &#x202B;سؤال وسط الفيديو&#x202C;  
5. قص البداية/النهاية → رفع → نشر  
6. عايني كطالب أو ضمّني في الدلفين عبر SDK