# رفع جریان پرداخت و اطلاعات حساب در نوبت‌گیری آنلاین

## پروژه

`nobat724_front` (سایت عمومی).

> این مشکل **کاملاً frontend** است. بک‌اند `clinicpro` همه‌ی endpointهای لازم را دارد و درست کار می‌کند: `POST /api/v1/appointment` (با `expires_at`)، `GET /api/v1/payment/config` (`test_mode`)، `POST /api/v1/payment/appointment` (`redirect_url` — در حالت تست از `MockGateway`)، `POST|GET /api/v1/payment/callback/{gateway}` (که نوبت را confirm و به `frontend_address` ریدایرکت می‌کند)، و `GET /api/v1/payment/{uuid}` (وضعیت پرداخت). نیازی به تغییر بک‌اند نیست. مرجع قرارداد: `clinicpro/docs/api/payment.md` و `docs/api/appointment.md`.

## زمینه

در فرایند نوبت‌گیری آنلاین (`/appointment/[doctorId]`) سه مشکل گزارش شده: (۱) اطلاعات حساب کاربری به‌درستی در فیلدها ست نمی‌شود، (۲) شمارنده‌ی زمان پرداخت کار نمی‌کند، (۳) درگاه پرداخت تست کار نمی‌کند. ریشه‌ی هر سه، **اشتباه در خواندن شکل پاسخ بک‌اند** در سمت frontend است — مخصوصاً پاسخ‌های double-nested بک‌اند.

یادآوری معماری پاسخ بک‌اند: `BaseController::success(['data' => X])` تولید می‌کند `{ success, data: { data: X } }`. interceptor در `services/api.js` یک بار `response.data` را برمی‌گرداند، پس مقدار واقعی در **`res.data.data`** است (نه `res.data`).

## مشکل / هدف

۱. **شمارنده + appointmentId**: پس از `POST /appointment`، فرانت `res.data.uuid` و `res.data.expires_at` را می‌خواند، اما چون پاسخ double-nested است این‌ها `undefined` می‌شوند → `appointmentId` خالی (پرداخت کار نمی‌کند) و `expiresAt` خالی (شمارنده روی مقدار ثابت `PAYMENT_TTL` می‌ماند و واقعی نیست).
۲. **درگاه تست**: درگاه تست خودِ بک‌اند است (`MockGateway`؛ وقتی `payment_test_mode=1`). فرانت باید: `redirect_url` بازگشتی از `POST /payment/appointment` را باز کند (که به callback بک‌اند می‌رود، نوبت را confirm می‌کند و به `frontend_address` با `?payment_uuid=...&status=...` برمی‌گردد). مشکل: `frontend_address` فعلی به `/payment/result` اشاره دارد که **route وجود ندارد**؛ صفحه‌ی واقعی `/payment/[uuid]` است و callback `payment_uuid` را برمی‌گرداند.
۳. **صفحه‌ی نتیجه‌ی پرداخت** (`/payment/[uuid]`): پاسخ `GET /payment/{uuid}` را به‌اشتباه می‌خواند (`setPayment(response)` به‌جای `response.data.data`) و statusها اشتباه‌اند (`completed`/`canceled` به‌جای `success`/`failed`).
۴. **اطلاعات حساب کاربری**: در `buildProfileData` کلیدها اصلاح شد (`label`→نام، `basic_insurance_id`، `gender` رشته، `national_code_approved`)؛ این وظیفه تثبیت/تأیید آن است.

## فایل‌های مرتبط

| فایل | نقش |
|------|-----|
| `components/appointment/detail/SubmitData.js` | پس از `postAppointment`، `appointmentId`/`expiresAt` را ست می‌کند — **double-nest باگ** |
| `components/appointment/paying/index.js` | شمارنده (`expiresAt` prop)، `getPaymentConfig`، `postAppointmentPayment` (`redirect_url`)، `frontend_address` |
| `app/payment/[uuid]/page.js` | صفحه‌ی نتیجه‌ی پرداخت — مصرف `getPayment` با شکل اشتباه + statusهای اشتباه |
| `services/response.js` | `getPayment`، `postAppointmentPayment`، `getPaymentConfig` (urlها درست‌اند) |
| `components/appointment/index.js` | `buildProfileData` — اطلاعات حساب (وظیفه ۴، عمدتاً انجام‌شده) |

