# API plan — POST /api/v1/auth/forgot-password/reset-password   (audience: `user` · flow: `forgot-password`)

> **الخطوة 3 من 3** — إدخال كلمة سر جديدة و**اعتماد التغيير**. تتطلّب temp token + إن الخطوة 2 اتعملت.

## 1) Identity
- **Endpoint:** `POST /api/v1/auth/forgot-password/reset-password`
- **Audience / platform:** `user` — `app`
- **Flow / screen:** `forgot-password` — Figma: `<شاشة كلمة السر الجديدة>` — **action:** حفظ
- **Auth / guard:** `auth:sanctum` + **`ability:forget-password`** (الـ temp token بس)
- **Rate limit:** `none`
- **Ownership:** المستخدم صاحب الـ temp token
- **Consumer:** شاشة كلمة السر الجديدة (آخر خطوة)

## 2) How it works — logic (multi-step 3/3)
- **يتأكّد إن الخطوة 2 اتعملت:** يوجد OTP `FORGET_PASSWORD` بحالة `FINISHED` للمستخدم خلال آخر ~15 دقيقة — **وإلا `409`** (ما يعرفش يعمل الخطوة دي قبل ما يخلّص اللي قبلها).
- داخل `DB::transaction`: يحدّث `users.password` (الـ hash تلقائي عبر cast الموديل).
- **يبطّل الـ temp token** بعد النجاح: `$request->user()->currentAccessToken()->delete()` (مايتعادش استخدامه).
- **Side effects (Laravel-first):** Notification «تم تغيير كلمة سرك» (`UserNotification`) + Event `PasswordChanged`.
- Edge: الخطوة 2 مش متعملة → 409؛ الجديدة = القديمة → 422 (اختياري `different`).

## 3) Request
- Body:
  - `password` — required · string · `min:8`
  - `password_confirmation` — required · مع `confirmed` على `password`
- **Form Request:** `App\Http\Requests\Api\Auth\ForgotPasswordResetRequest` (extends `BaseApiRequest`). (`confirmed` مقبولة هنا لأن التصميم بيطلب تأكيد كلمة السر صراحةً.)

## 4) Response
- **Success 200:** `respondWithSuccess(__('api/auth.password_reset_success'))` — `data: []` (اختياري: إصدار توكن دخول عادي لتسجيله مباشرة).
- **UI copy (from design):** ar `تم تغيير كلمة السر بنجاح` · en `Your password has been reset`. (إشعار: ar `تم تغيير كلمة سرك` · en `Your password was changed`.)
- **Errors:** `409` (لسه ماتحقّقش من الكود) · `422` (كلمة سر قصيرة/تأكيد غلط) · `401`.

## 5) Postman
- **Folder path:** `Auth` / `forgot-password` · **Request name:** `reset-password`
- **URL:** `{{base_url}}auth/forgot-password/reset-password` · POST · Bearer **`{{temp-token}}`**
- **Body (formdata):** `password`, `password_confirmation` · **Examples:** ✅ success · ❌ 409 · ⚠️ 422 · ❌ 401

## 6) Build checklist
- [ ] route (`auth:sanctum` + `ability:forget-password`) + thin controller + `ForgotPasswordService@resetPassword` (transaction + revoke token) + Form Request
- [ ] Notification «تم تغيير كلمة السر» · Event `PasswordChanged` · lang ar+en
- [ ] tests (flow كامل 3 خطوات + منع القفز) + Postman