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

> **الخطوة 1 من 3** — عامة (المستخدم نسي كلمة سره ومش مسجّل دخول). تفتح temp token للخطوتين اللي بعدها بس.

## 1) Identity
- **Endpoint:** `POST /api/v1/auth/forgot-password/request-code`
- **Audience / platform:** `user` — `app` (+ web — نفس الـ endpoint)
- **Flow / screen:** `forgot-password` — Figma: `<شاشة "نسيت كلمة السر — إدخال الجوال">` — **action:** إرسال كود
- **Auth / guard:** `public` (بدون توكن)
- **Rate limit:** `throttle:request-code` (OTP)
- **Ownership:** — (بيدوّر على المستخدم بالجوال)
- **Consumer:** شاشة "نسيت كلمة السر"

## 2) How it works — logic (multi-step 1/3)
- لو `country_code` مش مُرسَل → **اجعله `966`** (في `prepareForValidation`/`normalizeInputs`).
- دوّر على المستخدم بالجوال المطبّع (لازم موجود — `exists`).
- لغِّي أي OTP نشط من نوع `OtpType::FORGET_PASSWORD` للمستخدم، ثم `OtpService->sendOtp($user, OtpType::FORGET_PASSWORD, $user->phone, $user->country_code)`.
- **temp token محدود:** `$user->createToken('forget-password', ['forget-password'], now()->addMinutes(15))->plainTextToken` — صالح **15 دقيقة**، وبـ **ability واحدة** (`forget-password`) — الخطوتين الجايتين بس بيقبلوها؛ ما يعرفش يعمل أي أكشن تاني (راجع [`build-auth-audience.md`](../../../build/build-auth-audience.md) — سجّل alias الـ `ability` middleware في `bootstrap/app.php`).
- **Side effects (Laravel-first):** Notification للمستخدم «فيه محاولة لتغيير كلمة سرك الآن» (`UserNotification` عبر `SendNotificationJob` — database [+ mail/sms]) + Event `PasswordResetRequested`.
- **Multi-step (لا تجمّع):** `request-code` → **verify-code** → **reset-password**.
- Edge: جوال مش موجود → 422؛ throttle → 429.

## 3) Request
- Body:
  - `country_code` — optional · string · `exists:countries,code` (soft-delete-aware) · **default `966`**
  - `phone` — required · طبيعي عبر `PhoneNormalizer` · `exists:users,phone` `whereNull(deleted_at)`
- **Form Request:** `App\Http\Requests\Api\Auth\ForgotPasswordRequestCodeRequest` (extends `BaseApiRequest`) — الرسائل/الحقول في `validation.php`.

## 4) Response
- **Success 200:** `respondWithSuccess(__('api/auth.forgot_password_code_sent'), ['token' => $tempToken])` (أو داخل Resource صغيّر — التوكن جوّه الـ data).
- **UI copy (from design):** ar `تم إرسال رمز التحقق إلى جوالك` · en `A verification code was sent to your phone`. (إشعار: ar `فيه محاولة لتغيير كلمة سرك الآن` · en `A password reset was just requested`.)
- **Errors:** `422` (جوال غير موجود) · `429`.

## 5) Postman
- **Folder path:** `Auth` / `forgot-password` · **Request name:** `request-code`
- **URL:** `{{base_url}}auth/forgot-password/request-code` · POST · **بدون auth**
- **Body (formdata):** `country_code` (اختياري), `phone` (قيمة واقعية)
- **Test script:** خزّن التوكن المؤقت → `pm.collectionVariables.set('temp-token', pm.response.json().data.token)`
- **Examples:** ✅ success (+ token) · ⚠️ 422 · ❌ 429

## 6) Build checklist
- [ ] route (public) + thin controller + `ForgotPasswordService@requestCode` + Form Request (default 966)
- [ ] temp token (ability `forget-password`, 15 min) · Notification «محاولة تغيير» · Event `PasswordResetRequested`
- [ ] lang ar+en · tests (flow) + Postman