## وضعیت فعلی (کد واقعی)

### باگ ۱ — SubmitData: خواندن نتیجه‌ی نوبت
```js
const res = await request.postAppointment(appointmentPayload);
const appointmentUuid = res?.data?.uuid;          // ❌ undefined — باید res.data.data.uuid
if (appointmentUuid) {
  setAppointmentId(appointmentUuid);
  setAppointmentExpiresAt?.(res?.data?.expires_at ?? null);  // ❌ undefined
}
```
بک‌اند `POST /appointment` پاسخ می‌دهد: `{ success, data: { data: { uuid, slot_start, slot_end, expires_at, status, ... } } }`.

### باگ ۲ — paying: frontend_address و config
```js
const res = await request.postAppointmentPayment({
  appointment_uuid: appointmentId,
  gateway: testMode ? "mellat" : selectedBank,
  frontend_address: `${window.location.origin}/payment/result`,   // ❌ route وجود ندارد
});
const redirectUrl = res?.data?.redirect_url;   // ❌ باید res.data.data.redirect_url
```
- `getPaymentConfig` نیز: `res?.data?.test_mode` خوانده می‌شود ولی پاسخ `{ success, data: { test_mode } }` است (config با `success([...])` بدون nest اضافه ساخته شده؛ یعنی `res.data.test_mode` درست است — **این یکی را تأیید کن**، چون `config()` از `$this->success([...])` مستقیم استفاده می‌کند نه `['data'=>...]`).
- callback بک‌اند به `frontend_address` با `?payment_uuid=<uuid>&status=<status>` برمی‌گردد.

### باگ ۳ — payment/[uuid]/page.js
```js
const response = await request.getPayment(params.uuid);
setPayment(response);   // ❌ باید response.data.data
// ...
const statusMap = { pending:..., completed:..., failed:..., canceled:... };  // ❌ بک‌اند: pending|success|failed|refunded
```
بک‌اند `GET /payment/{uuid}` → `{ success, data: { data: { uuid, order_id, amount_rials, status, gateway, type, reference_id, appointment_uuid, created_at } } }`. statusهای واقعی: `pending`, `success`, `failed`, `refunded`. مبلغ در `amount_rials` (ریال) است.

## وظایف

### ۱. رفع double-nest در SubmitData (شمارنده + appointmentId)
در `components/appointment/detail/SubmitData.js`:
```js
const res = await request.postAppointment(appointmentPayload);
const appt = res?.data?.data;            // unwrap درست
const appointmentUuid = appt?.uuid;
if (appointmentUuid) {
  setAppointmentId(appointmentUuid);
  setAppointmentExpiresAt?.(appt?.expires_at ?? null);
}
```
> نکته: `expires_at` بک‌اند Unix ثانیه است؛ `paying/index.js` همان را در `computeLeft` با `expiresAt * 1000` به میلی‌ثانیه تبدیل می‌کند — درست است؛ فقط باید مقدار واقعی برسد.

### ۲. اصلاح frontend_address و redirect_url در paying
در `components/appointment/paying/index.js`، تابع `handlePayment`:
- `frontend_address` را به مسیر معتبری بده که نتیجه را نشان می‌دهد. چون callback `?payment_uuid=...&status=...` را به همان آدرس append می‌کند و صفحه‌ی نتیجه `/payment/[uuid]` است، یک **route نتیجه** لازم است که `payment_uuid` را از query بخواند و کاربر را به نتیجه ببرد. دو گزینه:
  - **الف (ساده):** `frontend_address` را روی `${window.location.origin}/payment/result` بگذار و یک صفحه‌ی سبک `app/payment/result/page.js` بساز که `payment_uuid` و `status` را از `searchParams` می‌خواند و به `/payment/${payment_uuid}` ریدایرکت (یا مستقیم وضعیت را نشان) می‌دهد. (پیشنهادی)
  - **ب:** اگر صفحه‌ی `[uuid]` را نتیجه‌ی نهایی می‌گیری، می‌توان مستقیم آن را هدف frontend_address نکرد چون uuid را callback append نمی‌کند (فقط `payment_uuid`)؛ پس گزینه الف تمیزتر است.
