/*
计划（伪代码，逐步说明）：
1. 在接口文件顶部添加文件级别注释，说明该文件用途与适用范围。
2. 为接口 `ILightChannel` 添加 XML 文档注释，描述接口职责（表示一个光源通道）。
3. 为每个属性添加 XML 注释：
   - `ChannelIndex`：只读，返回通道索引（非负整数）。
   - `ChannelName`：可读写，通道名称，允许为空或空字符串取决于实现。
   - `Brightness`：只读，返回当前亮度（建议范围 0-100）。
   - `IsOn`：只读，指示通道是否处于开启状态。
4. 为每个异步方法添加 XML 注释，说明参数、返回值语义以及可能的预期行为：
   - `SetBrightnessAsync(int brightness)`：说明亮度取值范围、异常或边界处理建议以及返回表示成功与否的 `Task<bool>`。
   - `TurnOnAsync()` / `TurnOffAsync()`：说明返回值含义（操作是否成功），并建议实现应保证幂等性。
   - `GetBrightnessAsync()` / `GetStatusAsync()`：说明返回当前状态/亮度的 `Task`。
5. 使用中文在 `<summary>`、`<param>`、`<returns>` 和 `<remarks>` 中撰写注释，保证对使用者友好。
6. 保持注释简洁、准确并符合项目风格（XML 注释用于生成文档），不修改接口签名或逻辑。

下面输出修改后的接口文件，包含完整中文 XML 注释。
*/

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

namespace TeamAAS_VP.Core.Lights
{
    /// <summary>
    /// 表示一个光源通道的接口。
    /// 实现该接口的类型应封装单个物理或虚拟光源通道的状态与控制操作（如亮度设置、开关等）。
    /// </summary>
    public interface ILightChannel
    {
        /// <summary>
        /// 获取通道索引（只读）。
        /// 索引用于唯一标识同一设备或集合中的通道，通常为非负整数。
        /// </summary>
        int ChannelIndex { get; }

        /// <summary>
        /// 获取或设置通道名称。
        /// 名称用于在 UI 或日志中显示更友好的通道标识，允许为空或空字符串，具体行为由实现决定。
        /// </summary>
        string ChannelName { get; set; }

        /// <summary>
        /// 获取当前亮度（只读）。
        /// 亮度通常在 0 到 100 的范围内表示（实现可约束或采用其他范围，但应在文档中说明）。
        /// </summary>
        int Brightness { get; }

        /// <summary>
        /// 获取通道当前的开关状态（只读）。
        /// 返回 true 表示通道处于开启状态；false 表示关闭状态。
        /// </summary>
        bool IsOn { get; }

        /// <summary>
        /// 异步设置通道亮度。
        /// </summary>
        /// <param name="brightness">目标亮度值。建议范围为 0 到 100；超出范围的处理由实现决定（例如截断或抛出异常）。</param>
        /// <returns>
        /// 返回一个 <see cref="Task{Boolean}"/>，其结果为 true 表示操作成功并且亮度已应用，false 表示操作失败。
        /// </returns>
        /// <remarks>
        /// 实现应尽可能保证该操作的幂等性，且在失败时不改变设备到不可预测的状态。
        /// 如需取消，请在具体实现中提供取消机制（例如接受 CancellationToken 的重载）。
        /// </remarks>
        Task<bool> SetBrightnessAsync(int brightness);

        /// <summary>
        /// 异步开启通道。
        /// </summary>
        /// <returns>
        /// 返回一个 <see cref="Task{Boolean}"/>，其结果为 true 表示通道已成功开启，false 表示开启失败。
        /// </returns>
        /// <remarks>
        /// 实现应保证多次调用的幂等性（多次开启不会引起错误）。
        /// </remarks>
        Task<bool> TurnOnAsync();

        /// <summary>
        /// 异步关闭通道。
        /// </summary>
        /// <returns>
        /// 返回一个 <see cref="Task{Boolean}"/>，其结果为 true 表示通道已成功关闭，false 表示关闭失败。
        /// </returns>
        /// <remarks>
        /// 实现应保证多次调用的幂等性（多次关闭不会引起错误）。
        /// </remarks>
        Task<bool> TurnOffAsync();

        /// <summary>
        /// 异步获取当前亮度。
        /// </summary>
        /// <returns>
        /// 返回一个 <see cref="Task{Int32}"/>，其结果为当前亮度值（通常在 0 到 100 之间）。
        /// </returns>
        Task<int> GetBrightnessAsync();

        /// <summary>
        /// 异步获取通道当前开关状态。
        /// </summary>
        /// <returns>
        /// 返回一个 <see cref="Task{Boolean}"/>，其结果为 true 表示通道已开启，false 表示通道已关闭。
        /// </returns>
        Task<bool> GetStatusAsync();
    }
}