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

namespace BaseGames.Core
{
    /// <summary>
    /// 存档服务接口。对外暴露存档系统的全部公开 API，供其他模块通过 ServiceLocator 访问。
    /// 实现由 BaseGames.Core.Save 程序集的 SaveManager 经 SaveServiceAdapter 桥接提供。
    /// </summary>
    public interface ISaveService
    {
        // ── I/O 操作 ──────────────────────────────────────────────────────

        /// <summary>将当前游戏状态写入指定存档槽。</summary>
        Task SaveAsync(int slot);

        /// <summary>从指定存档槽加载游戏状态。成功返回 true，存档损坏/不存在返回 false。</summary>
        Task<bool> LoadAsync(int slot);

        /// <summary>快速存档（覆盖快速存档槽，fire-and-forget）。</summary>
        void QuickSave();

        /// <summary>快速读档（从快速存档槽加载，fire-and-forget）。</summary>
        void QuickLoad();

        /// <summary>快速读档（awaitable 版本）。</summary>
        Task QuickLoadAsync();

        /// <summary>指定槽是否存在有效存档。</summary>
        bool HasSave(int slot);

        /// <summary>当前活跃存档槽（0–2）。</summary>
        int ActiveSlot { get; }

        /// <summary>删除指定存档槽数据。</summary>
        Task DeleteSlotAsync(int slot);

        // ── 存档点 ────────────────────────────────────────────────────────

        /// <summary>上次存档时的场景名（用于死亡复活跳转）。</summary>
        string LastCheckpointScene   { get; }

        /// <summary>上次存档时的出生点 ID。</summary>
        string LastCheckpointSpawnId { get; }

        // ── 世界状态查询 ──────────────────────────────────────────────────

        /// <summary>指定收藏物 ID 是否已拾取。</summary>
        bool IsWorldCollected(string id);

        /// <summary>指定门 / 进程锁 ID 是否已开启。</summary>
        bool IsDoorOpened(string id);

        /// <summary>指定 Boss ID 是否已被击败。</summary>
        bool IsBossDefeated(string bossId);

        /// <summary>当前存档中玩家最大 HP（存档未加载时返回 0）。</summary>
        int GetPlayerMaxHP();

        /// <summary>是否为指定挑战房间的首次通关（首次调用返回 true 并标记）。</summary>
        bool IsFirstClear(string challengeId);

        // ── 世界标志 & 事件链 ─────────────────────────────────────────────

        /// <summary>读取世界标志位。</summary>
        bool GetFlag(string flagId);

        /// <summary>写入世界标志位。</summary>
        void SetFlag(string flagId, bool value);

        /// <summary>获取所有已完成的事件链 ID。</summary>
        IEnumerable<string> GetCompletedChains();

        /// <summary>标记某条事件链已完成。</summary>
        void SetChainCompleted(string chainId);
    }
}