namespace BaseGames.Dialogue
{
    /// <summary>
    /// 对话服务接口。通过 ServiceLocator 注册，供 NPC 和测试使用。
    /// </summary>
    public interface IDialogueService
    {
        /// <summary>当前是否有对话正在播放。</summary>
        bool IsDialogueActive { get; }

        /// <summary>
        /// 当前正在播放对话的 NPC ID。无对话活跃时为 <see langword="null"/>。
        /// 供地图标记、HUD、分析埋点等外部系统主动查询，无需订阅事件。
        /// </summary>
        string CurrentNpcId { get; }

        /// <summary>
        /// 每次对话序列（含分支链）全部播完后触发。
        /// 测试代码可订阅此事件等待对话结束，无需依赖 VoidEventChannelSO 资产。
        /// </summary>
        event System.Action OnDialogueEnded;

        /// <summary>
        /// 启动对话序列。
        /// 若已有对话在播放：priority 高于当前对话时立即打断；否则进入队列（上限 8），超出丢弃。
        /// </summary>
        /// <param name="sequence">要播放的对话序列 SO。</param>
        /// <param name="npcId">NPC 标识符，对话结束时随 EVT_NpcDialogueCompleted 广播。</param>
        /// <param name="priority">优先级（默认 0）。数值越大越优先；高优先级可打断低优先级对话。</param>
        void StartDialogue(DialogueSequenceSO sequence, string npcId = "", int priority = 0);

        /// <summary>
        /// 启动对话序列，并在本次对话（含所有排队续播）全部结束时回调 <paramref name="onComplete"/>。
        /// 若 <paramref name="onComplete"/> 为 null，行为与 <see cref="StartDialogue(DialogueSequenceSO,string,int)"/> 完全相同。
        /// 回调仅触发一次；若对话被 <see cref="ForceEnd"/> 打断，回调同样会被调用（在 ForceEnd 末尾）。
        /// 适用场景：EventChain 触发对话后等待完成再执行下一动作、CutsceneModule 同步对话与演出。
        /// </summary>
        void StartDialogue(DialogueSequenceSO sequence, string npcId, int priority, System.Action onComplete);

        /// <summary>
        /// 立即强制结束当前对话（含清空等待队列），恢复游戏输入。
        /// 适用于：场景切换、演出系统打断、死亡/传送等需要硬中断的场合。
        /// 若当前没有活跃对话，则无操作。
        /// </summary>
        void ForceEnd();
    }
}