Gen_Hack-and-Slash-Roguelite/Client/Assets/Scripts/Managers/KeyValueArchiveManager.cs

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using Utils;

// 引入 UnityEngine 命名空间以使用 Debug.Log

namespace Managers
{
    /// <summary>
    ///     提供一个通用的键值对存档管理器
    ///     允许存储和检索各种类型的数据，并与 SaveManager 集成以进行持久化。
    /// </summary>
    public class KeyValueArchiveManager : Singleton<KeyValueArchiveManager>, ISavableSingleton, ILaunchManager
    {
        /// <summary>
        ///     内部用于存储键值对的字典，标记为 [Savable] 以便 SaveManager 进行序列化和反序列化。
        /// </summary>
        [Savable] private readonly Dictionary<string, object> _data = new();

        /// <summary>
        ///     私有构造函数，用于单例模式。
        ///     在首次创建实例时，将其注册到 SaveManager。
        /// </summary>
        public KeyValueArchiveManager()
        {
            SaveManager.Instance.RegisterSavable(this);
        }

        public bool Completed { get; set; }
        public string StepDescription { get; } = "加载存档数据中";

        public Task Init()
        {
            Completed = true;
            return Task.CompletedTask;
        }

        public void Clear()
        {
            Completed = false;
        }

        /// <summary>
        ///     将指定键的值设置为指定值。
        ///     如果键已存在，则更新其值；如果不存在，则添加键值对。
        /// </summary>
        /// <typeparam name="T">值的类型。</typeparam>
        /// <param name="key">要设置的键，不能为空或空白。</param>
        /// <param name="value">要存储的值。</param>
        /// <exception cref="ArgumentException">当键为 null 或空白时抛出。</exception>
        public void Set<T>(string key, T value)
        {
            if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("键不能为空或空白。", nameof(key));

            _data[key] = value;
        }

        /// <summary>
        ///     根据指定的键获取存储的值。
        /// </summary>
        /// <typeparam name="T">期望值的类型。</typeparam>
        /// <param name="key">要获取值的键，不能为空或空白。</param>
        /// <param name="defaultValue">如果键不存在或类型不匹配时返回的默认值。默认为类型 T 的默认值。</param>
        /// <returns>与键关联的值，如果键不存在或类型不匹配则返回 defaultValue。</returns>
        /// <exception cref="ArgumentException">当键为 null 或空白时抛出。</exception>
        public T Get<T>(string key, T defaultValue = default)
        {
            if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("键不能为空或空白。", nameof(key));

            if (_data.TryGetValue(key, out var value))
            {
                if (value is T typedValue) return typedValue;

                Debug.LogWarning(
                    $"警告: 键 '{key}' 存储的值类型为 '{value.GetType().Name}'，但请求的类型为 '{typeof(T).Name}'。返回默认值。");
            }

            return defaultValue;
        }

        /// <summary>
        ///     检查管理器中是否存在指定的键。
        /// </summary>
        /// <param name="key">要检查的键，不能为空或空白。</param>
        /// <returns>如果键存在则为 true，否则为 false。</returns>
        /// <exception cref="ArgumentException">当键为 null 或空白时抛出。</exception>
        public bool HasKey(string key)
        {
            if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("键不能为空或空白。", nameof(key));

            return _data.ContainsKey(key);
        }

        /// <summary>
        ///     从管理器中移除指定的键及其对应的值。
        /// </summary>
        /// <param name="key">要移除的键，不能为空或空白。</param>
        /// <exception cref="ArgumentException">当键为 null 或空白时抛出。</exception>
        public void Remove(string key)
        {
            if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("键不能为空或空白。", nameof(key));

            _data.Remove(key);
        }

        /// <summary>
        ///     ISavableSingleton 接口实现：当游戏状态需要被彻底重置时调用（例如，开始一个新游戏）。
        ///     将清除所有存储的键值对。
        /// </summary>
        public void ResetState()
        {
            _data.Clear();
        }
    }
}