# Sprint 4 — الحجز والدفع (Booking & payment)

> قلب المنصة: العناوين، البطاقات، إنشاء الحجز مع الدفع والمعاملات، التفاصيل/المسار، الإلغاء، التقييم.
> المرجع: [`../analysis.md`](../analysis.md) + `scratchpad/screens_u1.md` (Booking 5 steps) + `screens_u2.md` (Booking Details/Rate).

## النطاق
- **API user — addresses:** list · show · create · update · delete · set-default (ملكية صارمة).
- **API user — payment-cards:** list · add (توكنة البوابة) · delete · set-default. **ممنوع تخزين PAN/CVV.**
- **API user — bookings:**
  - `GET /providers/{id}/availability` · `/time-slots?date=` (للخطوة 2)
  - `POST /bookings` — (service|package, event_date, start/end, location_type, address_id|venue, payment_method) → **DB transaction**: احسب subtotal+vat+commission → أنشئ booking (`IHF-YYYY-####`) → اشحن عبر PaymentGateway → أنشئ transaction (`PAY-YYYY-#####`) → حدّث الحالة. فشل الدفع ⇒ الحجز لا يُؤكّد.
  - `GET /bookings?scope=upcoming|completed` · `GET /bookings/{id}` (timeline مشتقّ) · `POST /bookings/{id}/cancel` · `POST /bookings/{id}/review`.

## الاعتماديات
- Sprint 3 (كتالوج المستخدم + مصادقته) — DONE. Settings (`app_commission`/`vat_ratio`/`currency`/`booking_auto_confirm`) من Sprint 1.

## فكّر-الأول
- **لبنات Laravel:** **DB transaction** حول إنشاء الحجز+الدفع+المعاملة · **Observer** يحدّث `providers.rating_avg`/`rating_count` عند إنشاء/إخفاء review · **Events+Listeners+Jobs** لإشعارات (booking_confirmed/…)، تُفعّل فعلياً في Sprint 6 · Policies للملكية (حجز/عنوان/بطاقة) · Form Requests (enum Rule::enum، exists soft-aware).
- **قواعد أعمال حرجة (سيرفر = مصدر الحقيقة):** احسب الإجمالي سيرفر-side (لا تثق بالعميل) · امنع **الحجز المزدوج** لنفس السلوت (قفل/تحقّق داخل الـ transaction) · التقييم **لحجز مكتمل يملكه المستخدم فقط** و**واحد لكل حجز** (unique) · الإلغاء يتبع حرّاس الحالة · الدفع ينقل unpaid→paid و status→confirmed (أو pending لو auto_confirm=false).
- **حواف:** انتهاء السلوت أثناء الدفع · فشل البوابة (rollback) · إلغاء حجز مؤكد vs قيد التنفيذ · عنوان محذوف · بطاقة محذوفة أثناء الحجز.

## design pattern (اقتراح — موافقة عند التنفيذ)
- **Strategy** لـ `PaymentGateway` (واجهة + تطبيق وهمي/حقيقي) — يسمح بتبديل Moyasar/HyperPay/Tap.
- **State** لانتقالات حالة الحجز (حرّاس انتقال صريحة) — أو خدمة BookingStatusService.
- **Action/Service** `CreateBookingAction` يغلّف الـ transaction.

## نتيجة الإنجاز (DoD)
```
migrate:fresh --seed: ⬜ · pint: ⬜ · dump-autoload -o: ⬜ · schema:check: ⬜ · test: ⬜ · smoke: ⬜ · commit: <hash>
```