wpmind/includes/Failover/FailoverManager.php

<?php
/**
 * Failover Manager - 故障转移管理器
 *
 * 管理多个 Provider 的故障转移逻辑
 *
 * @package WPMind
 * @since 1.5.0
 */

declare(strict_types=1);

namespace WPMind\Failover;

class FailoverManager
{
    private static ?FailoverManager $instance = null;

    /** @var array<string, CircuitBreaker> */
    private array $circuitBreakers = [];

    /** @var array Provider 配置 */
    private array $providers = [];

    /**
     * 获取单例实例
     */
    public static function instance(): FailoverManager
    {
        if (self::$instance === null) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    private function __construct()
    {
        // 从 WPMind 获取已启用的 Provider
        if (function_exists('WPMind\\wpmind')) {
            $endpoints = \WPMind\wpmind()->get_custom_endpoints();
            foreach ($endpoints as $id => $config) {
                if (!empty($config['enabled']) && !empty($config['api_key'])) {
                    $this->providers[$id] = $config;
                    $this->circuitBreakers[$id] = new CircuitBreaker($id);
                }
            }
        }
    }

    /**
     * 选择最佳可用 Provider
     *
     * 优先级：
     * 1. 用户设置的首选 Provider（如果可用）
     * 2. 健康分数最高的 Provider
     *
     * @param string|null $preferredProvider 首选 Provider ID
     * @return string|null 选中的 Provider ID
     */
    public function select_provider(?string $preferredProvider = null): ?string
    {
        $available = $this->get_available_providers();

        if (empty($available)) {
            return null;
        }

        // 优先使用用户首选
        if ($preferredProvider && in_array($preferredProvider, $available, true)) {
            return $preferredProvider;
        }

        // 按健康分数排序
        usort($available, function ($a, $b) {
            $scoreA = ProviderHealthTracker::get_health_score($a);
            $scoreB = ProviderHealthTracker::get_health_score($b);

            // 分数相同时，按延迟排序
            if ($scoreA === $scoreB) {
                $latencyA = ProviderHealthTracker::get_average_latency($a);
                $latencyB = ProviderHealthTracker::get_average_latency($b);
                return $latencyA - $latencyB;
            }

            return $scoreB - $scoreA;
        });

        return $available[0];
    }

    /**
     * 获取所有可用的 Provider
     *
     * @return array<string> 可用的 Provider ID 列表
     */
    public function get_available_providers(): array
    {
        $available = [];

        foreach ($this->circuitBreakers as $providerId => $breaker) {
            if ($breaker->is_available()) {
                $available[] = $providerId;
            }
        }

        return $available;
    }

    /**
     * 获取故障转移链
     *
     * 返回按优先级排序的 Provider 列表，用于依次尝试
     *
     * @param string|null $preferredProvider 首选 Provider ID
     * @return array<string> Provider ID 列表
     */
    public function get_failover_chain(?string $preferredProvider = null): array
    {
        $available = $this->get_available_providers();

        if (empty($available)) {
            return [];
        }

        // 检查是否有手动优先级设置
        $manual_priority = [];
        if (class_exists('\\WPMind\\Routing\\IntelligentRouter')) {
            $router = \WPMind\Routing\IntelligentRouter::instance();
            $manual_priority = $router->get_manual_priority();
        }

        if (!empty($manual_priority)) {
            // 使用手动优先级排序
            $sorted = [];
            foreach ($manual_priority as $providerId) {
                if (in_array($providerId, $available, true)) {
                    $sorted[] = $providerId;
                }
            }
            // 添加未在手动列表中的可用 Provider
            foreach ($available as $providerId) {
                if (!in_array($providerId, $sorted, true)) {
                    $sorted[] = $providerId;
                }
            }
            $available = $sorted;
        } else {
            // 按健康分数排序
            usort($available, function ($a, $b) {
                return ProviderHealthTracker::get_health_score($b) - ProviderHealthTracker::get_health_score($a);
            });
        }

        // 首选 Provider 放在最前面
        if ($preferredProvider && in_array($preferredProvider, $available, true)) {
            $available = array_values(array_diff($available, [$preferredProvider]));
            array_unshift($available, $preferredProvider);
        }

        return $available;
    }

    /**
     * 记录请求结果
     *
     * @param string $providerId Provider ID
     * @param bool   $success    是否成功
     * @param int    $latencyMs  延迟（毫秒）
     */
    public function record_result(string $providerId, bool $success, int $latencyMs = 0): void
    {
        // 更新熔断器状态
        if (isset($this->circuitBreakers[$providerId])) {
            if ($success) {
                $this->circuitBreakers[$providerId]->record_success();
            } else {
                $this->circuitBreakers[$providerId]->record_failure();
            }
        }

        // 记录健康追踪
        ProviderHealthTracker::record($providerId, $success, $latencyMs);
    }

    /**
     * 获取 Provider 状态摘要
     *
     * @return array Provider 状态信息
     */
    public function get_status_summary(): array
    {
        $summary = [];

        foreach ($this->circuitBreakers as $providerId => $breaker) {
            $cbStatus = $breaker->get_status_details();
            $healthStatus = ProviderHealthTracker::get_provider_status($providerId);

            $summary[$providerId] = [
                'name'          => $this->providers[$providerId]['name'] ?? $providerId,
                'display_name'  => $this->providers[$providerId]['display_name'] ?? $providerId,
                'state'         => $cbStatus['state'],
                'state_label'   => $cbStatus['state_label'],
                'available'     => $breaker->is_available_read_only(),
                'health_score'  => $healthStatus['health_score'],
                'avg_latency'   => $healthStatus['avg_latency'],
                'success_rate'  => $healthStatus['success_rate'],
                'recovery_in'   => $cbStatus['recovery_in'],
            ];
        }

        return $summary;
    }

    /**
     * 检查是否有可用的 Provider
     *
     * @return bool
     */
    public function has_available_provider(): bool
    {
        return !empty($this->get_available_providers());
    }

    /**
     * 重置指定 Provider 的熔断器
     *
     * @param string $providerId Provider ID
     */
    public function reset_provider(string $providerId): void
    {
        if (isset($this->circuitBreakers[$providerId])) {
            $this->circuitBreakers[$providerId]->reset();
        }
        ProviderHealthTracker::clear_provider($providerId);
    }

    /**
     * 重置所有熔断器
     */
    public function reset_all(): void
    {
        foreach ($this->circuitBreakers as $breaker) {
            $breaker->reset();
        }
        ProviderHealthTracker::clear_all();
    }

    /**
     * 获取熔断器实例
     *
     * @param string $providerId Provider ID
     * @return CircuitBreaker|null
     */
    public function get_circuit_breaker(string $providerId): ?CircuitBreaker
    {
        return $this->circuitBreakers[$providerId] ?? null;
    }

    /**
     * 刷新 Provider 列表
     *
     * 当 Provider 配置变更时调用
     */
    public function refresh(): void
    {
        self::$instance = null;
        self::instance();
    }
}