# مراجعة مطابقة User Stories مع API Collection

بصفتي مدير منتج، قمت بمراجعة تفصيلية للـ 46 endpoint مقابل الـ 21 User Story الموثقة. النتائج:

---

## ✅ Epic 1 — إدارة الوصول والمصادقة (US-001, US-002, US-003)

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-001/002/003 | تسجيل الدخول (جميع الأدوار) | `POST /auth/login` | ✅ |
| US-001/002/003 | جلب بيانات المستخدم بعد الدخول | `GET /auth/me` | ✅ |
| US-001/002/003 | تسجيل الخروج | `POST /auth/logout` | ✅ |
| US-001/002/003 | تحديث الملف الشخصي | `PUT /auth/profile` | ✅ |
| US-001/002/003 | تغيير كلمة المرور | `PUT /auth/password` | ✅ |

### 🟡 ملاحظات مهمة:
- **US-001, US-002** تذكر رابط "نسيت كلمة المرور" في الواجهة، لكن **لا يوجد أي endpoint** مثل `POST /auth/forgot-password` أو `POST /auth/reset-password` في الكوليكشن — **Gap خطير يمس تجربة المستخدم**.
- قفل الحساب بعد المحاولات الفاشلة (3 لولي الأمر، 5 للمعلم/المشرف) هو **سلوك خلفي** غير مغطى بـ endpoint صريح — قد يكون منطقاً ضمن الـ Controller ولكن غير موثّق.

---

## ✅ Epic 2 — إدارة بيانات المدرسة (US-004, US-005)

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-004 | إضافة طالب جديد | `POST /admin/students` | ✅ |
| US-004 | عرض قائمة الطلاب | `GET /students` | ✅ |
| US-004 | عرض تفاصيل طالب | `GET /students/{id}` | ✅ |
| US-004 | تحديث بيانات طالب | `PUT /admin/students/{id}` | ✅ |
| US-004 | حذف طالب | `DELETE /admin/students/{id}` | ✅ |
| US-005 | إنشاء صف دراسي | `POST /admin/classes` | ✅ |
| US-005 | عرض قائمة الصفوف | `GET /admin/classes` | ✅ |

### 🟡 ملاحظة:
- US-004 يتطلب ربط ولي الأمر عند إضافة الطالب (جديد أو بحث عن حساب موجود) — حقل `parent_id` أو `parent_phone`/`parent_email` موجود في body النموذج ولكن **غير واضح** في الـ API body الحالي. الـ endpoint `POST /admin/students` لا يظهر في الـ raw model إرسال بيانات ولي الأمر (الاسم، الهاتف، الإيميل). **Gap محتمل**.

---

## ✅ Epic 3 — متابعة اليوم الدراسي (US-006, US-007, US-008)

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-006 | تسجيل الحضور (فردي) | `POST /attendance` | ✅ |
| US-006 | تسجيل الحضور (جماعي) | `POST /attendance/bulk` | ✅ |
| US-006 | عرض سجل الحضور لطالب | `GET /students/{id}/attendance` | ✅ |
| US-007 | تسجيل وجبة (فردي) | `POST /meal-records` | ✅ |
| US-007 | تسجيل وجبات (جماعي) | `POST /meal-records/bulk` | ✅ |
| US-007 | عرض سجل الوجبات لطالب | `GET /students/{id}/meal-records` | ✅ |
| US-007 | عرض قائمة الطعام | `GET /meal-plans` | ✅ |
| US-008 | تسجيل قيلولة (فردي) | `POST /sleep-records` | ✅ |
| US-008 | تسجيل قيلولة (جماعي) | `POST /sleep-records/bulk` | ✅ |
| US-008 | عرض سجل النوم لطالب | `GET /students/{id}/sleep-records` | ✅ |

### ✅ ملاحظة: تغطية ممتازة.

---

## ✅ Epic 4 — الأنشطة والوسائط (US-009, US-020)

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-009 | نشر نشاط جديد | `POST /activities` | ✅ |
| US-009 | عرض أنشطة الطالب | `GET /students/{id}/activities` | ✅ |
| US-009 | رفع الوسائط (Request URL) | `POST /media/request-upload` | ✅ |
| US-009 | تسجيل الوسائط بعد الرفع | `POST /media/register` | ✅ |
| US-009 | متابعة حالة المعالجة | `GET /media/{id}/status` | ✅ |
| US-020 | عرض أنشطة الطفل لولي الأمر | `GET /students/{id}/activities` | ✅ |
| US-020 | عرض وسائط الطفل | `GET /students/{id}/media` | ✅ |

### 🟡 ملاحظة:
- US-009 يدعم الحفظ كمسودة (`type: draft`) — الـ endpoint `POST /activities` لا يظهر حقل `status` في الـ body. **Gap بسيط**.

---

## ✅ Epic 5 — التواصل والإشعارات (US-010, US-011, US-018, US-013, US-027)

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-011 | نشر إعلان (إدارة) | `POST /admin/announcements` | ✅ |
| US-011/013/027 | عرض الإعلانات | `GET /announcements` | ✅ |
| US-011/013/027 | تحديد إعلان كمقروء | `POST /announcements/{id}/read` | ✅ |
| US-011 | حذف إعلان (إدارة) | `DELETE /admin/announcements/{id}` | ✅ |
| US-018 | عرض الإشعارات | `GET /notifications` | ✅ |
| US-018 | تحديد إشعار كمقروء | `POST /notifications/{id}/read` | ✅ |
| US-018 | عدد الإشعارات غير المقروءة | `GET /notifications/unread-count` | ✅ |

