<?php

/**
 * READ-ONLY — امضای منجمد متدهای عمومی SlotCalculatorService.
 *
 * افزودن پارامتر **اختیاری** جدید مجاز است و باید یک بار همین‌جا ثبت شود؛ تغییر نام،
 * تغییر نوع، تغییر ترتیب یا حذف پارامتر موجود ممنوع است.
 * رجوع: docs/new_feture/taskes/_shared/red-lines.md
 *
 * تاریخچهٔ به‌روزرسانی‌های مجاز:
 *   - تسک ۰۰ / قابلیت ۴: `getServiceStartTimes(..., ?int $excludeAppointmentId = null)`.
 *     پارامتر اختیاری با پیش‌فرض null و فقط روی مسیر **سرویسی**؛ هیچ فراخوانیِ موجودی
 *     رفتارش عوض نشد. لازم بود چون بدون آن، نوبتِ در حال جابه‌جایی خودش را اشغال می‌بیند
 *     و زمان فعلی‌اش در فهرست زمان‌های ممکن نمی‌آید.
 */
return [
    'explainEmptyDay' => [
        'returns' => '?string',
        'params'  => [
            'doctor'        => 'App\Doctor\Entity\Doctor',
            'date'          => 'string',
            'clinic'        => '?App\Clinic\Entity\Clinic = NULL',
            'forManagement' => 'bool = false',
        ],
    ],
    'findNextAvailableStart' => [
        'returns' => '?int',
        'params'  => [
            'doctor'        => 'App\Doctor\Entity\Doctor',
            'clinic'        => '?App\Clinic\Entity\Clinic = NULL',
            'daysAhead'     => 'int = 30',
            'forManagement' => 'bool = false',
        ],
    ],
    'getAllSlotsWithAvailability' => [
        'returns' => 'array',
        'params'  => [
            'doctor'        => 'App\Doctor\Entity\Doctor',
            'date'          => 'string',
            'clinic'        => '?App\Clinic\Entity\Clinic = NULL',
            'forManagement' => 'bool = false',
        ],
    ],
    'getAvailableSlots' => [
        'returns' => 'array',
        'params'  => [
            'doctor'        => 'App\Doctor\Entity\Doctor',
            'date'          => 'string',
            'clinic'        => '?App\Clinic\Entity\Clinic = NULL',
            'forManagement' => 'bool = false',
        ],
    ],
    'getServiceStartTimes' => [
        'returns' => 'array',
        'params'  => [
            'doctor'          => 'App\Doctor\Entity\Doctor',
            'date'            => 'string',
            'durationMinutes' => 'int',
            'clinic'          => '?App\Clinic\Entity\Clinic = NULL',
            'forManagement'   => 'bool = false',
            // تسک ۰۰ / قابلیت ۴ — تنها افزودهٔ مجاز؛ رجوع به docblock بالا
            'excludeAppointmentId' => '?int = NULL',
        ],
    ],
    'hasAnyAvailability' => [
        'returns' => 'bool',
        'params'  => [
            'doctor'        => 'App\Doctor\Entity\Doctor',
            'date'          => 'string',
            'clinic'        => '?App\Clinic\Entity\Clinic = NULL',
            'forManagement' => 'bool = false',
        ],
    ],
    'resolveSlotLocationId' => [
        'returns' => '?int',
        'params'  => [
            'doctor'        => 'App\Doctor\Entity\Doctor',
            'slotStart'     => 'int',
            'clinic'        => '?App\Clinic\Entity\Clinic = NULL',
            'forManagement' => 'bool = false',
        ],
    ],
];