/* 详细伪代码（步骤说明）：
   1. 在接口文件顶部添加多行注释，说明接下来要对接口及其成员生成 XML 注释的目的。
   2. 为接口 `ILightController` 添加总体的 `<summary>` 描述，解释该接口代表一个光源控制器，负责连接、初始化与批量控制通道。
   3. 为每个属性添加 `<summary>`：
      - `Id`：唯一标识符（只读）。
      - `Name`：控制器显示名称（只读）。
      - `Model`：控制器型号（只读）。
      - `ChannelCount`：通道数量，通常与 `Channels.Count` 一致（只读）。
      - `IsConnected`：指示与硬件连接状态（只读）。
      - `Channels`：只读通道列表，返回 `ILightChannel` 的不可变视图。
   4. 为每个方法添加 `<summary>`、`<returns>`，必要时添加 `<remarks>`：
      - `ConnectAsync`：异步建立连接，成功返回 true。
      - `DisconnectAsync`：异步断开连接（无需返回值）。
      - `InitializeAsync`：在连接后初始化控制器与通道配置，成功返回 true。
      - `TurnOnAllAsync` / `TurnOffAllAsync`：异步批量打开/关闭所有通道，返回整体成功状态（所有通道成功为 true）。
   5. 为接口继承的 `IDisposable` 提醒实现者在 `Dispose` 中释放非托管资源与关闭连接。
   6. 确保注释使用简体中文，保持简洁并包含异步行为、预期副作用与返回值含义。
   7. 将注释以标准 C# XML 文档注释（///）形式插入到接口及其成员上方，以便生成文档和在 IDE 中显示工具提示。
*/

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 ILightController : IDisposable
    {
        /// <summary>
        /// 控制器的唯一标识符。
        /// 通常由设备发现或配置阶段分配，供日志和映射使用。
        /// </summary>
        int Id { get; }

        /// <summary>
        /// 控制器的显示名称或描述。
        /// 可用于 UI 展示或调试。
        /// </summary>
        string Name { get; }

        /// <summary>
        /// 控制器的型号信息。
        /// 用于区分不同厂商或不同协议的实现逻辑。
        /// </summary>
        LightModel Model { get; }

        /// <summary>
        /// 控制器包含的通道数量。
        /// 通常应与 <see cref="Channels"/> 中的元素数量一致。
        /// </summary>
        int ChannelCount { get; }

        /// <summary>
        /// 指示控制器当前是否与底层硬件建立了连接。
        /// 在成功调用 <see cref="ConnectAsync"/> 并完成后应为 true，在调用 <see cref="DisconnectAsync"/> 或连接丢失后应为 false。
        /// </summary>
        bool IsConnected { get; }

        /// <summary>
        /// 只读的光源通道集合。
        /// 每个通道通过 <see cref="ILightChannel"/> 描述单个输出通道的状态与控制接口。
        /// </summary>
        IReadOnlyList<ILightChannel> Channels { get; }

        /// <summary>
        /// 异步建立与光源控制器的连接。
        /// </summary>
        /// <returns>
        /// 如果连接成功并且控制器可用则返回 <c>true</c>，否则返回 <c>false</c>。
        /// </returns>
        Task<bool> ConnectAsync();

        /// <summary>
        /// 异步断开与光源控制器的连接并释放会话相关的资源。
        /// 调用后 <see cref="IsConnected"/> 应变为 <c>false</c>。
        /// </summary>
        /// <returns>当断开完成时的任务。</returns>
        Task DisconnectAsync();

        /// <summary>
        /// 在连接建立后对控制器及其通道进行初始化（例如读取配置、设置初始状态等）。
        /// </summary>
        /// <returns>
        /// 初始化成功返回 <c>true</c>；若初始化失败（例如硬件响应异常或配置不兼容）返回 <c>false</c>。
        /// </returns>
        Task<bool> InitializeAsync();

        /// <summary>
        /// 异步将所有通道打开（或设置为“开启”状态）。
        /// 实现应遍历 <see cref="Channels"/> 并对每个通道执行打开操作。
        /// </summary>
        /// <returns>
        /// 当所有通道均成功打开时返回 <c>true</c>；若任一通道操作失败则返回 <c>false</c>（具体策略由实现决定）。
        /// </returns>
        Task<bool> TurnOnAllAsync();

        /// <summary>
        /// 异步将所有通道关闭（或设置为“关闭”状态）。
        /// 实现应遍历 <see cref="Channels"/> 并对每个通道执行关闭操作。
        /// </summary>
        /// <returns>
        /// 当所有通道均成功关闭时返回 <c>true</c>；若任一通道操作失败则返回 <c>false</c>（具体策略由实现决定）。
        /// </returns>
        Task<bool> TurnOffAllAsync();
    }
}