# نوبت‌دهی آنلاین بر اساس سرویس (Service-first booking)

## پروژه

`nobat724_front` (سایت عمومی نوبت‌دهی).
**Cross-repo:** وابسته به پرامپت backend `clinicpro/.claude/prompt/service-based-booking.md` — آن **اول** اجرا شود؛ این پرامپت endpoint و متای آن را مصرف می‌کند.

## زمینه

جریان فعلیِ نوبت‌گیری آنلاین یک wizard چندمرحله‌ای است بدون انتخاب سرویس:
`/appointment/[doctorId]` → روز → ساعت (اسلات ثابت) → لاگین/OTP → فرم بیمار → پرداخت.
اسلات‌ها از `GET /api/v1/appointment-slots?doctor_uuid&date` می‌آیند و همه هم‌اندازه‌اند.

بک‌اند حالت جدید «نوبت‌دهی بر اساس سرویس» را اضافه می‌کند: مدت نوبت = مجموع مدت سرویس‌های انتخابی، و endpoint جدید زمان‌های خالیِ کافی را برمی‌گرداند. سایت باید در این حالت **اول سرویس** را از بیمار بگیرد، سپس فقط زمان‌های خالیِ کافی را نشان دهد.

## هدف / spec انگلیسی

When a doctor uses `booking_mode = service`, insert a service-selection step **before** the date/time step. The patient picks one or more services; the site fetches candidate start times sized to the summed service duration from the new backend endpoint, shows only those, locks the chosen time via `postAppointment` (with the service items), then continues to the existing login/pay flow. When the doctor is in `slot` mode, the current flow is unchanged. «نوبت آزاد» (reserve) is secretary-only and never shown online.

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

| فایل | نقش |
|------|-----|
| `services/response.js` (L52 `getAppointmentSlots`, L57 `getMonthAvailability`, L62 `postAppointment`, L76 `getDoctorServices`) | افزودن `getServiceSlots` + رساندن `service_item_uuids` به postAppointment |
| `components/appointment/index.js` (L45 `AppointmentPage`, state L59-62) | افزودن state سرویس‌های انتخابی + مدت |
| `components/appointment/Container.js` (L42 `elements[]` step router) | افزودن مرحلهٔ انتخاب سرویس در ابتدای wizard (حالت سرویس) |
| `app/component/date/dateTime/index.js` (L29-52 fetch اسلات) | در حالت سرویس، فراخوانی endpoint سرویس با مدت مجموع |
| `lib/appointmentSlots.js` (L1 `adaptSlots`, L17 `hasAvailable`) | adapter برای پاسخ `start_times` |
| `components/appointment/detail/SubmitData.js` (L138-165 payload) | افزودن `service_item_uuids` به appointmentPayload |
| `app/appointment/[doctorId]/page.js` (L9, doctor fetch L17) | رساندن `booking_mode` و لیست سرویس‌ها به AppointmentPage |

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

### fetch اسلات ثابت
```js
// app/component/date/dateTime/index.js:29
request.getAppointmentSlots(doctor.uuid, dateStr).then((res) => {
  const parsed = adaptSlots(res);            // data.sessions[].slots
  ...
});
```
```js
// services/response.js:52
getAppointmentSlots: (doctor_uuid, date) =>
  api.get(`api/v1/appointment-slots?doctor_uuid=${doctor_uuid}&date=${date}`),
```

### payload رزرو — بدون سرویس
```js
// components/appointment/detail/SubmitData.js:138
const appointmentPayload = {
  doctor_uuid, slot_start: selectedSlot.start, slot_end: selectedSlot.end,
  for_self, patient_national_code, patient_gender, city_id,
};   // هیچ service_id ندارد
request.postAppointment(appointmentPayload);   // POST api/v1/appointment
```

### step router
```js
// components/appointment/Container.js:42
const elements = [Date, Login, Verify, Detail, Paying, SuccessPay, FailedPay];
// step: 0 روز/ساعت, 1 لاگین, 2 OTP, 3 فرم, 4 پرداخت ...
```

## وظایف

### ۱. سرویس در response.js

```js
// services/response.js
getServiceSlots: (doctor_uuid, date, serviceItemUuids) => {
  const q = serviceItemUuids.map(u => `service_item_uuids[]=${encodeURIComponent(u)}`).join('&');
  return api.get(`api/v1/appointment-service-slots?doctor_uuid=${doctor_uuid}&date=${date}&${q}`);
},
```
و اجازهٔ `service_item_uuids` در `postAppointment` (فقط pass-through payload).
منبع لیست سرویس‌های پزشک: `getDoctorServices` (L76, `api/v1/categorys/doctor_services`) یا endpoint سرویس‌های واقعیِ کلینیک اگر پزشک ServiceItem دارد — بررسی کن کدام سرویس‌ها `duration_minutes` دارند (فقط همان‌ها قابل‌انتخاب برای این جریان‌اند).

