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

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

namespace TeamAAS_VP.Core.Lights
{
    /// <summary>
    /// 表示单个 KCS 灯光通道的封装，用于读取/设置通道亮度并维护本地状态缓存。
    /// 与底层 <see cref="KCSLightController"/> 交互以执行实际的硬件操作。
    /// </summary>
    public class KCSLightChannel : ILightChannel
    {
        /// <summary>
        /// 对应的控制器实例，用于执行底层 IO 操作。由构造函数注入。
        /// </summary>
        private readonly KCSLightController _controller;

        /// <summary>
        /// 本地缓存的亮度值，范围 0-255。
        /// </summary>
        private int _brightness;

        /// <summary>
        /// 本地缓存的开/关状态，基于 <see cref="_brightness"/> 判定（>0 为开）。
        /// </summary>
        private bool _isOn;

        /// <summary>
        /// 通道索引（只读），对应控制器中的通道序号（从 0 开始）。
        /// </summary>
        public int ChannelIndex { get; }

        /// <summary>
        /// 通道名称（可读写），用于 UI 或日志显示。
        /// 默认为 "Channel {index + 1}"。
        /// </summary>
        public string ChannelName { get; set; }

        /// <summary>
        /// 当前本地缓存的亮度值（0-255）。
        /// 注意：此值可能不是实时的硬件状态，若需最新值请调用 <see cref="GetBrightnessAsync"/>。
        /// </summary>
        public int Brightness => _brightness;

        /// <summary>
        /// 当前本地缓存的开/关状态。若需实时状态请调用 <see cref="GetStatusAsync"/>。
        /// </summary>
        public bool IsOn => _isOn;

        /// <summary>
        /// 内部访问器，返回当前缓存亮度（供同程序集使用）。
        /// </summary>
        internal int CurrentBrightness => _brightness;

        /// <summary>
        /// 使用指定的通道索引和控制器实例创建一个新的 <see cref="KCSLightChannel"/>。
        /// </summary>
        /// <param name="index">通道索引（从 0 开始）。</param>
        /// <param name="controller">用于与硬件交互的 <see cref="KCSLightController"/> 实例，不能为空。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="controller"/> 为 null 时抛出。</exception>
        public KCSLightChannel(int index, KCSLightController controller)
        {
            if (controller == null)
                throw new ArgumentNullException(nameof(controller));

            ChannelIndex = index;
            ChannelName = $"Channel {index + 1}";
            _controller = controller;
        }

        /// <summary>
        /// 异步设置通道亮度（0-255）。
        /// 如果设置成功，将更新本地缓存的亮度与开/关状态。
        /// </summary>
        /// <param name="brightness">目标亮度，范围 0-255。</param>
        /// <returns>如果控制器成功应用了亮度返回 true，否则返回 false。</returns>
        /// <exception cref="ArgumentOutOfRangeException">当 <paramref name="brightness"/> 不在 0-255 范围内时抛出。</exception>
        public async Task<bool> SetBrightnessAsync(int brightness)
        {
            if (brightness < 0 || brightness > 255)
                throw new ArgumentOutOfRangeException(nameof(brightness));

            // 向控制器请求设置亮度，控制器负责具体的通信/协议实现。
            var result = await _controller.SetChannelBrightnessInternal(ChannelIndex, brightness);
            if (result)
            {
                // 仅在控制器确认成功后更新本地缓存状态。
                _brightness = brightness;
                _isOn = brightness > 0;
            }
            return result;
        }

        /// <summary>
        /// 异步开启通道。如果当前有缓存亮度且大于 0，则使用该亮度；否则使用默认亮度 100。
        /// 该方法会调用 <see cref="SetBrightnessAsync"/> 并返回控制器操作结果。
        /// </summary>
        /// <returns>如果成功开启返回 true，否则返回 false。</returns>
        public async Task<bool> TurnOnAsync()
        {
            // 若有缓存亮度且大于 0，则恢复该亮度；否则使用默认亮度 100。
            return await SetBrightnessAsync(_brightness > 0 ? _brightness : 100);
        }

        /// <summary>
        /// 异步关闭通道（将亮度设置为 0）。
        /// </summary>
        /// <returns>如果成功关闭返回 true，否则返回 false。</returns>
        public async Task<bool> TurnOffAsync()
        {
            return await SetBrightnessAsync(0);
        }

        /// <summary>
        /// 异步从控制器获取当前通道亮度并更新本地缓存。
        /// </summary>
        /// <returns>读取到的亮度值（0-255）。</returns>
        public async Task<int> GetBrightnessAsync()
        {
            // 从控制器读取最新亮度值并更新本地缓存与开/关状态。
            _brightness = await _controller.GetChannelBrightnessInternal(ChannelIndex);
            _isOn = _brightness > 0;
            return _brightness;
        }

        /// <summary>
        /// 异步获取当前通道开/关状态。
        /// 该方法会触发一次亮度读取以确保状态是最新的。
        /// </summary>
        /// <returns>如果通道处于开启状态返回 true，否则返回 false。</returns>
        public async Task<bool> GetStatusAsync()
        {
            await GetBrightnessAsync();
            return _isOn;
        }
    }
}