# نوبت‌دهی آنلاین منبع‌محور — اندپوینت‌های عمومی

## پروژه

`clinicpro` (Backend).

پرامپت همتا در سایت عمومی: `nobat724_front/.claude/prompt/public-resource-booking-ui.md`.
**اول این را اجرا کن، بعد آن را.** قرارداد API که اینجا ساخته می‌شود مصرف‌کنندهٔ مستقیم دارد و
تغییرش در build سایت خطا نمی‌دهد.

## زمینه

منبع (`ClinicResource`) هر چیزی است که ممکن است اشغال باشد: پزشک، اپراتور، دستگاه، اتاق، یونیت.
هر منبع تقویم خودش را دارد و سرویس‌هایی که ارائه می‌دهد در `resource_service_offerings` ثبت شده‌اند
(`ResourceServiceOffering`)، با مدت و قیمتِ اختصاصیِ همان جفتِ منبع↔سرویس.

روی `ServiceItem` یک توگل به نام `bookable` هست که در پنل با برچسب «نمایش در نوبت‌دهی آنلاین»
دیده می‌شود:

```php
// src/ClinicService/Entity/ServiceItem.php:107
/** نمایش این سرویس در نوبت‌دهی (پزشک ممکن است همهٔ سرویس‌ها را ارائه ندهد). */
#[ORM\Column(type: 'boolean', options: ['default' => false])]
private bool $bookable = false;
```

امروز این توگل فقط جریانِ **پزشک‌محورِ** سایت را تغذیه می‌کند
(`AppointmentController::bookableServices()` → `ServiceItemRepository::findBookableByEntity()`).
هیچ مسیر عمومی‌ای منابع را نمی‌بیند.

## مشکل / هدف

اسلات‌های منبع فقط از داخل پنل قابل خواندن‌اند:

```php
// src/Resource/Controller/ResourceBookingSlotController.php:26
#[IsGranted('IS_AUTHENTICATED_FULLY')]
class ResourceBookingSlotController extends BaseController
{
    use ResourcePermissionTrait;
    // هر اکشن با denyUnlessGrantedForBooking($user) گیت می‌شود
```

`ResourceContext::resource($user, $uuid)` هم منبع را در محیطِ کاربرِ احرازشده حل می‌کند، پس برای
بازدیدکنندهٔ ناشناسِ سایت اصلاً قابل استفاده نیست.

هدف: سه اندپوینت عمومیِ جدید تا سایت بتواند
۱) منابعِ قابلِ رزروِ یک پزشک را ببیند، ۲) وقت‌های خالیِ یک منبع برای سرویس‌های انتخاب‌شده را
بگیرد، ۳) روزهای فعالِ ماه را برای تقویم بگیرد.
به‌علاوه رفع یک ناسازگاریِ موجود در مسیر عمومیِ ثبت نوبت (وظیفهٔ ۴).

**گیتِ عمومی‌شدن دقیقاً همان توگل است:** منبع وقتی در سایت دیده می‌شود که دست‌کم یک
`ResourceServiceOffering` فعال به یک `ServiceItem` با `bookable = true` و `active = true` داشته باشد.

**تصمیم دامنه (تأییدشده):** روی صفحهٔ یک پزشک فقط منابعی می‌آیند که پزشکِ ناظرشان
(`supervisor`) همان پزشک است، یا خودشان پلِ همان پزشک‌اند (`doctor_id`). فهرست کلینیک‌محور
خارج از این تسک است.

## معیار پذیرش

- ✅ موفق:
  - `GET /api/v1/appointment-booking-resources/{doctorUuid}` بدون هیچ توکنی → ۲۰۰ با
    `{ success: true, data: { doctor_uuid, clinic_uuid, resources: [...] } }`؛ هر منبع فیلد
    `services[]` دارد و در آن فقط سرویس‌های `bookable=true` و `active=true` با
    `duration_minutes` و `price_rials`ِ حل‌شده از `ResourceServiceResolver` هستند.
  - `GET /api/v1/appointment-resource-slots?resource_uuid=..&date=..&service_item_uuids[]=..`
    بدون توکن → ۲۰۰ با `start_times[]` که هر عضوش `{start, end, start_time, end_time}` است، و
    `total_duration_minutes` برابرِ مجموعِ مدتِ حل‌شدهٔ همان منبع.
  - `GET /api/v1/appointment-resource-month-availability/{resourceUuid}?year=&month=&service_item_uuids[]=`
    بدون توکن → ۲۰۰ با `enabled_dates[]` و `disabled_dates[]` که مجموعشان همهٔ روزهای آن ماه است.
  - `POST /api/v1/appointment` با `resource_uuid` + `service_item_uuids[]` + یکی از
    `start_times`ِ بالا → ۲۰۱، و `slot_end` دقیقاً برابرِ `end`ِ همان start_time.
