<?php

namespace App\Support;

/**
 * Marcar un entorno como pendiente de revisar, con una nota y un nivel.
 *
 * **La pregunta que no tenía sitio.** Alguien ve que un entorno está mal —un plugin
 * desalineado, un dominio que va a cambiar, un cliente que pidió algo— y no había dónde
 * anotarlo: o se quedaba en la cabeza de esa persona, o acababa en un chat que nadie vuelve
 * a leer. El panel sabía muchas cosas del parque y ninguna de ellas la había escrito un
 * humano.
 *
 * ## Una sola observación por entorno, no un historial
 *
 * Decisión de Producto del 2026-09-15. La pregunta que se hace es «¿qué tiene pendiente este
 * entorno **ahora**?», no «¿qué le ha pasado en dos años?». Una lista de notas viejas obliga
 * a leerlas todas para encontrar la que sigue viva, que es exactamente lo que hacía inútil
 * el registro de cortes antes de agruparlo.
 *
 * **El historial no se pierde**: abrir y cerrar una observación deja su apunte en Acciones
 * del panel, con quién, cuándo y el texto. Ahí es donde ya se consulta todo lo demás.
 *
 * ## Los tres niveles
 *
 * No son decoración: son el orden en que se atiende una lista de pendientes. Y son tres
 * porque con dos todo acaba siendo urgente y con cinco nadie sabe cuál elegir.
 */
final class RevisionDeEntorno
{
    /** Anotado, no corre prisa. Es la mayoría, y está bien que lo sea. */
    public const AVISO = 'aviso';

    /** Hay que mirarlo, pero nadie se ha quedado sin servicio. */
    public const IMPORTANTE = 'importante';

    /** El cliente está afectado ahora mismo. */
    public const URGENTE = 'urgente';

    /**
     * Cada nivel con lo que significa y cómo se pinta.
     *
     * El `cuando` no es un adorno: es lo que evita que todo se marque urgente. Un nivel sin
     * criterio escrito se elige por cómo de enfadado está quien anota.
     *
     * @var array<string, array{etiqueta: string, cuando: string, color: string, fondo: string, peso: int}>
     */
    public const NIVELES = [
        self::AVISO => [
            'etiqueta' => 'Aviso',
            'cuando' => 'Queda anotado y no corre prisa.',
            'color' => 'var(--text-muted)',
            'fondo' => 'var(--surface-alt)',
            'peso' => 1,
        ],
        self::IMPORTANTE => [
            'etiqueta' => 'Importante',
            'cuando' => 'Hay que mirarlo, pero nadie se ha quedado sin servicio.',
            'color' => 'var(--warning-500)',
            'fondo' => 'var(--warning-50)',
            'peso' => 2,
        ],
        self::URGENTE => [
            'etiqueta' => 'Urgente',
            'cuando' => 'El cliente está afectado ahora mismo.',
            'color' => 'var(--danger-500)',
            'fondo' => 'var(--danger-50)',
            'peso' => 3,
        ],
    ];

    /** Los niveles válidos, para validar lo que llega del navegador. */
    public static function niveles(): array
    {
        return array_keys(self::NIVELES);
    }

    /** La regla de validación, escrita una vez. */
    public static function regla(): string
    {
        return 'required|in:' . implode(',', self::niveles());
    }

    /**
     * La ficha de un nivel, o la del aviso si llega algo que no existe.
     *
     * No se devuelve null: quien pinta esto está en medio de una fila de una tabla, y un
     * nivel viejo o mal escrito no puede dejar la pantalla a medias.
     */
    public static function nivel(?string $clave): array
    {
        return self::NIVELES[$clave] ?? self::NIVELES[self::AVISO];
    }

    /** El nombre de un nivel, para textos y correos. */
    public static function etiqueta(?string $clave): string
    {
        return self::nivel($clave)['etiqueta'];
    }

    /**
     * El orden en que se atiende: lo urgente primero.
     *
     * Se expresa como un `CASE` de SQL para poder ordenar en la consulta y no en PHP: el
     * listado de entornos pagina, y ordenar después de paginar ordena la página, no la
     * lista.
     */
    public static function ordenSql(string $columna = 'review_level'): string
    {
        $casos = '';

        foreach (self::NIVELES as $clave => $ficha) {
            $casos .= " when '{$clave}' then {$ficha['peso']}";
        }

        return "case {$columna}{$casos} else 0 end";
    }
}