### ۲. تشخیص حالت پزشک

از پاسخ doctor یا از `getMonthAvailability` مقدار `booking_mode` را بخوان (backend آن را در متای weekly-schedule دارد؛ اگر در پاسخ doctor نبود، از یک فیلد مناسب که backend اضافه می‌کند). در `AppointmentPage`:
- `booking_mode === 'service'` → مرحلهٔ انتخاب سرویس فعال شود.
- در غیر این صورت → **دقیقاً** جریان فعلی (هیچ تغییری).

### ۳. مرحلهٔ انتخاب سرویس (فقط حالت سرویس)

- کامپوننت جدید `components/appointment/service/index.js`: لیست سرویس‌های پزشک با مدت و قیمت؛ انتخاب یک/چند سرویس؛ نمایش «مدت کل» = Σ `duration_minutes`.
- در `Container.js` این مرحله را **قبل** از انتخاب روز قرار بده (حالت سرویس) و state سرویس‌ها را در `AppointmentPage` نگه‌دار.

### ۴. نمایش فقط زمان‌های کافی

- در `app/component/date/dateTime/index.js`: اگر حالت سرویس است، به‌جای `getAppointmentSlots` از `getServiceSlots(uuid, dateStr, selectedServiceUuids)` استفاده کن.
- `lib/appointmentSlots.js`: یک adapter برای پاسخ `data.start_times` (آرایهٔ `{start,end,start_time,location_id}`) اضافه کن که همان ساختار مورد انتظارِ لیست ساعت را بسازد (هر مورد یک دکمهٔ زمان). چون همه از قبل «کافی» هستند، `is_available=true`.
- اگر `start_times` خالی بود: پیام «برای این سرویس در این روز زمان خالی کافی نیست» + هدایت به روز بعدِ دارای ظرفیت (از `getMonthAvailability` برای فعال/غیرفعال بودن روزها استفاده کن).

### ۵. قفل زمان هنگام ثبت

- در `SubmitData.js` به `appointmentPayload` کلید `service_item_uuids: [...]` اضافه کن (حالت سرویس). `slot_start` از انتخاب می‌آید؛ `slot_end` را backend از مدت سرویس محاسبه می‌کند (به مقدار کلاینت اعتماد نمی‌شود) ولی همان `selectedSlot.end` را هم بفرست تا سازگاری حفظ شود.
- منطق قفل دو-مرحله‌ای موجود (`postAppointment` → `expires_at` → شمارش معکوس در `paying/index.js` → redirect به `payment/order`) دست‌نخورده بماند؛ فقط payload سرویس اضافه می‌شود. مدیریت خطای 409 (reset به step 0، `SubmitData.js:178`) همان بماند.

## نکات مهم

- **«نوبت آزاد» آنلاین نیست.** هیچ مسیری برای `is_reserve` در سایت اضافه نکن؛ فقط منشی در پنل. (در سایت «رزرو» فقط برچسب بازاریابی/عنوان است، نه مدل داده — `Container.js:102`, `payment/[uuid]/page.js:206`.)
- **حالت اسلاتی دست‌نخورده:** وقتی `booking_mode !== 'service'`، هیچ کامپوننت/فراخوانیِ فعلی نباید تغییر رفتار بدهد. مرحلهٔ سرویس فقط شرطی render شود.
- **فقط سرویس‌های دارای مدت:** سرویسی که `duration_minutes` ندارد نباید در این جریان قابل‌انتخاب باشد (backend هم ۴۲۲ می‌دهد) — در UI غیرفعال/مخفی کن.
- **الگوهای پروژه:** App Router، `await params`؛ فراخوانی API از `services/response.js` (interceptor پاسخ را در `services/api.js:73` به `response.data` تبدیل می‌کند)؛ تاریخ Jalali با `moment`/`jalali-moment`؛ RTL، فونت Vazir، MUI v5 + Tailwind؛ رشته‌های UI فارسی. slug پزشک = `uuid`.
- **تست:** به `nobat724-test-suite` پروژه اضافه کن — رندر مرحلهٔ سرویس در حالت سرویس، عدم‌رندر در حالت اسلاتی، محاسبهٔ مدت کل، adapter `start_times`، افزودن `service_item_uuids` به payload.