- ❌ خطا:
  - منبعی که هیچ سرویسِ `bookable` ندارد → در پاسخِ فهرست **نمی‌آید**؛ و
    `appointment-resource-slots` رویش → ۴۲۲ با کد `ERR_VALIDATION_001` و
    `field: service_item_uuids`.
  - سرویسی که `bookable=false` است ولی روی منبع offering فعال دارد → `resource-slots` → ۴۲۲
    (پیام: «این سرویس برای نوبت‌دهی آنلاین فعال نیست»). یعنی مسیر عمومی سخت‌گیرتر از پنل است.
  - `date` با فرمت نادرست → ۴۲۲ با `field: date`. `resource_uuid` ناموجود یا `active=false` →
    ۴۲۲ با `field: resource_uuid` (نه ۴۰۴؛ همان الگوی موجود در `AppointmentController`).
  - `POST /api/v1/appointment` روی بازه‌ای که منبع در آن پر است → ۴۰۹ با
    `field: resource_uuid` (رفتار موجودِ `ResourceOccupier`؛ نباید بشکند).
- ⚠️ مرزی:
  - پزشکی که هیچ منبعی ندارد → ۲۰۰ با `resources: []`، نه ۴۰۴.
  - منبعِ با `capacity > 1`: وقتی یک نوبت روی آن نشسته، همان بازه هنوز باید در `start_times` بیاید
    (ظرفیت هنوز پر نشده). `ResourceBookingSlotService::freeIntervals()` این را می‌داند؛ فقط با
    داده تست شود.
  - روزی که منبع شیفت ندارد → `start_times: []` و همان روز در `disabled_dates` ماه.
  - `service_item_uuids` خالی → ۴۲۲ با پیام «انتخاب حداقل یک سرویس الزامی است» (رفتار موجودِ
    `resolveDuration`).
  - آخرین روز ماه شمسی/میلادی: `month-availability` بر پایهٔ سال/ماهِ **میلادی** است — همان
    قرارداد `appointment-settings/month-availability` که سایت از قبل با آن کار می‌کند. تغییرش نده.

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

| فایل | نقش |
|------|-----|
| `src/Resource/Entity/ClinicResource.php` | منبع؛ `address`, `type`, `supervisor`, `doctor`, `capacity`, `active` |
| `src/Resource/Entity/ResourceServiceOffering.php` | جفتِ منبع↔سرویس با مدت/قیمت/`active` |
| `src/Resource/Repository/ClinicResourceRepository.php` | کوئری‌های منبع؛ متد جدید اینجا |
| `src/Resource/Repository/ResourceServiceOfferingRepository.php` | `findForResource`, `bookableResourceIds`, `activeResourceIdsFor` |
| `src/Resource/Service/ResourceBookingSlotService.php` | `resolveDuration`, `startTimes`, `freeIntervals`, `assertOffered` |
| `src/ClinicService/Service/ResourceServiceResolver.php` | زنجیرهٔ حلِ مدت و قیمت |
| `src/Resource/Controller/ResourceBookingSlotController.php` | نسخهٔ پنلیِ همین اسلات‌ها — الگوی مرجع |
| `src/Appointment/Controller/AppointmentController.php` | اندپوینت‌های عمومی موجود + `POST /api/v1/appointment` |
| `config/packages/security.yaml` | `access_control` |
| `docs/api/resource.md`، `docs/api/appointment.md` | مستندات |

## وضعیت فعلی

منبعِ حقیقتِ مدت و قیمت، این زنجیره است:

```php
// src/ClinicService/Service/ResourceServiceResolver.php:41
public function resolve(
    ClinicResource $resource,
    ServiceItem $item,
    DoctorAddress $address,
    ?ServiceItem $parentService = null,
): ResolvedServiceSpec
// ۱. منبع+گزینه → ۲. منبع+سرویس → ۳. شعبه → ۴. پیش‌فرض سرویس
```

