// Assets/Scripts/World/Map/IMapService.cs
// 地图服务接口，通过 ServiceLocator 注册与查询。
// MapManager 实现此接口；MapPanel 等调用方通过接口解耦。

using System;
using System.Collections.Generic;

namespace BaseGames.World.Map
{
    public interface IMapService
    {
        bool IsExplored(string roomId);
        bool IsMapped(string roomId);
        void SetMapped(string roomId);

        /// <summary>
        /// 批量解锁地图房间（地图碎片覆盖多间房间时调用）。
        /// 内部去重，对每个新增房间触发 <see cref="OnRoomMapped"/>，最后只广播一次 EVT_MapUpdated。
        /// </summary>
        void SetMappedBatch(IEnumerable<string> roomIds);

        MapDatabaseSO Database { get; }

        /// <summary>玩家当前所在区域 ID（最近一次 EVT_RegionChanged 对应的值）。</summary>
        string CurrentRegionId { get; }

        /// <summary>已踏入的房间总数。</summary>
        int ExploredRoomCount { get; }

        /// <summary>探索进度 0~1（已探索房间数 / 数据库总房间数）。</summary>
        float GetExplorationProgress();

        /// <summary>返回属于指定区域的所有房间数据；regionId 为空时返回空数组。</summary>
        MapRoomDataSO[] GetRoomsByRegion(string regionId);

        // ── 定位门控（Locator / 指南针）────────────────────────────────────────

        /// <summary>
        /// 是否已启用"定位"能力（由指南针类护符解锁）。
        /// 为 false 时，地图 UI 应隐藏玩家位置点——玩家能看地图但不知自己在哪。
        /// 由 <see cref="SetLocatorEnabled"/> 控制，跨存档持久化。
        /// </summary>
        bool IsLocatorEnabled { get; }

        /// <summary>
        /// 设置定位能力开关（拾取/装备指南针道具时调用 true）。
        /// 状态变化时触发 <see cref="OnLocatorChanged"/> 并写入存档。
        /// </summary>
        void SetLocatorEnabled(bool enabled);

        /// <summary>定位能力开关变化时触发；地图 UI 据此显示/隐藏玩家位置点。</summary>
        event Action OnLocatorChanged;

        /// <summary>
        /// 当地图数据库结构发生变化（房间增删/编辑器热改/运行时热更）时触发。
        /// MapPanel、MinimapHUD 等 UI 应订阅此事件以执行完整重建。
        /// </summary>
        event Action OnDatabaseChanged;

        /// <summary>
        /// 探索进度变化事件（读档恢复 / 房间状态变化 / SetMapped 等）。
        /// 与 <see cref="OnDatabaseChanged"/> 区分：本事件不要求 UI 销毁重建结构，
        /// 仅需调用 RefreshAllCells/RebuildPins 等轻量刷新即可。
        /// </summary>
        event Action OnExplorationChanged;

        /// <summary>
        /// 某个房间首次被标记为 Mapped 时触发（参数为 roomId）。
        /// UI 可订阅做"地图碎片解锁"动画。批量 SetMappedBatch 时对每个新增房间各触发一次。
        /// </summary>
        event Action<string> OnRoomMapped;

        /// <summary>主动通知所有订阅者数据库结构已变更（同时会让 Database 的空间索引失效）。</summary>
        void NotifyDatabaseChanged();
    }
}