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

> **الخطوة 2 من 3** — تأكيد الكود المُرسَل. تتطلّب الـ temp token من الخطوة 1.

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

## 2) How it works — logic (multi-step 2/3)
- يتحقّق من الـ OTP النشط `OtpType::FORGET_PASSWORD` بالكود المخزّن في `otps` من الخطوة 1:
  `OtpService->verifyOtp($request->user(), $code, OtpType::FORGET_PASSWORD)` → ينجح فيبقى `FINISHED` (نافذة تُستخدم في الخطوة 3).
- **Multi-step:** بعدها **reset-password**. (لو الـ temp token مش موجود/منتهي → 401؛ لو ability غلط → 403.)
- Edge: كود غلط/منتهٍ/تعدّى المحاولات → 422.

## 3) Request
- Body: `code` — required · string (طول الكود من الإعدادات)
- **Form Request:** `App\Http\Requests\Api\Auth\ForgotPasswordVerifyCodeRequest` (extends `BaseApiRequest`) — رسائل الكود في `validation.php` (`custom.code.invalid`).

## 4) Response
- **Success 200:** `respondWithSuccess(__('api/auth.forgot_password_code_verified'))` — `data: []` (نفس الـ temp token يكمل للخطوة 3).
- **UI copy (from design):** ar `تم التحقق من الرمز` · en `Code verified`.
- **Errors:** `422` (كود غلط/منتهٍ) · `401` (temp token مفقود/منتهي) · `403` (ability غلط).

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

## 6) Build checklist
- [ ] route (`auth:sanctum` + `ability:forget-password`) + thin controller + `ForgotPasswordService@verifyCode` + Form Request
- [ ] lang ar+en · tests (flow) + Postman