# تنظیمات نوبت‌دهی آنلاین دکتر: بازه‌ی رزرو (booking window) + endpoint در‌دسترس‌بودن ماهانه

## پروژه

`clinicpro` (Backend + Admin React panel). **این پرامپت اول اجرا شود.**

> **Cross-repo:** قرارداد API این پرامپت توسط سایت عمومی مصرف می‌شود. پرامپت همتا در سمت فرانت:
> `nobat724_front/.claude/prompt/appointment-calendar-disabled-dates.md`

## زمینه

پزشک در پنل ادمین (`assets/admin/pages/DoctorDetailPage.tsx`) از قبل می‌تواند **برنامه‌ی هفتگی**، **date override** (روز تعطیل/سفارشی) و **تعطیلات (holidays)** را تنظیم کند. `SlotCalculatorService` هم این‌ها را با اولویت درست اعمال می‌کند (holiday → override → weekly). پس «۲۷/۰۳/۱۴۰۵ تعطیل است» همین حالا با یک date override (`active:false`) قابل تنظیم است و `appointment-slots` برای آن روز آرایه‌ی خالی برمی‌گرداند.

اما **دو چیز وجود ندارد:**

1. **بازه‌ی رزرو آنلاین (booking window):** پزشک نمی‌تواند تعیین کند «تا چند هفته/ماه جلوتر بیمار می‌تواند آنلاین نوبت بگیرد» و نمی‌تواند نوبت‌دهی آنلاین را کلاً خاموش کند. الان هیچ سقفی نیست و `appointment-slots` برای هر تاریخ آینده‌ای اسلات می‌دهد.
2. **در‌دسترس‌بودن ماهانه (month availability):** سایت عمومی برای خاکستری‌کردن روزهای تعطیل/خارج‌از‌بازه روی تقویم، باید بداند کدام روزهای یک ماه قابل‌انتخاب‌اند. الان فقط endpoint تک‌روزه (`appointment-slots`) هست؛ صدا‌زدن آن برای ۳۰ روز سنگین است. یک endpoint که برای یک ماه، آرایه‌ی روزهای غیرفعال را برگرداند لازم است.

## مشکل / هدف

۱. افزودن تنظیمات «نوبت‌دهی آنلاین» به پزشک: `online_booking_enabled` (boolean) و `booking_window` (عدد + واحد هفته/ماه). بدون migration — داخل همان `WeeklySchedule.setting` JSON ذخیره شود.
۲. اعمال این بازه در `SlotCalculatorService`: اگر نوبت‌دهی آنلاین خاموش است یا تاریخ خارج از بازه است → اسلات خالی.
۳. endpoint عمومی جدید: `GET /api/v1/appointment-settings/month-availability/{doctorUuid}?year=&month=` که برای یک ماه شمسی **یا** میلادی، روزهای غیرفعال (تعطیل/override بسته/خارج‌از‌بازه/بدون session) را برگرداند تا تقویم سایت آن‌ها را غیرقابل‌انتخاب کند.
۴. UI در پنل ادمین (`DoctorDetailPage.tsx`) برای تنظیم این دو مقدار.

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

| فایل | نقش |
|------|-----|
| `src/Appointment/Entity/WeeklySchedule.php` | `setting` JSON — محل ذخیره‌ی booking window (بدون فیلد جدید DB) |
| `src/Appointment/Service/SlotCalculatorService.php` | منطق محاسبه‌ی اسلات — اعمال window |
| `src/Appointment/Controller/AppointmentController.php` | `appointment-slots` (تک‌روز) — باید window را respect کند |
| `src/Appointment/Controller/AppointmentSettingsController.php` | weekly-schedule upsert + endpoint جدید month-availability |
| `src/Appointment/Repository/WeeklyScheduleRepository.php` | `findByDoctor` |
| `docs/api/appointment-settings.md` | مستندسازی window + endpoint جدید |
| `docs/api/appointment.md` | اگر رفتار `appointment-slots` تغییر کرد |
| `assets/admin/pages/DoctorDetailPage.tsx` | UI تنظیم booking window + toggle آنلاین |

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

### `WeeklySchedule.php` — ذخیره‌سازی در JSON

```php
#[ORM\Column(type: 'json')]
private array $setting = [];
```

