// ============================================================================
// IResourceCache.cs — 资源缓存服务接口
// Feature: 001-async-resource-loading
// ============================================================================

using System;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace ProjSG.Resource
{
    /// <summary>
    /// 全局资源缓存服务接口。
    /// 提供预加载后的同步缓存获取能力，以及异步加载+自动缓存能力。
    /// </summary>
    public interface IResourceCache
    {
        /// <summary>
        /// 缓存中的资源数量
        /// </summary>
        int CachedCount { get; }

        /// <summary>
        /// 同步获取已缓存的资源。
        /// 如果资源未在缓存中，返回 null（不会触发加载）。
        /// </summary>
        T GetCached<T>(string location) where T : UnityEngine.Object;

        /// <summary>
        /// 检查资源是否已在缓存中。
        /// </summary>
        bool IsCached(string location);

        /// <summary>
        /// 异步获取资源。缓存命中直接返回，未命中则加载并缓存。
        /// 同一资源的并发请求自动去重。
        /// </summary>
        UniTask<T> GetOrLoadAsync<T>(string location) where T : UnityEngine.Object;

        /// <summary>
        /// 批量预加载资源到缓存。
        /// </summary>
        UniTask PreloadAsync(string[] locations, bool permanent = false, IProgress<float> progress = null);

        /// <summary>
        /// 释放指定资源的缓存。常驻资源需 forceRelease=true。
        /// </summary>
        void Release(string location, bool forceRelease = false);

        /// <summary>
        /// 释放所有非常驻缓存资源。
        /// </summary>
        void ReleaseAll();

        /// <summary>
        /// 释放所有资源（含常驻）。
        /// </summary>
        void ForceReleaseAll();
    }
}