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

using System;
using System.Collections.Generic;
using UnityEngine; // 引入 UnityEngine 命名空间以使用 Debug.Log

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

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

        /// <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(T))
        {
            if (string.IsNullOrWhiteSpace(key))
            {
                throw new ArgumentException("键不能为空或空白。", nameof(key));
            }

            if (_data.TryGetValue(key, out object 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();
        }

        // 加载存档数据中的步骤描述。
        public string StepDescription { get; } = "加载存档数据中";

        public void Init()
        {
            // 启动初始化逻辑（当前为空）
        }

        public void Clear()
        {
            // 清理逻辑（当前为空）
        }
    }
}