<?php

namespace App\Enum\Dsar;

/**
 * Canonical definition of the dsars.status values plus the various status
 * "sets" used across the app (manual dropdowns, the inbox triage page, the AI
 * auto-status guard, open/terminal worklist queries and reports).
 *
 * IMPORTANT: this is a helper / single source of truth — the dsars.status
 * column is NOT cast to this enum. Many call sites compare the status as a raw
 * string (e.g. `$dsar->status === 'completed'`, `ucwords($dsar->status)`), so
 * the helper methods accept and return plain strings to interoperate with them.
 */
enum DsarStatus: string
{
    case Draft               = 'draft';
    case Approved            = 'approved';
    case NeedsPosting        = 'needs posting';
    case Failed              = 'failed';
    case Sent                = 'sent';
    case Completed           = 'completed';
    case Acknowledged        = 'acknowledged';
    case Clarified           = 'clarified';
    case FurtherInfoRequired = 'further info required';
    case NoRecords           = 'no records';
    case Relevant            = 'relevant';
    case NotRelevant         = 'not relevant';

    /** Human-friendly label for a raw status value. */
    public static function label(string $status): string
    {
        return match ($status) {
            'needs posting'         => 'Needs Posting',
            'further info required' => 'Further Info Required',
            'no records'            => 'No Records',
            'not relevant'          => 'Not Relevant',
            default                 => ucwords($status),
        };
    }

    /** Bootstrap badge class for a raw status value. */
    public static function badgeFor(string $status): string
    {
        return match ($status) {
            'completed', 'relevant'         => 'bg-success',
            'approved' , 'sent',            => 'bg-primary',
            'acknowledged', 'clarified'     => 'bg-info',
            'needs posting',
            'further info required'         => 'bg-warning text-dark',
            'draft', 'no records',
            'not relevant'                  => 'bg-secondary',
            'failed'                        => 'bg-danger',
            default                         => 'bg-info text-dark',
        };
    }

    /** Statuses a user may set manually on the DSAR view page. */
    public static function manuallySelectable(): array
    {
        return [
            'sent', 'completed',
            'acknowledged', 'clarified', 'further info required',
            'no records',
        ];
    }

    /**
     * Outcome-focused statuses a user may set from the inbox triage page on a
     * matched DSAR. Deliberately narrower than manuallySelectable() — a triager
     * shouldn't reset lifecycle states (draft/approved/sent/needs posting) here.
     */
    public static function triageSelectable(): array
    {
        return [
            'acknowledged', 'further info required', 'clarified',
            'completed', 'no records', 'relevant', 'not relevant',
        ];
    }

    /**
     * Statuses an inbound classification is allowed to auto-advance FROM.
     * Post-send and non-terminal only, so the AI never overwrites a terminal
     * status or touches a DSAR that has not been sent yet.
     */
    public static function autoFromStates(): array
    {
        return ['sent', 'acknowledged', 'further info required', 'clarified'];
    }

    /**
     * Terminal statuses — the DSAR has reached a disposition.
     * (relevant / not relevant treatment here is provisional, pending the
     * later relevance-review work.)
     */
    public static function terminal(): array
    {
        return ['completed', 'no records', 'relevant', 'not relevant'];
    }

    /**
     * Pre-send statuses — the DSAR has not yet gone out to the institution.
     * 'approved' is treated like 'draft': still being prepared, not yet sent, so
     * it is never "open"/outstanding, never appears in worklists, and is excluded
     * from the DSAR reports.
     */
    public static function preSend(): array
    {
        return ['draft', 'approved'];
    }

    /**
     * Statuses excluded from "open DSAR" queries (worklists + AI matcher):
     * pre-send (draft, approved) plus everything terminal.
     */
    public static function excludedFromOpen(): array
    {
        return array_merge(self::preSend(), self::terminal());
    }

    /** In-flight statuses counted as "outstanding" in DSAR reports (sent, awaiting a response). */
    public static function outstanding(): array
    {
        return ['sent', 'needs posting', 'acknowledged', 'clarified', 'further info required'];
    }

    /**
     * Statuses indicating the institution has come back to us in some form.
     * The denominator for the Response Types breakdown on the DSAR report.
     * Excludes 'failed' — that is a send failure, not a response — along with
     * the pre-response lifecycle states (draft, approved, sent, needs posting).
     */
    public static function responded(): array
    {
        return [
            'acknowledged', 'clarified', 'further info required',
            'completed', 'no records', 'relevant', 'not relevant',
        ];
    }
}
