# تقرير الفروقات — Postman Collection vs الكود الفعلي

تمت مراجعة `docs/postman-collection.json` ومقارنته بالكود المنفذ في الموديولات الخمسة:
Meals, SleepRecords, Activities, Announcements, Reports

---

## ١. مشاكل حرجة (Critical)

### 1.1 ActivityResource ينقصه حقل `media`

| المصدر | التفاصيل |
|--------|---------|
| **Postman** | استجابة `GET /students/{id}/activities` تحتوي على مصفوفة `media` تحتوي على `id`, `url`, `thumbnail_url`, `mime_type` |
| **Postman** | استجابة `POST /activities` تحتوي أيضاً على `"media": []` حتى لو فارغة |
| **الكود** | `ActivityResource` لا يحتوي على حقل `media` إطلاقاً |

**الملف المتأثر:** `Modules/Activities/Http/Resources/ActivityResource.php`

**الإصلاح المطلوب:** إضافة علاقة `media` للموديل `Activity` أو إضافة حقل `media` فارغ في الـ Resource.

---

### 1.2 Admin ReportController — صلاحيات خاطئة للـ meals و sleep

| المصدر | التفاصيل |
|--------|---------|
| **الكود** | `Admin\ReportController::__construct()` يربط method `meals` و `sleep` بالصلاحية `reports.attendance` بدلاً من صلاحياتهم المناسبة |
| **التأثير** | كلا الـ methods تفحص `reports.attendance` للـ 3 طرق (حضور، وجبات، نوم) — خطأ مفاهيمي |

**الملف المتأثر:** `Modules/Reports/Http/Controllers/Admin/ReportController.php:17-20`

```php
// الكود الحالي (خاطئ):
$this->applyPermissions('reports', [], [
    'attendance' => 'attendance',
    'meals' => 'attendance',    // ← يجب أن تكون 'attendance' أو تُضاف صلاحية جديدة
    'sleep' => 'attendance',    // ← يجب أن تكون 'attendance' أو تُضاف صلاحية جديدة
]);
```

**ملاحظة:** عملياً لا يوجد كسر لأن admin لديه `all:reports`، لكن المابينغ غير صحيح منطقياً. الصلاحية `reports` معرفة في `config/permissions.php` بالأكشنز: `['list', 'show', 'attendance', 'payment', 'student-progress']` — لا يوجد `meals` أو `sleep` منفصلين.

---

## ٢. مشاكل ملحوظة (Notable)

### 2.1 Student Meal Records — pagination غير متوقعة

| Postman | الكود |
|---------|-------|
| `GET /students/1/meal-records?date=2026-06-07` | نفس المسار |
| الاستجابة: `"result": [...]` مصفوفة عادية | `sendPaginatedResponse()` — يرجع pagination |
| لا يوجد `page`, `per_page` | default `per_page=10` |

**الملف:** `Modules/Meals/Http/Controllers/MealController.php:38-49`

قد يكون هذا متعمداً (pagination أفضل للأداء)، لكنه يختلف عن مواصفات Postman.

---

### 2.2 Student Sleep Records — pagination غير متوقعة

| Postman | الكود |
|---------|-------|
| `GET /students/1/sleep-records?from=...&to=...` | نفس المسار |
| الاستجابة: `"result": [...]` مصفوفة عادية | `sendPaginatedResponse()` — يرجع pagination |
| لا يوجد `page`, `per_page` | default `per_page=31` |

**الملف:** `Modules\SleepRecords\Http\Controllers\SleepRecordController.php:24-36`

---

### 2.3 Student Reports — غير موجودة في Postman

الكود أضاف 3 إندبوينتس لتقارير ولي الأمر غير موجودة في Postman ولا في `endpoints-guide.md`:

| المسار | الوصف |
|--------|-------|
| `GET /students/{id}/reports/attendance` | تقرير حضور طالب (ولي أمر) |
| `GET /students/{id}/reports/meals` | تقرير وجبات طالب (ولي أمر) |
| `GET /students/{id}/reports/sleep` | تقرير نوم طالب (ولي أمر) |

**الملف:** `Modules\Reports\Routes\api.php:9-13`, `StudentReportController.php`

---

### 2.4 Admin Reports (meals/sleep) — غير موجودة في Postman

| المسار | موجود في Postman؟ |
|--------|:--:|
| `GET /admin/reports/attendance` | نعم |
| `GET /admin/reports/meals` | لا |
| `GET /admin/reports/sleep` | لا |