و اسلات‌ها:

```php
// src/Resource/Service/ResourceBookingSlotService.php:87
public function startTimes(
    ClinicResource $resource,
    string $date,
    int $totalMinutes,
    ?int $excludeAppointmentId = null,
): array
```

مسیر عمومیِ ثبت نوبت، مدت را از calculatorِ پزشک‌محور می‌گیرد — حتی وقتی منبع دارد:

```php
// src/Appointment/Controller/AppointmentController.php:528-538
$duration = null;
if ($hasServices) {
    $duration = $this->serviceCalculator->calculate($doctor, $bookingClinic, $serviceUuids);
    $slotEnd  = $duration->endFor($slotStart);
}

if ($resource !== null) {
    [$bookingType, $bookingId] = EntityContext::forBooking($doctor, $bookingClinic)->toEntityPair();
    // ...
```

مسیر پنل همین را درست انجام می‌دهد و باید الگو باشد:

```php
// src/Appointment/Controller/MyAppointmentsController.php:188-197
if (!empty($serviceUuids) && !$isReserve && $resource !== null) {
    // نوبتِ منبع: مدت از زنجیرهٔ حلِ همان منبع می‌آید (هر دستگاه مدت خودش را
    // دارد) و گیتِ «این سرویس روی این منبع فعال است؟» جای `bookable` می‌نشیند.
    ['minutes' => $resourceMinutes, 'items' => $serviceItems] =
        $this->resourceSlots->resolveDuration($resource, $serviceUuids, $durationOverrides);
```

## وظایف

### ۱. کوئری منابعِ قابلِ رزروِ عمومی

در `src/Resource/Repository/ClinicResourceRepository.php` متد جدید:

```php
/**
 * منابعِ یک پزشک در یک محیط که در سایت عمومی قابل رزروند.
 *
 * سه شرط با هم: منبع فعال، دست‌کم یک offering فعال، و سرویسِ آن offering هم
 * `bookable` و هم `active`. توگلِ «نمایش در نوبت‌دهی آنلاین» تنها گیتِ عمومی‌شدن است؛
 * منبعی که سرویسِ روشنی ندارد اصلاً نباید در پاسخ دیده شود.
 *
 * @return ClinicResource[]
 */
public function findPublicBookableForDoctor(string $entityType, int $entityId, Doctor $doctor): array
{
    return $this->createQueryBuilder('r')
        ->join('r.type', 't')
        ->addSelect('t')
        ->join(ResourceServiceOffering::class, 'o', 'WITH', 'o.resource = r')
        ->join('o.serviceItem', 'i')
        ->where('r.entityType = :type')
        ->andWhere('r.entityId = :id')
        ->andWhere('r.active = true')
        ->andWhere('o.active = true')
        ->andWhere('i.bookable = true')
        ->andWhere('i.active = true')
        // فقط منابع همین پزشک: یا خودش پلِ پزشک است، یا پزشک ناظرش همین است.
        ->andWhere('r.doctor = :doctor OR r.supervisor = :doctor')
        ->setParameter('type', $entityType)
        ->setParameter('id', $entityId)
        ->setParameter('doctor', $doctor)
        ->distinct()
        ->orderBy('r.name', 'ASC')
        ->getQuery()
        ->getResult();
}
```

**نحوه تست:** یک unit/functional تست که سه سناریو بسازد — منبع با سرویسِ bookable (باید بیاید)،
منبع با سرویسِ `bookable=false` (نباید بیاید)، منبع با offering غیرفعال (نباید بیاید) — و منبعی
که ناظرش پزشک دیگری است (نباید بیاید).

### ۲. سرویسِ ساختِ payload عمومی

فایل جدید `src/Resource/Service/PublicResourceBookingService.php`.
کنترلر نازک می‌ماند؛ این کلاس تنها مسئولیتش «منبع → آرایهٔ عمومی» است (SRP).

