// ============================================================================
// IYooAssetService.cs — YooAsset 资源加载服务接口
// 定义在 Main 程序集中，供所有业务系统使用
// ============================================================================

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

namespace ProjSG.Resource
{
    /// <summary>
    /// YooAsset 资源加载服务接口。
    /// 封装 YooAsset ResourcePackage 的核心加载能力，提供 UniTask 异步 API。
    /// </summary>
    public interface IYooAssetService
    {
        /// <summary>
        /// 服务是否已初始化完成
        /// </summary>
        bool IsInitialized { get; }

        /// <summary>
        /// 当前运行模式
        /// </summary>
        EPlayMode PlayMode { get; }

        // ====================================================================
        // 初始化
        // ====================================================================

        /// <summary>
        /// 初始化 YooAsset 资源服务。
        /// 在 Launch 阶段由 YooAssetInitializer 调用。
        /// </summary>
        /// <param name="playMode">运行模式</param>
        /// <param name="remoteServices">CDN 远程服务（HostPlayMode/WebPlayMode 必需）</param>
        /// <returns>初始化完成</returns>
        UniTask InitializeAsync(EPlayMode playMode, IRemoteServices remoteServices = null);

        // ====================================================================
        // 资源加载 — Asset
        // ====================================================================

        /// <summary>
        /// 异步加载指定类型的资源。
        /// </summary>
        /// <typeparam name="T">资源类型（GameObject, Sprite, AudioClip 等）</typeparam>
        /// <param name="location">YooAsset 资源地址</param>
        /// <param name="priority">加载优先级（0 = 默认）</param>
        /// <param name="ct">取消令牌</param>
        /// <returns>加载完成的资源对象，加载失败返回 null</returns>
        UniTask<T> LoadAssetAsync<T>(string location, uint priority = 0,
            CancellationToken ct = default) where T : UnityEngine.Object;

        /// <summary>
        /// 异步加载指定类型的资源（Type 参数版本）。
        /// </summary>
        UniTask<UnityEngine.Object> LoadAssetAsync(string location, Type type, uint priority = 0,
            CancellationToken ct = default);

        /// <summary>
        /// 异步加载子资源（如 SpriteAtlas 中的 Sprite）。
        /// </summary>
        UniTask<SubAssetsHandle> LoadSubAssetsAsync<T>(string location, uint priority = 0,
            CancellationToken ct = default) where T : UnityEngine.Object;

        /// <summary>
        /// 异步加载同一 Bundle 下的所有同类型资源。
        /// </summary>
        UniTask<AllAssetsHandle> LoadAllAssetsAsync<T>(string location, uint priority = 0,
            CancellationToken ct = default) where T : UnityEngine.Object;

        // ====================================================================
        // 资源加载 — RawFile
        // ====================================================================

        /// <summary>
        /// 异步加载原始文件并返回文本内容。
        /// 用于配置文件（.txt, .json, .csv 等）加载。
        /// </summary>
        UniTask<string> LoadRawFileTextAsync(string location, CancellationToken ct = default);

        /// <summary>
        /// 异步加载原始文件并返回字节数组。
        /// </summary>
        UniTask<byte[]> LoadRawFileBytesAsync(string location, CancellationToken ct = default);

        // ====================================================================
        // 场景加载
        // ====================================================================

        /// <summary>
        /// 异步加载场景。
        /// </summary>
        UniTask<SceneHandle> LoadSceneAsync(string location, LoadSceneMode sceneMode = LoadSceneMode.Single,
            LocalPhysicsMode physicsMode = LocalPhysicsMode.None, bool suspendLoad = false, uint priority = 0, CancellationToken ct = default);

        // ====================================================================
        // 资源信息查询
        // ====================================================================

        /// <summary>
        /// 检查资源地址是否有效。
        /// </summary>
        bool CheckLocationValid(string location);

        /// <summary>
        /// 获取指定标签的所有资源信息。
        /// </summary>
        YooAsset.AssetInfo[] GetAssetInfosByTag(string tag);

        /// <summary>
        /// 检查资源是否需要从远程下载。
        /// </summary>
        bool IsNeedDownloadFromRemote(string location);

        // ====================================================================
        // 资源下载
        // ====================================================================

        /// <summary>
        /// 创建资源下载器并开始下载。
        /// </summary>
        UniTask DownloadByTagsAsync(string[] tags, int downloadingMaxNumber = 10,
            int failedTryAgain = 3, IProgress<float> progress = null, CancellationToken ct = default);

        // ====================================================================
        // 版本管理
        // ====================================================================

        /// <summary>
        /// 请求最新包裹版本。
        /// </summary>
        UniTask<string> RequestPackageVersionAsync(CancellationToken ct = default);

        /// <summary>
        /// 更新包裹 Manifest 到指定版本。
        /// </summary>
        UniTask UpdatePackageManifestAsync(string packageVersion, CancellationToken ct = default);

        // ====================================================================
        // 资源释放
        // ====================================================================

        /// <summary>
        /// 释放资源句柄（引用计数 -1）。
        /// </summary>
        void ReleaseHandle(HandleBase handle);

        /// <summary>
        /// 卸载所有引用计数为零的资源。
        /// </summary>
        UniTask UnloadUnusedAssetsAsync();

        /// <summary>
        /// 强制卸载所有资源。
        /// </summary>
        UniTask UnloadAllAssetsAsync();
    }
}