ladill-care/app/Services/Care/Ophthalmology/OphthalmologyWorkflowService.php

<?php

namespace App\Services\Care\Ophthalmology;

/**
 * Map eye-care clinical progress onto ophthalmology visit stages.
 */
class OphthalmologyWorkflowService
{
    public const STAGE_CHECK_IN = 'check_in';

    public const STAGE_HISTORY = 'history';

    public const STAGE_REFRACTION = 'refraction';

    public const STAGE_EXAM = 'exam';

    public const STAGE_INVESTIGATION = 'investigation';

    public const STAGE_PLAN = 'plan';

    public const STAGE_TREATMENT = 'treatment';

    public const STAGE_COMPLETED = 'completed';

    /**
     * Suggested stage after a refraction / VA payload is saved.
     *
     * @param  array<string, mixed>  $payload
     */
    public function stageFromRefraction(array $payload): string
    {
        $vaOd = trim((string) ($payload['va_od'] ?? ''));
        $vaOs = trim((string) ($payload['va_os'] ?? ''));

        if ($vaOd !== '' || $vaOs !== '') {
            return self::STAGE_REFRACTION;
        }

        return self::STAGE_HISTORY;
    }

    /**
     * Suggested stage after an eye exam payload is saved.
     *
     * @param  array<string, mixed>  $payload
     */
    public function stageFromExam(array $payload): string
    {
        $findings = strtolower((string) ($payload['findings'] ?? ''));
        if (str_contains($findings, 'oct')
            || str_contains($findings, 'field')
            || str_contains($findings, 'imaging')
            || str_contains($findings, 'investigate')) {
            return self::STAGE_INVESTIGATION;
        }

        return self::STAGE_EXAM;
    }

    /**
     * Suggested stage after a diagnosis/plan payload is saved.
     *
     * @param  array<string, mixed>  $payload
     */
    public function stageFromPlan(array $payload): string
    {
        if (! empty($payload['procedure_planned'])) {
            return self::STAGE_TREATMENT;
        }

        return self::STAGE_PLAN;
    }

    /**
     * Whether a procedure payload should close the visit episode.
     *
     * @param  array<string, mixed>  $payload
     */
    public function shouldCompleteVisit(array $payload): bool
    {
        $outcome = strtolower((string) ($payload['outcome'] ?? ''));

        return str_contains($outcome, 'completed');
    }

    /**
     * Default stage progression for action buttons.
     *
     * @return array<string, array{next: string, label: string}>
     */
    public function stageFlow(): array
    {
        return [
            self::STAGE_CHECK_IN => ['next' => self::STAGE_HISTORY, 'label' => 'Start history'],
            self::STAGE_HISTORY => ['next' => self::STAGE_REFRACTION, 'label' => 'Move to VA / refraction'],
            self::STAGE_REFRACTION => ['next' => self::STAGE_EXAM, 'label' => 'Move to examination'],
            self::STAGE_EXAM => ['next' => self::STAGE_INVESTIGATION, 'label' => 'Move to investigations'],
            self::STAGE_INVESTIGATION => ['next' => self::STAGE_PLAN, 'label' => 'Move to diagnosis & plan'],
            self::STAGE_PLAN => ['next' => self::STAGE_TREATMENT, 'label' => 'Move to treatment'],
            self::STAGE_TREATMENT => ['next' => self::STAGE_COMPLETED, 'label' => 'Complete visit'],
            self::STAGE_COMPLETED => ['next' => self::STAGE_COMPLETED, 'label' => 'Completed'],
        ];
    }
}