```php
/**
 * نمای عمومیِ منبع برای سایت نوبت‌دهی.
 *
 * از نمای پنل جداست چون سؤالِ دیگری جواب می‌دهد: پنل همهٔ سرویس‌های منبع را
 * می‌خواهد، سایت فقط آن‌هایی را که مالک روشن کرده. ادغامشان یعنی یک `if ($public)`
 * در دلِ کد پنل و یک راهِ تازه برای نشتِ سرویسِ خاموش.
 */
final class PublicResourceBookingService
{
    public function __construct(
        private readonly ClinicResourceRepository          $resources,
        private readonly ResourceServiceOfferingRepository $offerings,
        private readonly ResourceServiceResolver           $resolver,
    ) {}

    /** @return array<int, array<string, mixed>> */
    public function resourcesFor(Doctor $doctor, ?Clinic $clinic): array;

    /**
     * سرویس‌های عمومیِ یک منبع — همان گیتِ فهرست، تا اسلات و فهرست از هم واگرا نشوند.
     *
     * @return array<int, array<string, mixed>>
     */
    public function publicServices(ClinicResource $resource): array;

    /** @throws AppException ۴۲۲ روی سرویسی که در سایت روشن نیست */
    public function assertPublicService(ClinicResource $resource, ServiceItem $item): void;
}
```

شکل هر منبع در پاسخ:

```php
[
    'uuid'            => $resource->getUuid(),
    'name'            => $resource->getName(),
    'type'            => ['code' => $type->getCode(), 'name' => $type->getName()],
    'capacity'        => $resource->getCapacity(),
    'location'        => [
        'uuid'    => $address->getUuid(),
        'title'   => $address->getName() ?: 'مطب شخصی',
        'address' => $address->getAddress(),
    ],
    'supervisor'      => ['uuid' => ..., 'full_name' => ...] | null,
    'services'        => [
        [
            'uuid'             => $item->getUuid(),
            'name'             => $item->getName(),
            'duration_minutes' => $spec->durationMinutes,   // از resolver، نه از پیش‌فرض خام
            'price_rials'      => $spec->priceRials,
            'service_section'  => ['uuid' => ..., 'name' => ...],
        ],
    ],
]
```

نکتهٔ کارایی: `publicServices()` نباید به ازای هر سرویس یک `findOneFor` جدا بزند وقتی
`findForResource($resource)` همه را یک‌جا می‌دهد. offeringهای همان منبع را یک‌بار بخوان و
سرویس‌های `bookable && active` را از رویش فیلتر کن؛ `resolver->resolve()` را فقط برای همان‌ها صدا بزن.

**نحوه تست:** `ddev exec php bin/phpunit` روی یک تستِ سرویس با دو سرویس (یکی روشن، یکی خاموش)
و یک offering با `duration_minutes` اختصاصی؛ ادعا: خروجی یک عضو دارد و مدتش عددِ offering است،
نه `solo_duration_minutes`ِ سرویس.

### ۳. کنترلر عمومی + مسیرها

فایل جدید `src/Resource/Controller/PublicResourceBookingController.php` — `extends BaseController`،
**بدون** `IsGranted` و بدون `ResourcePermissionTrait`.

```php
/**
 * نوبت‌دهی منبع‌محور برای سایت عمومی.
 *
 * از {@see ResourceBookingSlotController} جداست و نه یک پرچمِ `public` روی آن: آنجا منبع
 * از محیطِ کاربرِ احرازشده حل می‌شود (`ResourceContext::resource($user, $uuid)`) و اینجا
 * کاربری وجود ندارد. یک کنترلر با دو مدلِ اعتماد، همان‌جایی است که نشت اتفاق می‌افتد.
 */
#[OA\Tag(name: 'Resource')]
class PublicResourceBookingController extends BaseController
{
    // GET /api/v1/appointment-booking-resources/{doctorUuid}?clinic_uuid=
    // GET /api/v1/appointment-resource-slots?resource_uuid=&date=&service_item_uuids[]=
    // GET /api/v1/appointment-resource-month-availability/{resourceUuid}?year=&month=&service_item_uuids[]=
}
```

قواعدی که باید رعایت شوند:

- محیط با همان الگوی موجود حل شود:
  `[$type, $id] = EntityContext::forBooking($doctor, $clinic)->toEntityPair();`
  و `$clinic` از `AppointmentController::bookingClinic()` — اگر متد `private` است، منطقش را
  کپی نکن؛ یا در یک سرویس مشترک بگذار یا از `BookingContextResolver` استفاده کن. تصمیم و دلیلش
  را در کامنت بنویس.
