Display_D_HP/TeamAAS-VM/Interfaces/ILightManagerService.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using TeamAAS_VP.Core.Lights;
using TeamAAS_VP.Models;
using TeamAAS_VP.Models.Lights;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 管理整套灯控器与全局通道的服务接口。
    /// 提供控制器注册/注销、全局通道亮度与开关操作、连接管理以及配置持久化等功能。
    /// </summary>
    public interface ILightManagerService
    {
        /// <summary>
        /// 当新的灯控制器被注册并添加到管理器时触发。
        /// 事件参数包含被添加的控制器信息与对应 Id。
        /// </summary>
        event EventHandler<LightControllerEventArgs> ControllerAdded;

        /// <summary>
        /// 当已有的灯控制器被从管理器中移除时触发。
        /// 事件参数包含被移除的控制器信息与对应 Id。
        /// </summary>
        event EventHandler<LightControllerEventArgs> ControllerRemoved;

        /// <summary>
        /// 当任意全局通道的状态（例如亮度或开关状态）发生变化时触发。
        /// 事件参数包含受影响的通道信息与新状态。
        /// </summary>
        event EventHandler<LightChannelEventArgs> ChannelStatusChanged;

        /// <summary>
        /// 当前已注册的控制器集合（只读）。
        /// 键为控制器 Id，值为对应的 <see cref="ILightController"/> 实例。
        /// </summary>
        IReadOnlyDictionary<int, ILightController> Controllers { get; }

        /// <summary>
        /// 全局通道集合（只读）。
        /// 键为全局通道 Id，值为对应的 <see cref="ILightChannel"/> 实例。
        /// </summary>
        IReadOnlyDictionary<int, ILightChannel> GlobalChannels { get; }

        /// <summary>
        /// 异步注册并初始化一个新的灯控制器。
        /// </summary>
        /// <param name="id">要注册的控制器 Id，必须唯一。</param>
        /// <param name="configuration">该控制器的配置数据。</param>
        /// <returns>
        /// 返回已注册并初始化的 <see cref="ILightController"/> 实例。
        /// 如果注册失败，返回的任务可能抛出异常或返回 null（由具体实现决定）。
        /// </returns>
        Task<ILightController> RegisterControllerAsync(int id, LightControllerConfig configuration);

        /// <summary>
        /// 异步注销并移除指定 Id 的控制器。
        /// </summary>
        /// <param name="controllerId">要注销的控制器 Id。</param>
        /// <returns>操作成功返回 true；如果找不到控制器或注销失败则返回 false。</returns>
        Task<bool> UnregisterControllerAsync(int controllerId);

        /// <summary>
        /// 为指定的全局通道设置亮度值。
        /// </summary>
        /// <param name="globalChannelId">目标全局通道 Id。</param>
        /// <param name="brightness">亮度值，通常在 0 到 100 范围内（具体范围请参照实现）。</param>
        /// <returns>操作成功返回 true，否则返回 false。</returns>
        Task<bool> SetGlobalChannelBrightnessAsync(int globalChannelId, int brightness);

        /// <summary>
        /// 打开指定的全局通道（将其置于开启状态）。
        /// </summary>
        /// <param name="globalChannelId">目标全局通道 Id。</param>
        /// <returns>操作成功返回 true，否则返回 false。</returns>
        Task<bool> TurnOnGlobalChannelAsync(int globalChannelId);

        /// <summary>
        /// 关闭指定的全局通道（将其置于关闭状态）。
        /// </summary>
        /// <param name="globalChannelId">目标全局通道 Id。</param>
        /// <returns>操作成功返回 true，否则返回 false。</returns>
        Task<bool> TurnOffGlobalChannelAsync(int globalChannelId);

        /// <summary>
        /// 尝试连接所有已注册的控制器并建立通信通道。
        /// </summary>
        /// <returns>所有连接成功则返回 true；若有失败则返回 false（或由实现抛出异常以提供详细错误）。</returns>
        Task<bool> ConnectAllAsync();

        /// <summary>
        /// 断开所有已连接的控制器并释放相关资源。
        /// </summary>
        /// <returns>所有断开成功则返回 true；若有失败则返回 false（或由实现抛出异常以提供详细错误）。returns>
        Task<bool> DisconnectAllAsync();

        /// <summary>
        /// 将当前管理器的配置（包括控制器和全局通道映射）保存到指定文件路径。
        /// </summary>
        /// <param name="filePath">目标文件路径，支持绝对或相对路径。</param>
        /// <returns>完成保存操作的任务。实现可能在 I/O 错误时抛出异常。</returns>
        Task SaveConfigurationAsync(string filePath);

        /// <summary>
        /// 从指定文件路径加载管理器配置并应用到当前实例。
        /// </summary>
        /// <param name="filePath">包含配置的文件路径。</param>
        /// <returns>完成加载操作的任务。实现可能在文件不存在或格式不正确时抛出异常。</returns>
        Task LoadConfigurationAsync(string filePath);
    }
}