ladill-care/app/Services/Care/Workflow/WorkflowQueueGate.php

<?php

namespace App\Services\Care\Workflow;

use App\Models\Organization;
use App\Models\Visit;
use App\Services\Care\CareFeatures;
use App\Services\Care\CareQueueContexts;

/**
 * Single boundary for deciding whether a visit may be exposed to a Queue
 * service line. Every direct issue and background backfill passes through it.
 */
class WorkflowQueueGate
{
    public function __construct(
        protected CareFeatures $features,
        protected WorkflowEngine $engine,
    ) {}

    public function enabled(Organization $organization): bool
    {
        return $this->features->enabled($organization, CareFeatures::WORKFLOW_ENGINE);
    }

    public function canRelease(
        Organization $organization,
        ?Visit $visit,
        string $queueContext,
    ): bool {
        if (! $this->enabled($organization) || $visit === null) {
            return true;
        }

        $advance = $this->engine->currentAdvance($visit)
            ? $this->engine->refreshGate($visit)
            : $this->engine->start($visit);
        $stage = $advance?->stage;

        // An enabled org without a materialized workflow keeps legacy behavior.
        if ($stage === null) {
            return true;
        }

        if (! $this->contextsMatch($stage->queue_context, $stage->type, $queueContext)) {
            return false;
        }

        if (! $this->features->enabled($organization, CareFeatures::FINANCIAL_GATES)) {
            return true;
        }

        return $this->engine->isQueueReleasable($visit);
    }

    protected function contextsMatch(?string $stageContext, string $stageType, string $queueContext): bool
    {
        if ($stageContext === $queueContext) {
            return true;
        }

        // Specialty appointments still fulfill a consultation workflow stage.
        return $stageType === 'consultation'
            && CareQueueContexts::isSpecialty($queueContext)
            && $stageContext === CareQueueContexts::CONSULTATION;
    }
}