> `setting` الان فقط کلیدهای `"0".."6"` (روزهای هفته) را دارد. می‌توان یک کلید رزروشده‌ی غیرعددی مثل `"meta"` اضافه کرد بدون اینکه `SlotCalculatorService` که فقط کلیدهای عددی روز را می‌خواند، بشکند.

### `SlotCalculatorService::buildAllSessions()` — ترتیب اولویت فعلی

```php
private function buildAllSessions(Doctor $doctor, string $date): array
{
    $dayStart = (int) strtotime($date . ' 00:00:00');
    $dayEnd   = $dayStart + 86400;

    // 1. Blocked by holiday
    if (!empty($this->holidayRepo->findActiveByDoctor($doctor, $dayStart, $dayEnd - 1))) {
        return [];
    }
    // 2. Date override
    foreach ($this->overrideRepo->findByDoctor($doctor) as $override) {
        if (date('Y-m-d', $override->getDate()) === $date) {
            if (!$override->isActive()) return [];
            return $this->buildSessionsFromOverride($override->getSetting() ?? [], $dayStart);
        }
    }
    // 3. Weekly schedule
    $schedule = $this->scheduleRepo->findByDoctor($doctor);
    if ($schedule === null) return [];
    // ...
}
```

### `appointment-slots` controller — بدون چک window

```php
#[Route('/api/v1/appointment-slots', methods: ['GET'])]
public function slots(Request $request): JsonResponse
{
    $doctorUuid = trim($request->query->get('doctor_uuid', ''));
    $date       = trim($request->query->get('date', ''));
    $doctor = $this->doctorRepo->findByUuid($doctorUuid);
    // ... validation ...
    $sessions = $this->slotCalculator->getAllSlotsWithAvailability($doctor, $date);
    return $this->success([...]);
}
```

### `DoctorDetailPage.tsx` — schedule از قبل ذخیره می‌شود

```tsx
const saveMut = useMutation({
  mutationFn: () => existing
    ? api.patch(`/api/v1/appointment-settings/weekly-schedule/${doctorUuid}`, { schedule: scheduleMap })
    : api.post('/api/v1/appointment-settings/weekly-schedule', { doctor_uuid: doctorUuid, schedule: scheduleMap }),
});
```

## وظایف

اجرای مرحله‌به‌مرحله؛ بعد از هر قابلیت تست (PHP lint + migrate در صورت نیاز + admin build) و سپس commit جدا.

### ۱. مدل booking window در `WeeklySchedule.setting`

- ساختار جدید زیر کلید رزروشده `"meta"` (یا `"settings"`) در `setting`:

```json
{
  "0": { "sessions": [...] },
  "...": {},
  "meta": {
    "online_booking_enabled": true,
    "booking_window_value": 2,
    "booking_window_unit": "month"
  }
}
```

- `booking_window_unit`: یکی از `"week"` یا `"month"`. `booking_window_value`: عدد مثبت (مثلاً ۲ هفته یا ۲ ماه).
- پیش‌فرض وقتی `meta` نیست: نوبت‌دهی آنلاین **روشن**، بازه‌ی پیش‌فرض (مثلاً ۱ ماه) — این پیش‌فرض را به‌صورت ثابت در سرویس تعریف کن و در پاسخ‌ها هم برگردان تا فرانت بداند.
- weekly-schedule controller (POST/PATCH) باید فیلدهای `meta` را در صورت ارسال بپذیرد و ذخیره کند (validation: `unit ∈ {week, month}`، `value ≥ 1`). کلیدهای عددی روز دست‌نخورده بمانند.

### ۲. اعمال window در `SlotCalculatorService`

- یک متد private مثل `isWithinBookingWindow(Doctor $doctor, string $date): bool` بساز:
  - `meta` را از `schedule->getSetting()['meta']` بخوان (با fallback پیش‌فرض).
  - اگر `online_booking_enabled === false` → خارج از بازه (false).
  - سقف را با `strtotime("+{$value} {$unit}", today)` حساب کن؛ اگر `dayStart` بعد از سقف بود → false. تاریخ‌های گذشته هم false (همین حالا فرانت گذشته را می‌بندد ولی backend هم باید مقاوم باشد).
- در `buildAllSessions` **قبل از** بازگشت اسلات‌ها این چک را اعمال کن: اگر خارج از بازه → `return []`.
- توجه: تاریخ‌های یونیکس صحیح (نه DateTime object).