- `redirect_url` را از `res?.data?.data?.redirect_url` بخوان (double-nest):
```js
const res = await request.postAppointmentPayment({
  appointment_uuid: appointmentId,
  gateway: testMode ? "mellat" : selectedBank,
  frontend_address: `${window.location.origin}/payment/result`,
});
const redirectUrl = res?.data?.data?.redirect_url;
if (redirectUrl) window.location.href = redirectUrl;
```
> در حالت تست، بک‌اند `MockGateway` یک `redirect_url` می‌دهد که مستقیم به callback بک‌اند می‌رود (`/api/v1/payment/callback/mock?...&mock=1&ResCode=0`) و خودِ بک‌اند نوبت را confirm و به `frontend_address` برمی‌گرداند. پس «درگاه تست» کاملاً سمت بک‌اند است و response واقعی می‌دهد — فرانت فقط `redirect_url` را باز می‌کند. **هیچ شبیه‌سازی پرداخت سمت فرانت اضافه نکن.**

### ۳. تأیید getPaymentConfig
`config()` بک‌اند از `$this->success(['test_mode' => ...])` استفاده می‌کند → پاسخ `{ success, data: { test_mode } }`. پس `res?.data?.test_mode` در `paying/index.js` **درست** است. فقط تأیید کن این مقدار را درست می‌خواند و دکمه بر اساسش «پرداخت آزمایشی»/درگاه را نشان می‌دهد.

### ۴. اصلاح صفحه‌ی نتیجه `app/payment/[uuid]/page.js`
```js
const response = await request.getPayment(params.uuid);
setPayment(response?.data?.data ?? null);   // unwrap درست
```
- statusها را با مقادیر واقعی بک‌اند هماهنگ کن: `pending` (در انتظار)، `success` (پرداخت موفق)، `failed` (ناموفق)، `refunded` (مسترد). برچسب/رنگ هر کدام.
- مبلغ از `payment.amount_rials` است (ریال) — برای نمایش تومان `/10`.
- روش پرداخت از `payment.gateway` (`mellat`/`sep`/`mock`).
- تاریخ از `payment.created_at` (Unix ثانیه).

### ۵. صفحه‌ی واسط نتیجه (اگر گزینه الف انتخاب شد)
`app/payment/result/page.js` بساز:
- `payment_uuid` و `status` را از `useSearchParams` بخوان.
- اگر `payment_uuid` بود → `router.replace('/payment/' + payment_uuid)`؛ در غیر این صورت پیام خطا.
- این صفحه فقط یک واسط ریدایرکت سبک است (با لودینگ).

### ۶. تثبیت اطلاعات حساب کاربری (انجام‌شده — تأیید)
در `components/appointment/index.js` تابع `buildProfileData` قبلاً اصلاح شده: `name` از `profile.label`، `basic_insurance`/`supplementary_insurance` از `*_id` به‌صورت `{id}`، `gender` رشته‌ی `profile.gender`، و `national_code.isEdit = !profile.national_code_approved`. تأیید کن این فیلدها در فرم (`detail/Form.js`) درست نمایش داده می‌شوند و در `SubmitData` درست ارسال می‌شوند (که سازگار است). اگر چیزی جا مانده اصلاح کن.

## نکات مهم

- **بک‌اند تغییر نمی‌کند.** همه‌ی endpointها موجود و درست‌اند؛ فقط مصرف frontend اصلاح می‌شود.
- پاسخ‌های `appointment` و `payment/{uuid}` و `payment/appointment` همگی **double-nested** اند (`res.data.data`)؛ ولی `payment/config` نیست (`res.data.test_mode`). به این تفاوت دقت کن.
- شمارنده باید از `expires_at` واقعیِ بک‌اند (Unix ثانیه) تغذیه شود؛ منطق فعلی `computeLeft` درست است، فقط ورودی‌اش باید برسد.
- پرداخت تست = درگاه تست بک‌اند (`MockGateway`)؛ فرانت فقط `redirect_url` را باز می‌کند و نتیجه را از callback/صفحه‌ی نتیجه می‌گیرد. شبیه‌سازی فرانت ممنوع.
- App Router؛ صفحه‌ی نتیجه `"use client"` (به `useSearchParams`/`useParams` نیاز دارد). RTL، فونت Vazir، MUI v5.
- بعد از تغییر: `npm run build` بدون خطا؛ جریان را end-to-end تست کن (نوبت → شمارنده فعال → پرداخت آزمایشی → callback → صفحه‌ی نتیجه با وضعیت `success`).