<?php

namespace App\Appointment\Availability\Picker;

use App\Resource\Entity\ClinicResource;

/**
 * ترتیبی که کاندیدهای یک نقش امتحان می‌شوند.
 *
 * استراتژی **انتخاب نمی‌کند، مرتب می‌کند**. تصمیم نهایی همچنان با موتور است، چون فقط
 * موتور می‌داند کدام منبع در این زمان جا دارد و کدام قبلاً برای نقش دیگری برداشته شده.
 * استراتژی‌ای که خودش انتخاب کند، مجبور است همان منطق را تکرار کند.
 */
interface ResourcePicker
{
    /** کلید پایدار — در تنظیمات محیط ذخیره می‌شود. */
    public static function code(): string;

    /** برچسب فارسی برای پنل. */
    public static function label(): string;

    /**
     * @param list<ClinicResource> $candidates
     * @return list<ClinicResource> همان مجموعه، با ترتیب تازه
     */
    public function order(array $candidates, PickContext $context): array;
}
