wpmind/modules/cost-control/includes/BudgetManager.php

<?php
/**
 * Budget Manager - 预算管理器
 *
 * 管理 AI 服务的费用预算配置
 * 关键修复：使用 recursive_merge() 替代 wp_parse_args() 处理嵌套数组
 *
 * @package WPMind\Modules\CostControl
 * @since 1.0.0
 */

declare(strict_types=1);

namespace WPMind\Modules\CostControl;

class BudgetManager
{
    private const OPTION_KEY = 'wpmind_budget_settings';

    /**
     * 强制模式常量
     */
    public const MODE_ALERT    = 'alert';
    public const MODE_DISABLE  = 'disable';
    public const MODE_DOWNGRADE = 'downgrade';

    /**
     * 单例实例
     */
    private static ?BudgetManager $instance = null;

    /**
     * 预算配置缓存
     */
    private ?array $settings = null;

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

    /**
     * 私有构造函数
     */
    private function __construct() {}

    /**
     * 获取默认预算配置
     */
    public function get_defaults(): array
    {
        return [
            'enabled' => false,
            'global' => [
                'daily_limit_usd'   => 0,
                'daily_limit_cny'   => 0,
                'monthly_limit_usd' => 0,
                'monthly_limit_cny' => 0,
                'alert_threshold'   => 80,
            ],
            'enforcement_mode' => self::MODE_ALERT,
            'providers' => [],
            'notifications' => [
                'admin_notice'  => true,
                'email_alert'   => false,
                'email_address' => '',
            ],
        ];
    }

    /**
     * 递归合并数组（关键修复）
     *
     * wp_parse_args() 无法正确处理嵌套数组，会导致嵌套数组被完全覆盖。
     * 此方法递归合并嵌套数组，确保默认值正确应用。
     *
     * @param array $args     用户提供的参数
     * @param array $defaults 默认值
     * @return array 合并后的数组
     */
    private function recursive_merge(array $args, array $defaults): array
    {
        $result = $defaults;

        foreach ($args as $key => $value) {
            // 如果两边都是数组且默认值中存在该键，递归合并
            if (is_array($value) && isset($defaults[$key]) && is_array($defaults[$key])) {
                // 检查是否是关联数组（非索引数组）
                if ($this->is_associative_array($defaults[$key])) {
                    $result[$key] = $this->recursive_merge($value, $defaults[$key]);
                } else {
                    // 索引数组直接覆盖
                    $result[$key] = $value;
                }
            } else {
                // 非数组或默认值中不存在，直接覆盖
                $result[$key] = $value;
            }
        }

        return $result;
    }

    /**
     * 检查是否是关联数组
     *
     * @param array $arr 要检查的数组
     * @return bool 是否是关联数组
     */
    private function is_associative_array(array $arr): bool
    {
        if (empty($arr)) {
            return false;
        }
        return array_keys($arr) !== range(0, count($arr) - 1);
    }

    /**
     * 获取预算配置
     */
    public function get_settings(): array
    {
        if (null === $this->settings) {
            $saved = get_option(self::OPTION_KEY, []);
            if (!is_array($saved)) {
                $saved = [];
            }
            // 使用 recursive_merge 替代 wp_parse_args
            $this->settings = $this->recursive_merge($saved, $this->get_defaults());
        }
        return $this->settings;
    }

    /**
     * 保存预算配置
     */
    public function save_settings(array $settings): bool
    {
        $sanitized = $this->sanitize_settings($settings);
        $result = update_option(self::OPTION_KEY, $sanitized, false);
        $this->settings = null; // 清除缓存
        return $result;
    }

