# استراتيجية Queues & Jobs — v1

## البنية التحتية

| المكون | الغرض |
|--------|-------|
| **Database Queue** | Queue driver (يكفي لـ v1 workload) |
| **php artisan queue:work --daemon** | تشغيل queue worker كعملية بسيطة |

Database queue كافٍ لحجم العمل في v1. لا حاجة لـ Redis أو Horizon أو Supervisor.

---

## أنواع Queues حسب الأولوية

| Queue | الأولوية | أمثلة |
|-------|---------|-------|
| `default` | عادية | Notifications, media processing, batch operations |
| `low` | خلفية | Cleanup jobs, report generation |

---

## قائمة Jobs الكاملة

### 1. SendExpoPushNotification

| الخاصية | القيمة |
|---------|--------|
| Queue | `default` |
| Tries | 3 |
| Backoff | 1, 5, 10 ثواني |
| فشل | يُسجل في failed_jobs + يرسل تنبيه للمطور |

**الوظيفة:** إرسال إشعار عبر Expo Push API لجهاز معين.
**يُسترعى عند:** أي حدث إشعار (حضور، وجبات، نوم، ...).

### 2. ProcessMediaFile

| الخاصية | القيمة |
|---------|--------|
| Queue | `low` |
| Tries | 2 |
| Timeout | 300 ثانية |
| Backoff | 10, 30 ثانية |

**الوظيفة (بعد الرفع المباشر لـ R2):**
- تحميل الملف الخام من R2 `temp/` (ذاكرة السيرفر)
- إنشاء thumbnails للصور (300px)
- Resize الصور إلى أقصى عرض 1920px
- تحويل الصور إلى WebP
- ضغط الفيديو: 720p max, H.264, 1.5 Mbps — عبر FFmpeg
- رفع الملفات المُعالجة إلى المسار الدائم في R2
- حذف الملف المؤقت من `temp/`
- تحديث status إلى `ready` أو `failed`

### 3. GenerateAttendanceReport

| الخاصية | القيمة |
|---------|--------|
| Queue | `low` |
| Tries | 2 |
| Timeout | 300 ثانية |

**الوظيفة:** إنشاء تقارير Excel/PDF للحضور (شهري، فصلي) وحفظها ثم إرسال رابط لـ Admin.

### 4. PruneOldNotifications (Scheduled Job)

| الخاصية | القيمة |
|---------|--------|
| Queue | `low` |
| Schedule | `dailyAt('03:00')` |
| Tries | 1 |

**الوظيفة:** حذف الإشعارات القديمة (أكبر من 30 يوم).

### 5. CleanupExpiredAnnouncements (Scheduled Job)

| الخاصية | القيمة |
|---------|--------|
| Queue | `low` |
| Schedule | `dailyAt('04:00')` |
| Tries | 1 |

**الوظيفة:** إخفاء/حذف الإعلانات منتهية الصلاحية.

### 6. CleanupTempUploads (Scheduled Job)

| الخاصية | القيمة |
|---------|--------|
| Queue | `low` |
| Schedule | `dailyAt('02:00')` |
| Tries | 1 |

**الوظيفة:** حذف الملفات المؤقتة في R2 `temp/` التي مر عليها أكثر من 24 ساعة (رفع لم يكتمل أو لم يُسجل reference).

---

## جدولة المهام الدورية (Cron/Console Kernel)

| المهمة | الوقت | Job |
|--------|-------|-----|
| تنضيف الملفات المؤقتة | يوميًا 2:00 فجرًا | CleanupTempUploads |
| تنضيف الإشعارات | يوميًا 3:00 فجرًا | PruneOldNotifications |
| تنضيف الإعلانات | يوميًا 4:00 فجرًا | CleanupExpiredAnnouncements |

---

## نقاط مهمة

1. **لا تستخدم sync queue في production** — أي عملية إشعار يجب أن تكون غير متزامنة.
2. **Batching عند تسجيل الحضور/الوجبات/النوم bulk** — لعمل Job واحد لكل صف بدلاً من 20 Job.
3. **Rate limiting لـ Expo Push API** — الالتزام بحدود Expo APIs لتجنب 429 errors.
4. **Failed jobs table** — مراقبة دورية للمهام الفاشلة وإعادة المحاولة اليدوية عند الحاجة.
5. **Always use `dispatch()` or `ShouldQueue`** — أي عملية تأخذ > 200ms يجب أن تُدفع إلى queue.
6. **تشغيل queue worker** — يمكن تشغيله كعملية بسيطة: `php artisan queue:work --daemon`.