### ۳. endpoint عمومی month-availability

- متد جدید در `AppointmentSettingsController` با route:
  `GET /api/v1/appointment-settings/month-availability/{doctorUuid}` — **Permission: PUBLIC** (مثل `available-locations`).
- Query params: `year` و `month` (عددی). چون تقویم سایت شمسی است، **هر دو حالت را بپذیر**: اگر `calendar=jalali` آمد ورودی را شمسی تفسیر کن، در غیر این صورت میلادی. (یا ساده‌تر: همیشه میلادی بگیر و در پرامپت فرانت تبدیل شمسی→میلادی انجام شود — یکی را انتخاب کن و دقیق مستند کن.)
- برای هر روز ماه، با همان منطق `SlotCalculatorService` (holiday/override/window/weekly) تعیین کن آیا روز اسلات دارد یا نه. **برای پرهیز از سنگینی، یک متد سبک در سرویس اضافه کن** مثل `hasAnyAvailability(Doctor, string $date): bool` که فقط وجود session را چک کند (نه ساخت کامل اسلات‌ها).
- پاسخ:

```json
{
  "success": true,
  "data": {
    "year": 2026,
    "month": 6,
    "disabled_dates": ["2026-06-16", "2026-06-17", "2026-06-20"],
    "enabled_dates": ["2026-06-21", "2026-06-22"],
    "online_booking_enabled": true,
    "booking_window": { "value": 2, "unit": "month" }
  }
}
```

> `disabled_dates`: روزهایی که تعطیل/خارج‌از‌بازه/بدون session‌اند (غیرقابل‌انتخاب). فرمت `Y-m-d`. فرانت این‌ها را روی تقویم خاکستری می‌کند.

### ۴. UI در پنل ادمین (`DoctorDetailPage.tsx`)

- در بخش تنظیمات برنامه‌ی هفتگی، یک کارت/سکشن «نوبت‌دهی آنلاین» اضافه کن:
  - یک toggle برای `online_booking_enabled`.
  - یک input عددی + select واحد (`هفته`/`ماه`) برای بازه.
- مقدار اولیه را از پاسخ `weekly-schedule` (`data?.data?.data?.meta`) بخوان (double-nested).
- در `saveMut` همان weekly-schedule، فیلد `meta` را هم به payload اضافه کن (`{ schedule: scheduleMap, meta: {...} }` یا داخل خود `scheduleMap` با کلید `meta`).
- از کلاس‌های CSS موجود همان صفحه استفاده کن؛ RTL؛ بدون کتابخانه‌ی جدید.

## نکات مهم

- **بدون migration:** booking window در `WeeklySchedule.setting` JSON می‌رود. اگر ترجیح می‌دهی فیلد مجزا در DB باشد، **متوقف شو و بپرس** (نیاز به migration دارد).
- همه‌ی controllerها از `BaseController`؛ پاسخ‌ها `$this->success()`/`$this->error()`. خطاها با `AppException(ErrorCodes::ERR_XXX, ...)`.
- `appointment-slots` تک‌روزه هم باید window را respect کند (وگرنه بیمار می‌تواند تاریخ خارج‌از‌بازه را مستقیم صدا بزند و اسلات بگیرد).
- `month-availability` باید **public** باشد (تقویم سایت قبل از لاگین لود می‌شود) — مثل `available-locations`.
- پاسخ weekly-schedule **double-nested** است (`data.data.data`) — UI ادمین با همین الگو می‌خواند.
- اولویت منطق دست‌نخورده بماند: holiday > override > window > weekly. window نباید روی اسلات‌های گذشته‌ی همین ماه تأثیر اشتباه بگذارد.
- بعد از تغییر API، **هم `docs/api/appointment-settings.md` و هم (در صورت تغییر رفتار) `docs/api/appointment.md`** را در همین session به‌روز کن: endpoint جدید با method/path/permission/query/response، و فیلدهای `meta`.
- تست: `ddev exec php -l ...` روی فایل‌های PHP؛ `ddev exec php bin/console debug:router | grep month-availability`؛ یک‌بار واقعی `curl` روی `month-availability` با پزشک تست `4a0594b1-008b-478a-a593-259b95d8c2dd`؛ و `ddev exec yarn dev` برای build پنل ادمین. سپس commit.