- در `resource-slots` و `month-availability` منبع با `ClinicResourceRepository::findByUuid()`
  گرفته می‌شود و **باید** بررسی شود: `isActive()` و اینکه دست‌کم یک سرویس عمومی دارد. منبعِ
  ناموجود یا خاموش → ۴۲۲ با `field: resource_uuid`.
- برای هر uuid در `service_item_uuids` اول `assertPublicService()` صدا زده شود (گیتِ `bookable`)،
  بعد `ResourceBookingSlotService::resolveDuration()` (گیتِ offering + مدت). ترتیب مهم است:
  پیامِ «در سایت فعال نیست» گویاتر از «این منبع این سرویس را ارائه نمی‌دهد» است.
- `durations[]` که نسخهٔ پنلی می‌پذیرد **در مسیر عمومی پذیرفته نشود** — override مدت ابزار منشی
  است؛ در دست بازدیدکننده یعنی ساختن ظرفیتِ جعلی. یعنی `resolveDuration($resource, $uuids)`
  بدون آرگومان سوم.
- `month-availability` روی روزهای ماه حلقه بزند و برای هر روز `startTimes(...) !== []` را
  بسنجد — همان الگوی `AppointmentController::monthAvailability()` که با `hasAnyAvailability`
  کار می‌کند. اگر روی ۳۱ روز کند بود، به‌جای `startTimes` از `freeIntervals` استفاده کن و فقط
  وجودِ یک بازهٔ به‌اندازهٔ کافی بلند را چک کن.

سپس در `config/packages/security.yaml`، بخش `access_control`، کنار همتاهای موجود:

```yaml
- { path: ^/api/v1/appointment-booking-resources/,           roles: PUBLIC_ACCESS }
- { path: ^/api/v1/appointment-resource-slots,               roles: PUBLIC_ACCESS }
- { path: ^/api/v1/appointment-resource-month-availability/, roles: PUBLIC_ACCESS }
```

مسیرها روی firewallِ `api` می‌مانند (به `public_endpoints` **اضافه نشوند**) — دقیقاً به همان
دلیلی که در کامنت بالای `public_endpoints` نوشته شده: توکن اختیاری بماند.

**نحوه تست:**

```bash
ddev exec php bin/console debug:router | grep resource
# سه مسیر جدید باید دیده شوند

curl -s "https://clinic-pro.ddev.site/api/v1/appointment-booking-resources/<DOCTOR_UUID>" | jq
curl -s "https://clinic-pro.ddev.site/api/v1/appointment-resource-slots?resource_uuid=<R>&date=2026-08-15&service_item_uuids[]=<S>" | jq
curl -s "https://clinic-pro.ddev.site/api/v1/appointment-resource-month-availability/<R>?year=2026&month=8&service_item_uuids[]=<S>" | jq
```

هر سه بدون هدر `Authorization` و همه باید ۲۰۰ بدهند. سپس همان `curl`ها را روی سرویسی بزن که
`bookable` را در پنل خاموش کرده‌ای و ۴۲۲ بگیر.
اکانت تست پنل برای ساختن داده: `09390039833` / `09390039833`.

### ۴. رفعِ مدتِ نوبتِ منبع‌دار در مسیر عمومی

در `src/Appointment/Controller/AppointmentController.php::book()`، شاخهٔ محاسبهٔ مدت باید مثل
مسیر پنل، وقتی منبع هست از `ResourceBookingSlotService::resolveDuration()` استفاده کند:

```php
$duration = null;
$resourceItems = [];

if ($hasServices && $resource !== null) {
    // مدت از زنجیرهٔ حلِ همان منبع می‌آید، وگرنه `slot_end` با start_timesِ
    // appointment-resource-slots یکی نمی‌شود و بیمار وقتی را می‌گیرد که سرور
    // جای دیگری آزاد حساب کرده بود.
    foreach ($serviceUuids as $u) { /* assertPublicService(...) */ }
    ['minutes' => $minutes, 'items' => $resourceItems] =
        $this->resourceSlots->resolveDuration($resource, $serviceUuids);
    $slotEnd = $slotStart + $minutes * 60;
} elseif ($hasServices) {
    $duration = $this->serviceCalculator->calculate($doctor, $bookingClinic, $serviceUuids);
    $slotEnd  = $duration->endFor($slotStart);
}
```

