Display_D_HP/TeamAAS-VM/Core/Lights/LightControllerBase.cs

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

namespace TeamAAS_VP.Core.Lights
{
    /// <summary>
    /// 光源控制器基类。
    /// 提供通用的光源控制和通道管理能力，具体控制器应从此类继承并实现硬件相关逻辑。
    /// </summary>
    public abstract class LightControllerBase : ILightController
    {
        /// <summary>
        /// 控制器唯一标识（只读）。
        /// </summary>
        public int Id { get; }

        /// <summary>
        /// 控制器名称，可用于显示或日志记录。
        /// </summary>
        public string Name { get; set; }

        /// <summary>
        /// 光源模型信息（只读），用于指示此控制器对应的光源类型或型号。
        /// </summary>
        public LightModel Model { get; }

        /// <summary>
        /// 控制器支持的通道数量（只读）。
        /// </summary>
        public int ChannelCount { get; }

        /// <summary>
        /// 指示控制器当前是否与设备连接。派生类应在连接/断开时维护此状态。
        /// </summary>
        public bool IsConnected { get; protected set; }

        /// <summary>
        /// 内部维护的通道列表（可变）。派生类或内部实现可通过此集合管理通道。
        /// </summary>
        protected List<ILightChannel> ChannelsInternal { get; }

        /// <summary>
        /// 对外只读的通道集合，外部调用者只能读取，不可修改通道集合本身。
        /// </summary>
        public IReadOnlyList<ILightChannel> Channels => ChannelsInternal;

        /// <summary>
        /// 构造函数：根据指定的 id 和通道数量初始化控制器实例并创建通道集合。
        /// </summary>
        /// <param name="id">控制器标识符。</param>
        /// <param name="channelCount">通道数量，必须为非负整数。</param>
        protected LightControllerBase(int id,int channelCount)
        {
            Id = id;
            ChannelCount = channelCount;
            ChannelsInternal = new List<ILightChannel>();
            InitializeChannels();
        }

        /// <summary>
        /// 初始化通道集合，根据 <see cref="ChannelCount"/> 调用 <see cref="CreateChannel(int)"/> 创建每个通道。
        /// 私有方法，在构造期间调用以确保通道列表已准备就绪。
        /// </summary>
        private void InitializeChannels()
        {
            for (int i = 0; i < ChannelCount; i++)
            {
                ChannelsInternal.Add(CreateChannel(i));
            }
        }

        /// <summary>
        /// 创建指定索引处的通道实例。
        /// 派生类必须实现此方法以返回实际的 <see cref="ILightChannel"/> 对象。
        /// </summary>
        /// <param name="index">通道索引（从 0 开始）。</param>
        /// <returns>新创建的 <see cref="ILightChannel"/> 实例。</returns>
        protected abstract ILightChannel CreateChannel(int index);

        /// <summary>
        /// 异步连接到控制器对应的硬件或服务。
        /// 在成功连接后，派生类应将 <see cref="IsConnected"/> 设置为 true。
        /// </summary>
        /// <returns>表示连接是否成功的任务（true 表示成功）。</returns>
        public abstract Task<bool> ConnectAsync();

        /// <summary>
        /// 异步断开与硬件或服务的连接。
        /// 在断开后，派生类应将 <see cref="IsConnected"/> 设置为 false。
        /// </summary>
        /// <returns>表示断开操作完成的任务。</returns>
        public abstract Task DisconnectAsync();

        /// <summary>
        /// 异步初始化控制器（例如加载配置、检测硬件状态等）。
        /// 在调用任何控制或通道相关操作前应先调用此方法。
        /// </summary>
        /// <returns>表示初始化是否成功的任务（true 表示成功）。</returns>
        public abstract Task<bool> InitializeAsync();

        /// <summary>
        /// 异步打开所有通道的光源。
        /// 实现应保证在并发场景下的线程安全或在文档中说明限制。
        /// </summary>
        /// <returns>表示操作是否成功的任务（true 表示成功）。</returns>
        public abstract Task<bool> TurnOnAllAsync();

        /// <summary>
        /// 异步关闭所有通道的光源。
        /// </summary>
        /// <returns>表示操作是否成功的任务（true 表示成功）。</returns>
        public abstract Task<bool> TurnOffAllAsync();

        /// <summary>
        /// 释放托管资源的虚拟方法实现。
        /// 派生类在覆盖时应调用 base.Dispose(disposing) 以确保基类资源被正确释放。
        /// </summary>
        /// <param name="disposing">若为 true，则同时释放托管资源；若为 false，仅释放非托管资源。</param>
        protected virtual void Dispose(bool disposing)
        {
            if (disposing)
            {
                foreach (var channel in ChannelsInternal)
                {
                    (channel as IDisposable)?.Dispose();
                }
                ChannelsInternal.Clear();
            }
        }

        /// <summary>
        /// 释放当前实例占用的资源并通知垃圾回收器不再调用终结器。
        /// 建议在不再使用控制器时显式调用此方法以尽早释放资源。
        /// </summary>
        public void Dispose()
        {
            Dispose(true);
            GC.SuppressFinalize(this);
        }
    }
}