<?php

declare(strict_types=1);

/**
 * 本文件属于 DBErp 进销存系统。
 *
 * 版权所有 © 2026 北京珑大钜商科技有限公司。保留所有权利。
 *
 * 未经官方授权，不得删除、篡改或隐藏本文件中的版权声明、产品标识与来源信息。
 * 商业授权、官方更新与技术支持服务，请以珑大官方支持中心记录为准。
 *
 * @link https://support.loongdom.cn
 * @see  https://www.dberp.com.cn
 */

namespace App\Services\SupportCenter;

use DomainException;

/**
 * CLI 系统更新命令前置校验失败（面向运维的中文说明）。
 */
final class HostSystemUpdateCliRunException extends DomainException
{
    public function __construct(
        private readonly string $userFacingMessage,
        private readonly string $errorCode,
        private readonly ?string $recoverySuggestion = null,
    ) {
        parent::__construct($userFacingMessage);
    }

    public function userFacingMessage(): string
    {
        return $this->userFacingMessage;
    }

    public function errorCode(): string
    {
        return $this->errorCode;
    }

    public function recoverySuggestion(): ?string
    {
        return $this->recoverySuggestion;
    }

    public static function executionNotFound(string $executionNo): self
    {
        return new self(
            userFacingMessage: (string) __('dberp.system_update_center.cli.errors.execution_not_found', [
                'execution_no' => $executionNo,
            ]),
            errorCode: 'cli_execution_not_found',
        );
    }

    public static function alreadyCompleted(string $executionNo): self
    {
        return new self(
            userFacingMessage: (string) __('dberp.system_update_center.cli.errors.already_completed', [
                'execution_no' => $executionNo,
            ]),
            errorCode: 'cli_execution_already_completed',
        );
    }

    public static function notRetryable(string $executionNo, string $statusLabel): self
    {
        return new self(
            userFacingMessage: (string) __('dberp.system_update_center.cli.errors.not_retryable', [
                'execution_no' => $executionNo,
                'status' => $statusLabel,
            ]),
            errorCode: 'cli_execution_not_retryable',
            recoverySuggestion: (string) __('dberp.system_update_center.cli.suggestions.not_retryable'),
        );
    }

    public static function anotherExecutionActive(string $activeExecutionNo): self
    {
        return new self(
            userFacingMessage: (string) __('dberp.system_update_center.cli.errors.another_execution_active', [
                'execution_no' => $activeExecutionNo,
            ]),
            errorCode: 'cli_another_execution_active',
            recoverySuggestion: (string) __('dberp.system_update_center.cli.suggestions.another_execution_active'),
        );
    }

    public static function manualInterventionRequired(string $executionNo, string $reason): self
    {
        return new self(
            userFacingMessage: (string) __('dberp.system_update_center.cli.errors.manual_intervention', [
                'execution_no' => $executionNo,
                'reason' => $reason,
            ]),
            errorCode: 'cli_manual_intervention_required',
            recoverySuggestion: (string) __('dberp.system_update_center.cli.suggestions.manual_intervention'),
        );
    }

    public static function entitlementDenied(string $reason): self
    {
        return new self(
            userFacingMessage: (string) __('dberp.system_update_center.cli.errors.entitlement_denied', [
                'reason' => $reason,
            ]),
            errorCode: 'cli_entitlement_denied',
        );
    }
}