    /**
     * 清理预算配置
     */
    private function sanitize_settings(array $input): array
    {
        $defaults = $this->get_defaults();
        $sanitized = [];

        // 启用状态
        $sanitized['enabled'] = !empty($input['enabled']);

        // 全局设置
        $sanitized['global'] = [
            'daily_limit_usd'   => $this->sanitize_amount($input['global']['daily_limit_usd'] ?? 0),
            'daily_limit_cny'   => $this->sanitize_amount($input['global']['daily_limit_cny'] ?? 0),
            'monthly_limit_usd' => $this->sanitize_amount($input['global']['monthly_limit_usd'] ?? 0),
            'monthly_limit_cny' => $this->sanitize_amount($input['global']['monthly_limit_cny'] ?? 0),
            'alert_threshold'   => $this->sanitize_threshold($input['global']['alert_threshold'] ?? 80),
        ];

        // 强制模式
        $sanitized['enforcement_mode'] = $this->sanitize_mode($input['enforcement_mode'] ?? self::MODE_ALERT);

        // 按服务商设置
        $sanitized['providers'] = [];
        if (!empty($input['providers']) && is_array($input['providers'])) {
            foreach ($input['providers'] as $provider => $limits) {
                $provider = sanitize_key($provider);
                if (!empty($limits['daily_limit']) || !empty($limits['monthly_limit'])) {
                    $sanitized['providers'][$provider] = [
                        'daily_limit'   => $this->sanitize_amount($limits['daily_limit'] ?? 0),
                        'monthly_limit' => $this->sanitize_amount($limits['monthly_limit'] ?? 0),
                    ];
                }
            }
        }

        // 通知设置
        $sanitized['notifications'] = [
            'admin_notice'  => !empty($input['notifications']['admin_notice']),
            'email_alert'   => !empty($input['notifications']['email_alert']),
            'email_address' => sanitize_email($input['notifications']['email_address'] ?? ''),
        ];

        return $sanitized;
    }

    /**
     * 清理金额
     */
    private function sanitize_amount($value): float
    {
        $amount = (float) $value;
        return max(0, round($amount, 2));
    }

    /**
     * 清理阈值
     */
    private function sanitize_threshold($value): int
    {
        $threshold = (int) $value;
        return max(1, min(100, $threshold));
    }

    /**
     * 清理强制模式
     */
    private function sanitize_mode(string $mode): string
    {
        $allowed = [self::MODE_ALERT, self::MODE_DISABLE, self::MODE_DOWNGRADE];
        return in_array($mode, $allowed, true) ? $mode : self::MODE_ALERT;
    }

    /**
     * 检查预算功能是否启用
     */
    public function is_enabled(): bool
    {
        $settings = $this->get_settings();
        return !empty($settings['enabled']);
    }

    /**
     * 获取全局预算设置
     */
    public function get_global_budget(): array
    {
        $settings = $this->get_settings();
        return $settings['global'] ?? $this->get_defaults()['global'];
    }

    /**
     * 获取服务商预算设置
     */
    public function get_provider_budget(string $provider): ?array
    {
        $settings = $this->get_settings();
        return $settings['providers'][$provider] ?? null;
    }

    /**
     * 获取通知设置
     */
    public function get_notification_settings(): array
    {
        $settings = $this->get_settings();
        return $settings['notifications'] ?? $this->get_defaults()['notifications'];
    }

    /**
     * 获取强制模式
     */
    public function get_enforcement_mode(): string
    {
        $settings = $this->get_settings();
        return $settings['enforcement_mode'] ?? self::MODE_ALERT;
    }

    /**
     * 获取告警阈值
     */
    public function get_alert_threshold(): int
    {
        $global = $this->get_global_budget();
        return $global['alert_threshold'] ?? 80;
    }

    /**
     * 检查是否有任何限额设置
     */
    public function has_any_limits(): bool
    {
        $global = $this->get_global_budget();

        if (($global['daily_limit_usd'] ?? 0) > 0 || ($global['daily_limit_cny'] ?? 0) > 0) {
            return true;
        }
        if (($global['monthly_limit_usd'] ?? 0) > 0 || ($global['monthly_limit_cny'] ?? 0) > 0) {
            return true;
        }

        $settings = $this->get_settings();
        return !empty($settings['providers']);
    }

    /**
     * 获取强制模式的显示名称
     */
    public static function get_mode_label(string $mode): string
    {
        $labels = [
            self::MODE_ALERT    => __('仅告警', 'wpmind'),
            self::MODE_DISABLE  => __('禁用服务', 'wpmind'),
            self::MODE_DOWNGRADE => __('降级模型', 'wpmind'),
        ];
        return $labels[$mode] ?? $mode;
    }

    /**
     * 获取所有强制模式选项
     */
    public static function get_mode_options(): array
    {
        return [
            self::MODE_ALERT    => __('仅告警 - 超限时发送通知，不阻止请求', 'wpmind'),
            self::MODE_DISABLE  => __('禁用服务 - 超限时禁用该服务商', 'wpmind'),
            self::MODE_DOWNGRADE => __('降级模型 - 超限时自动切换到更便宜的模型', 'wpmind'),
        ];
    }
}