`endpoints-guide.md` أيضاً يسجل فقط attendance report (#43) كامل المجموعة 12.

**الملف:** `Modules\Reports\Routes\api.php:15-19`

---

### 2.5 Admin Meals CRUD — غير موجود في Postman

أضفنا 5 إندبوينتس لإدارة تعريفات الوجبات:

| المسار | موجود في Postman؟ |
|--------|:--:|
| `GET /admin/meals` | لا |
| `POST /admin/meals` | لا |
| `GET /admin/meals/{id}` | لا |
| `PUT /admin/meals/{id}` | لا |
| `DELETE /admin/meals/{id}` | لا |

**الملف:** `Modules\Meals\Routes\api.php:17-23` — الـ 5 routes موجودة لكن غير موثقة

---

### 2.6 Admin Meal Plans CRUD — غير موجود في Postman

| المسار | موجود في Postman؟ |
|--------|:--:|
| `GET /admin/meal-plans` | لا |
| `POST /admin/meal-plans` | لا |
| `GET /admin/meal-plans/{id}` | لا |
| `PUT /admin/meal-plans/{id}` | لا |
| `DELETE /admin/meal-plans/{id}` | لا |

**الملف:** `Modules\Meals\Routes\api.php:25-31`

---

### 2.7 MealRecordResource — حقول إضافية غير موجودة في Postman

| الحقل | في Postman؟ | ملاحظة |
|-------|:-----------:|--------|
| `student_id` | لا | Postman لا يظهره |
| `student_name` | لا | Postman لا يظهره |
| `created_at` | لا | إضافي |
| `updated_at` | لا | إضافي |

**الملف:** `Modules/Meals/Http/Resources/MealRecordResource.php`

---

### 2.8 SleepRecordResource — حقول إضافية غير موجودة في Postman

| الحقل | في Postman؟ | ملاحظة |
|-------|:-----------:|--------|
| `student_id` | لا | Postman لا يظهره |
| `student_name` | لا | Postman لا يظهره |
| `created_at` | لا | إضافي |
| `updated_at` | لا | إضافي |

**الملف:** `Modules/SleepRecords/Http/Resources/SleepRecordResource.php`

---

## ٣. ملاحظات عامة (General Observations)

### 3.1 حساسيات الطلاب غير مضمّنة مع الوجبات

ملاحظة في `database-schema.md`:
> "عند توزيع الوجبات، تُعرض الحساسيات (من حقل `students.allergies`) بجانب اسم الطالب ليتمكن المعلم من الانتباه."

الكود الحالي لا يُرجع حقل الحساسيات مع meal records ولا مع bulk.

---

### 3.2 AnnouncementResource — متوافق

حقول Postman موجودة كلها، مع حقول إضافية (`target_user_id`, `target_user_name`, `created_at`, `updated_at`). لا مشكلة.

---

### 3.3 ActivityResource — ينقصه `published` في قائمة الأنشطة

| استجابة Postman GET | الكود |
|---------------------|-------|
| Postman لا يظهر `published` صراحةً | `ActivityResource` يحتوي على `published` ← إضافة جيدة |

لا مشكلة، لكن ملاحظة للتوثيق.

---

### 3.4 Reports Resources — متوافقة مع Postman

`AttendanceReportResource` يطابق استجابة Postman لـ `GET /admin/reports/attendance` تماماً (class_id, class_name, from, to, total_students, summary, daily). تقارير الوجبات والنوم (الإضافية) تتبع نفس النمط.

---

### 3.5 ملاحظة على `GET /meal-plans`

Postman يقول "Get scheduled meal plans **for a class**" لكن الـ endpoint لا يستقبل `class_id` parameter — والوجبات في قاعدة البيانات موحّدة للروضة كاملة (الجدول `meal_plans` لا يحتوي على `class_id`). هذا تناقض في وصف Postman وليس في الكود.

---

## ٤. ملخص إحصائي

| التصنيف | العدد |
|---------|:-----:|
| مشاكل حرجة (يجب إصلاحها) | ٢ |
| مشاكل ملحوظة (تستحق المراجعة) | ٨ |
| ملاحظات عامة | ٥ |
| إجمالي الإندبوينتس المنفذة في الموديولات الخمسة | ٣٠ |
| إندبوينتس موجودة في Postman ضمن نطاقنا | ١٦ |
| إندبوينتس إضافية خارج Postman | ١٤ |
| **إجمالي الإندبوينتس في Postman كاملاً** | **٥١** (١٥ مجموعة) |
| **إجمالي الإندبوينتس في الكود كاملاً** | غير محدد — خارج نطاق المراجعة |

---

## ٥. الإندبوينتس المنفذة — جدول كامل

### Meals Module (14 endpoint)

| # | المسار | في Postman؟ |
|:-:|--------|:----------:|
| 1 | `GET /meal-plans` | نعم |
| 2 | `GET /students/{id}/meal-records` | نعم |
| 3 | `POST /meal-records` | نعم |
| 4 | `POST /meal-records/bulk` | نعم |
| 5 | `GET /admin/meals` | لا |
| 6 | `POST /admin/meals` | لا |
| 7 | `GET /admin/meals/{id}` | لا |
| 8 | `PUT /admin/meals/{id}` | لا |
| 9 | `DELETE /admin/meals/{id}` | لا |
| 10 | `GET /admin/meal-plans` | لا |
| 11 | `POST /admin/meal-plans` | لا |
| 12 | `GET /admin/meal-plans/{id}` | لا |
| 13 | `PUT /admin/meal-plans/{id}` | لا |
| 14 | `DELETE /admin/meal-plans/{id}` | لا |

### SleepRecords Module (3 endpoint)

| # | المسار | في Postman؟ |
|:-:|--------|:----------:|
| 1 | `GET /students/{id}/sleep-records` | نعم |
| 2 | `POST /sleep-records` | نعم |
| 3 | `POST /sleep-records/bulk` | نعم |

### Activities Module (3 endpoint)

| # | المسار | في Postman؟ |
|:-:|--------|:----------:|
| 1 | `GET /students/{id}/activities` | نعم |
| 2 | `GET /classes/{id}/schedules` | نعم |
| 3 | `POST /activities` | نعم |

### Announcements Module (4 endpoint)

| # | المسار | في Postman؟ |
|:-:|--------|:----------:|
| 1 | `GET /announcements` | نعم |
| 2 | `POST /announcements/{id}/read` | نعم |
| 3 | `POST /admin/announcements` | نعم |
| 4 | `DELETE /admin/announcements/{id}` | نعم |

### Reports Module (6 endpoint)

| # | المسار | في Postman؟ |
|:-:|--------|:----------:|
| 1 | `GET /admin/reports/attendance` | نعم |
| 2 | `GET /admin/reports/meals` | لا |
| 3 | `GET /admin/reports/sleep` | لا |
| 4 | `GET /students/{id}/reports/attendance` | لا |
| 5 | `GET /students/{id}/reports/meals` | لا |
| 6 | `GET /students/{id}/reports/sleep` | لا |