### 🔴 ثغرة حرجة: **US-010 — إرسال إشعار جماعي من المعلم**
- **لا يوجد أي endpoint** في الكوليكشن يسمح للمعلم بإنشاء وإرسال إشعار جماعي.
- الـ `POST /admin/announcements` مخصص للإدارة فقط.
- **Gap: مفقود بالكامل.**

---

## ✅ Epic 6 — ميزة الاستلام (US-012, US-023, US-028)

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-012 | إرسال إشعار "أنا قادم" | `POST /pickup/notify` | ✅ |
| US-012 | إلغاء إشعار الاستلام | `POST /pickup/{id}/cancel` | ✅ |
| US-028 | عرض إشعارات الاستلام (معلم) | `GET /pickup/alerts` | ✅ |

### 🔴 ثغرات حرجة:
- **US-028 — تأكيد الاستلام وتجهيز الطفل**: لا يوجد endpoint لتأكيد الاستلام (`POST /pickup/{id}/acknowledge`) أو تحديث الحالة إلى "الطفل جاهز" (`POST /pickup/{id}/ready`). **المعلم لا يستطيع تأكيد أو تحديث الحالة عبر API.**
- **US-023 — متابعة إشعارات الاستلام من الإدارة**: لا يوجد endpoint خاص للإدارة لعرض جميع الإشعارات (جميع الصفوف). الـ `GET /pickup/alerts` يحتوي على فلتر `class_id` لكنه موجه للمعلم. **Gap محتمل.**

---

## 🔶 Epic 7 — لوحات المعلومات وتفاصيل اليوم (US-029, US-030)

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-029 | لوحة ولي الأمر الرئيسية | `GET /auth/me` (يعيد قائمة الطلاب) + بيانات متفرقة | ⚠️ جزئي |
| US-030 | تفاصيل يوم الطفل | `GET /students/{id}` + عدة endpoints أخرى | ⚠️ جزئي |

### 🟡 ملاحظة:
- **لا يوجد endpoint مخصص** للوحة الرئيسية أو تفاصيل اليوم. يعتمد على 3-5 استعلامات منفصلة مما قد يؤثر على الأداء. يُوصى بـ:
  - `GET /parent/dashboard` يُعيد ملخص جميع الأطفال
  - `GET /students/{id}/daily-summary` يُعيد ملخص اليوم كاملاً (حضور + وجبات + قيلولة + أنشطة)

---

## 🔶 US-021 — إدخال قائمة الطعام اليومية

| US | المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :--- | :---: |
| US-021 | عرض قائمة الطعام | `GET /meal-plans` | ✅ |
| US-021 | إدخال/تعديل قائمة الطعام | **لا يوجد** | 🔴 **مفقود** |

### 🔴 ثغرة:
- **لا يوجد endpoint لإنشاء أو تعديل قائمة الطعام** (`POST /meal-plans` أو `PUT /meal-plans/{id}`). المعلم لا يستطيع إدخال القائمة عبر API.

---

## 🔶 وسائط الإعلام — Admin Media Workflow

| المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :---: |
| عرض الوسائط المعلّقة (إدارة) | `GET /admin/media/pending` | ✅ |
| الموافقة على الوسائط أو رفضها | `POST /admin/media/{id}/approve` | ✅ |
| حذف وسائط | `DELETE /media/{id}` | ✅ |

### ✅ تغطية جيدة لميزة الموافقة على الوسائط المذكورة في US-009 و US-020.

---

## 🔶 إدارة النظام — الإعدادات والتقارير والمستخدمين (Admin)

| المطلوب | Endpoint المقابل | الحكم |
| :--- | :--- | :---: |
| عرض الإعدادات | `GET /admin/settings` | ✅ |
| تحديث الإعدادات | `PUT /admin/settings` | ✅ |
| تقرير الحضور | `GET /admin/reports/attendance` | ✅ |
| عرض المستخدمين | `GET /admin/users` | ✅ |

### 🟡 ملاحظة:
- التوصيف (US-003 وغيره) يذكر "جميع التقارير" (مدفوعات، إلخ) ولكن لا توجد endpoints للتقارير المالية.
- US-003 يذكر عداد "المدفوعات المتأخرة" في لوحة الإدارة ولكن **لا يوجد أي endpoint للمدفوعات** في الكوليكشن.

---

## 📊 ملخص نتائج المطابقة

| الحالة | العدد |
| :--- | :---: |
| ✅ Endpoints موجودة ومطابقة بالكامل | **35** |
| ⚠️ موجودة جزئياً أو تحتاج تحسين | **4** |
| 🔴 مفقودة بالكامل (Gap) | **7** |

### 🔴 الـ Gaps الحرجة (مرتبة حسب الأولوية):

1. **نسيت/إعادة تعيين كلمة المرور** — US-001, US-002 (يؤثر على جميع المستخدمين)
2. **إرسال إشعار جماعي من المعلم** — US-010 (ميزة تواصل أساسية)
3. **تأكيد استلام الطفل (تأكيد + طفل جاهز)** — US-028 (يكمل ميزة "أنا قادم")
4. **إدخال/تعديل قائمة الطعام اليومية** — US-021 (يمنع تسجيل الوجبات)
5. **لوحة ولي الأمر الرئيسية (endpoint مخصص)** — US-029 (أداء)
6. **تفاصيل يوم الطفل (endpoint مدمج)** — US-030 (أداء)
7. **مدفوعات** — مذكورة في لوحة الإدارة بدون أي endpoint

### ✅ نقاط القوة في الكوليكشن:
- توحيد الاستجابة (code, message, result, success)
- Pagination موحّد
- تغطية كاملة للوجبات والقيلولة والحضور (فردي وجماعي)
- وسائط مع رفع مباشر إلى R2 ومعالجة خلفية
- استخدام Sanctum tokens
- تقسيم منطقي للمجلدات (Authentication, Students, Attendance, إلخ)