<?php

namespace Kylin\Core\Enums;

use Kylin\Core\Contracts\KylinErrorCodeInterface;

/**
 * 核心错误码枚举
 *
 * 定义核心包中各模块的错误码，每个错误码绑定 HTTP 状态码。
 * 遵循 Kylin 错误码规范：{模块}-{类型}-{序号}
 *
 * 错误码分类：
 *  - SYS：系统级错误（500/503）
 *  - VAL：参数校验错误（422）
 *  - AUTH：认证错误（401）
 *  - PERM：权限错误（403）
 *
 * 实现 KylinErrorCodeInterface 接口，确保所有错误码具备
 * value()、message()、httpStatus() 三个方法。
 */
enum CoreErrorCode: string implements KylinErrorCodeInterface
{
    /** 操作成功 */
    case Success = 'SUCCESS';
    /** 未知系统错误（HTTP 500） */
    case UnknownError = 'CORE-SYS-001';
    /** 请求参数验证失败（HTTP 422） */
    case ValidationError = 'CORE-VAL-001';
    /** 请求的资源不存在（HTTP 404） */
    case NotFound = 'CORE-SYS-002';
    /** 无权执行此操作（HTTP 403） */
    case Forbidden = 'CORE-PERM-001';
    /** 未认证或认证已过期（HTTP 401） */
    case Unauthorized = 'CORE-AUTH-001';
    /** 请求过于频繁（HTTP 429） */
    case RateLimited = 'CORE-SYS-003';
    /** 服务器内部错误（HTTP 500） */
    case ServerError = 'CORE-SYS-004';
    /** 系统维护中（HTTP 503） */
    case Maintenance = 'CORE-SYS-005';

    /** @return string 错误码字符串值 */
    public function value(): string
    {
        return $this->value;
    }

    /** @return string 中文错误描述 */
    public function message(): string
    {
        return match ($this) {
            self::Success => '操作成功',
            self::UnknownError => '未知系统错误',
            self::ValidationError => '请求参数验证失败',
            self::NotFound => '请求的资源不存在',
            self::Forbidden => '无权执行此操作',
            self::Unauthorized => '未认证或认证已过期',
            self::RateLimited => '请求过于频繁，请稍后再试',
            self::ServerError => '服务器内部错误',
            self::Maintenance => '系统维护中',
        };
    }

    /** @return int HTTP 状态码 */
    public function httpStatus(): int
    {
        return match ($this) {
            self::Success => 200,
            self::UnknownError => 500,
            self::ValidationError => 422,
            self::NotFound => 404,
            self::Forbidden => 403,
            self::Unauthorized => 401,
            self::RateLimited => 429,
            self::ServerError => 500,
            self::Maintenance => 503,
        };
    }
}