سه قید:

- ترازِ سطلِ اشغال (`OccupancyBucket::alignWindow`) در خط ۵۱۵ **قبل از** محاسبهٔ مدت اجرا
  می‌شود و در آنجا `$slotEnd` هنوز مقدارِ کلاینت است. بعد از بازنویسیِ `$slotEnd`، تراز باید
  دوباره اعمال شود؛ وگرنه بازهٔ نهایی ناتراز می‌ماند.
- ذخیرهٔ سرویس‌ها روی نوبت (خط ~۶۰۵، `replaceServiceItems` + `setServiceDuration`) نباید بشکند.
  در شاخهٔ منبع، `$duration` تهی است، پس این بلوک باید `items` و `minutes`ِ منبع را هم بپذیرد.
- بررسیِ موجودِ «این منبع این سرویس را ارائه می‌دهد؟» (خط ۵۵۸ با `hasAnyFor`/`activeResourceIdsFor`)
  حالا با `resolveDuration` تکراری می‌شود. یکی را نگه دار — `resolveDuration` سخت‌گیرتر است چون
  `offering.active` را هم می‌بیند. حذفِ کدِ تکراری را در همان commit توضیح بده.

**نحوه تست:** یک تست functional که:
۱) از `appointment-resource-slots` یک `start_time` بگیرد،
۲) با همان `start` و همان `service_item_uuids` روی `POST /api/v1/appointment` بزند،
۳) ادعا کند `slot_end` پاسخ برابر `end`ِ همان start_time است.
قبل از این تغییر باید قرمز شود.

### ۵. مستندات

- `docs/api/resource.md`: سه اندپوینت عمومی جدید با نمونهٔ درخواست/پاسخ و جدول خطاها.
- `docs/api/appointment.md`: رفتار `resource_uuid` در `POST /api/v1/appointment` — که مدت از
  منبع می‌آید و در مسیر عمومی سرویس باید `bookable` باشد.
- اگر فایل `docs/api/appointment-booking.md` جریان عمومی را توصیف می‌کند، مرحلهٔ منبع‌محور را
  هم آنجا اضافه کن.

## نکات مهم

- **گیتِ عمومی یک جا تعریف شود.** «سرویس در سایت دیده می‌شود» = `bookable && active` + offering
  فعال. این شرط در سه جا لازم است (فهرست، اسلات، ثبت نوبت). یک متد در
  `PublicResourceBookingService` و صدا زدنش از هر سه — نه سه‌بار نوشتنِ همان `if`.
- **جداسازی محیط:** منبع با uuid از بیرون می‌آید و `TenantFilter` پوششش نمی‌دهد
  (`ResourceServiceOffering` فرزندِ aggregate است). در هر سه اندپوینت، تطابقِ
  `(entity_type, entity_id)`ِ منبع با محیطِ رزروِ همان پزشک/کلینیک باید صریح بررسی شود — همان
  کاری که `AppointmentController` در خط ۵۴۹ می‌کند.
- **fail-safe عمومی:** پارامتر `management=1` در این کنترلر معنا ندارد و پیاده نشود. اگر روزی
  پنل بخواهد همین دید را داشته باشد، مسیر پنلیِ خودش را دارد.
- **`durations[]` در مسیر عمومی ممنوع** — دلیلش بالا آمده.
- ظرفیت و اشغال را خودت حساب نکن؛ `ResourceBookingSlotService` هر دو منبعِ اشغال را می‌بیند
  (`appointments.resource_id` و `resource_occupancy`). دور زدنش یعنی نوبتِ نامرئی.
- تاریخ‌ها Unix timestamp صحیح‌اند؛ `start_time`/`end_time` رشتهٔ `H:i` به وقتِ محلیِ شعبهٔ منبع
  است (`ResourceBookingSlotService::dayStart()` این را از `address->getTimezone()` می‌گیرد).
- **مصرف‌کنندهٔ cross-repo:** این قرارداد را `nobat724_front/services/response.js` مصرف می‌کند.
  هر تغییر در نام فیلدها بعد از این، در build سایت خطا **نمی‌دهد** — پس شکل پاسخ را قبل از
  merge نهایی کن.
