Display_D_HP/TeamAAS-VM/Interfaces/IConfigService.cs

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Threading.Tasks;
using TeamAAS_VP.Models;
using TeamAAS_VP.Models.Calibration;
using TeamAAS_VP.Models.Feeder;
using TeamAAS_VP.Models.Lights;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 配置管理服务：管理系统设置、相机、机器人、Feeder、PLC、后台通讯等配置的增删改查与持久化。
    /// 实现类负责在内存与持久化存储（例如文件或数据库）之间同步数据，并提供同步与异步的加载/保存接口。
    /// </summary>
    public interface IConfigService : IDisposable
    {
        // Load/Save

        /// <summary>
        /// 同步加载所有配置（从持久化存储读取并更新内存中的配置）。
        /// </summary>
        /// <remarks>
        /// 该方法为阻塞调用，适用于应用启动时或明确需要同步加载的场景。
        /// 实现应保证在发生错误时记录日志并在必要时抛出异常以通知调用方。
        /// </remarks>
        void LoadAll();

        /// <summary>
        /// 异步加载所有配置（从持久化存储读取并更新内存中的配置）。
        /// </summary>
        /// <returns>一个表示异步加载操作的任务。</returns>
        Task LoadAllAsync();

        /// <summary>
        /// 同步保存所有当前内存中的配置到持久化存储。
        /// </summary>
        /// <remarks>
        /// 该方法为阻塞调用，适用于需要立即保证配置持久化的场景。
        /// </remarks>
        void SaveAll();

        /// <summary>
        /// 异步保存所有当前内存中的配置到持久化存储。
        /// </summary>
        /// <returns>表示保存操作完成的任务。</returns>
        Task SaveAllAsync();

        // Cameras

        /// <summary>
        /// 获取所有已注册的相机信息的只读集合。
        /// </summary>
        /// <returns>相机信息的只读集合快照。</returns>
        IReadOnlyCollection<CameraInfo> GetAllCameras();

        /// <summary>
        /// 根据标识获取单个相机信息。
        /// </summary>
        /// <param name="id">相机的唯一标识符。</param>
        /// <returns>对应的 <see cref="CameraInfo"/> 实例；若未找到则返回 null。</returns>
        CameraInfo GetCamera(Guid id);

        /// <summary>
        /// 新增或更新指定的相机信息。
        /// </summary>
        /// <param name="camera">要新增或更新的相机信息，不能为 null。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="camera"/> 为 null 时抛出。</exception>
        CameraInfo AddOrUpdateCamera(CameraInfo camera);

        /// <summary>
        /// 移除指定标识的相机信息。
        /// </summary>
        /// <param name="id">要移除的相机的唯一标识符。</param>
        /// <returns>如果找到并移除成功则返回 true；否则返回 false。</returns>
        bool RemoveCamera(Guid id);

        /// <summary>
        /// 判断是否包含指定标识的相机配置。
        /// </summary>
        /// <param name="id">相机唯一标识符。</param>
        /// <returns>存在则返回 true，否则返回 false。</returns>
        bool ContainsCamera(Guid id);

        // Robots

        /// <summary>
        /// 获取所有已注册的机器人信息的只读集合。
        /// </summary>
        /// <returns>机器人信息的只读集合快照。</returns>
        IReadOnlyCollection<RobotInfo> GetAllRobots();

        /// <summary>
        /// 根据标识获取单个机器人信息。
        /// </summary>
        /// <param name="id">机器人的唯一标识符。</param>
        /// <returns>对应的 <see cref="RobotInfo"/> 实例；若未找到则返回 null。</returns>
        RobotInfo GetRobot(Guid id);

        /// <summary>
        /// 新增或更新指定的机器人信息。
        /// </summary>
        /// <param name="robot">要新增或更新的机器人信息，不能为 null。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="robot"/> 为 null 时抛出。</exception>
        RobotInfo AddOrUpdateRobot(RobotInfo robot);

        /// <summary>
        /// 移除指定标识的机器人信息。
        /// </summary>
        /// <param name="id">要移除的机器人的唯一标识符。</param>
        /// <returns>如果找到并移除成功则返回 true；否则返回 false。</returns>
        bool RemoveRobot(Guid id);

        /// <summary>
        /// 判断是否包含指定标识的机器人配置。
        /// </summary>
        /// <param name="id">机器人唯一标识符。</param>
        /// <returns>存在则返回 true，否则返回 false。</returns>
        bool ContainsRobot(Guid id);

        /// <summary>
        /// 修改指定机器人id的步进距离
        /// </summary>
        /// <param name="id">机器人唯一标识符。</param>
        /// <param name="stepDistance">步进距离</param>
        /// <returns></returns>
        bool UpdateRobotStepDistance(Guid id, double stepDistance);

        /// <summary>
        /// 获取指定机器人Id的步进距离
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        double GetRobotStepDistance(Guid id);

        // Feeders

        /// <summary>
        /// 获取所有已注册的 Feeder 信息的只读集合。
        /// </summary>
        /// <returns>Feeder 信息的只读集合快照。</returns>
        IReadOnlyCollection<FeederInfo> GetAllFeeders();

        /// <summary>
        /// 根据标识获取单个 Feeder 信息。
        /// </summary>
        /// <param name="id">Feeder 的唯一标识符。</param>
        /// <returns>对应的 <see cref="FeederInfo"/> 实例；若未找到则返回 null。</returns>
        FeederInfo GetFeeder(Guid id);

        /// <summary>
        /// 新增或更新指定的 Feeder 信息。
        /// </summary>
        /// <param name="feeder">要新增或更新的 Feeder 信息，不能为 null。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="feeder"/> 为 null 时抛出。</exception>
        FeederInfo AddOrUpdateFeeder(FeederInfo feeder);

        /// <summary>
        /// 移除指定标识的 Feeder 信息。
        /// </summary>
        /// <param name="id">要移除的 Feeder 的唯一标识符。</param>
        /// <returns>如果找到并移除成功则返回 true；否则返回 false。</returns>
        bool RemoveFeeder(Guid id);

        /// <summary>
        /// 判断是否包含指定标识的 Feeder 配置。
        /// </summary>
        /// <param name="id">Feeder 唯一标识符。</param>
        /// <returns>存在则返回 true，否则返回 false。</returns>
        bool ContainsFeeder(Guid id);

        // PLCs

        /// <summary>
        /// 获取所有已注册的 PLC 信息的只读集合。
        /// </summary>
        /// <returns>PLC 信息的只读集合快照。</returns>
        IReadOnlyCollection<PlcInfo> GetAllPlcs();

        /// <summary>
        /// 根据标识获取单个 PLC 信息。
        /// </summary>
        /// <param name="id">PLC 的唯一标识符。</param>
        /// <returns>对应的 <see cref="PlcInfo"/> 实例；若未找到则返回 null。</returns>
        PlcInfo GetPlc(Guid id);

        /// <summary>
        /// 新增或更新指定的 PLC 信息。
        /// </summary>
        /// <param name="plc">要新增或更新的 PLC 信息，不能为 null。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="plc"/> 为 null 时抛出。</exception>
        PlcInfo AddOrUpdatePlc(PlcInfo plc);

        /// <summary>
        /// 移除指定标识的 PLC 信息。
        /// </summary>
        /// <param name="id">要移除的 PLC 的唯一标识符。</param>
        /// <returns>如果找到并移除成功则返回 true；否则返回 false。</returns>
        bool RemovePlc(Guid id);

        /// <summary>
        /// 判断是否包含指定标识的 PLC 配置。
        /// </summary>
        /// <param name="id">PLC 唯一标识符。</param>
        /// <returns>存在则返回 true，否则返回 false。</returns>
        bool ContainsPlc(Guid id);

        // Plc Addresses
        /// <summary>
        /// Get all PlcAddress entries
        /// </summary>
        /// <returns></returns>
        PlcAddressConfig GetPlcAddresses();

        
        // Background TCP

        /// <summary>
        /// 获取后台通讯（TCP/IP）配置。
        /// </summary>
        /// <returns>当前后台 TCP 配置快照。</returns>
        BgTcpIP GetBgTcp();

        /// <summary>
        /// 设置后台通讯（TCP/IP）配置（仅更新内存）。
        /// </summary>
        /// <param name="cfg">新的后台 TCP 配置，不能为 null。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="cfg"/> 为 null 时抛出。</exception>
        void SetBgTcp(BgTcpIP cfg);

        /// <summary>
        /// 将当前内存中的后台 TCP 配置保存到持久化存储。
        /// </summary>
        void SaveBgTcp();

        // Background Modbus

        /// <summary>
        /// 获取后台 Modbus TCP 配置。
        /// </summary>
        /// <returns>当前后台 Modbus TCP 配置快照。</returns>
        BgModbusTcp GetBgModbusTcp();

        /// <summary>
        /// 设置后台 Modbus TCP 配置（仅更新内存）。
        /// </summary>
        /// <param name="cfg">新的后台 Modbus TCP 配置，不能为 null。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="cfg"/> 为 null 时抛出。</exception>
        void SetBgModbusTcp(BgModbusTcp cfg);

        /// <summary>
        /// 将当前内存中的后台 Modbus TCP 配置保存到持久化存储。
        /// </summary>
        void SaveBgModbusTcp();

        //系统设置

        /// <summary>
        /// 获取系统设置
        /// </summary>
        /// <returns></returns>
        SystemConfiguration GetSystemConfiguration();

        /// <summary>
        /// 保存系统设置
        /// </summary>
        void SaveSystemConfiguration(SystemConfiguration systemConfiguration);

        //清料任务

        /// <summary>
        /// 获取所有清料任务
        /// </summary>
        /// <returns></returns>
        IReadOnlyCollection<FeederClearWork> GetAllClearanceTasks();

        /// <summary>
        /// 新增或更新清料任务
        /// </summary>
        /// <param name="task"></param>
        /// <returns></returns>
        FeederClearWork AddOrUpdateClearanceTask(FeederClearWork task);

        /// <summary>
        /// 移除清料任务
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        bool RemoveClearanceTask(Guid id);

        /// <summary>
        /// 清除所有清料任务
        /// </summary>
        void ClearAllClearanceTasks();

        /// <summary>
        /// 判断是否包含指定标识的清料任务
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        bool ContainsClearanceTask(Guid id);

        /// <summary>
        /// 根据标识获取单个清料任务信息
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        FeederClearWork GetClearanceTask(Guid id);

        /// <summary>
        /// 判断是否包含指定编号的清料任务
        /// </summary>
        /// <param name="taskNumber"></param>
        /// <returns></returns>
        bool ContainsClearanceTaskByNumber(int taskNumber);

        /// <summary>
        /// 根据编号获取单个清料任务信息
        /// </summary>
        /// <param name="taskNumber"></param>
        /// <returns></returns>
        FeederClearWork GetClearanceTaskByNumber(int taskNumber);

        // Light controllers and channels

        /// <summary>
        /// 获取所有已注册的灯光控制器信息的只读集合。
        /// </summary>
        /// <returns>灯光控制器信息的只读集合快照。</returns>
        IReadOnlyCollection<LightControllerConfig> GetAllLightControllers();

        /// <summary>
        /// 根据标识获取单个灯光控制器信息。
        /// </summary>
        /// <param name="id">灯光控制器的唯一标识符。</param>
        /// <returns>对应的 <see cref="LightControllerConfig"/> 实例；若未找到则返回 null。</returns>
        LightControllerConfig GetLightController(int id);

        /// <summary>
        /// 新增或更新指定的灯光控制器信息。
        /// </summary>
        /// <param name="controller">要新增或更新的灯光控制器信息，不能为 null。</param>
        /// <exception cref="ArgumentNullException">当 <paramref name="controller"/> 为 null 时抛出。</exception>
        LightControllerConfig AddOrUpdateLightController(LightControllerConfig controller);

        /// <summary>
        /// 移除指定标识的灯光控制器信息。
        /// </summary>
        /// <param name="id">要移除的灯光控制器的唯一标识符。</param>
        /// <returns>如果找到并移除成功则返回 true；否则返回 false。</returns>
        bool RemoveLightController(int id);

        /// <summary>
        /// 判断是否包含指定标识的灯光控制器配置。
        /// </summary>
        /// <param name="id">灯光控制器唯一标识符。</param>
        /// <returns>存在则返回 true，否则返回 false。</returns>
        bool ContainsLightController(int id);

        /// <summary>
        /// 获取所有已注册的灯光通道信息的只读集合。
        /// </summary>
        /// <returns>灯光通道信息的只读集合快照。</returns>
        IReadOnlyCollection<ChannelConfig> GetAllLightChannels();

        /// <summary>
        /// 根据全局索引获取单个灯光通道信息。
        /// </summary>
        /// <param name="globalIndex">灯光通道的全局索引。</param>
        /// <returns>对应的 <see cref="ChannelConfig"/> 实例；若未找到则返回 null。</returns>
        ChannelConfig GetLightChannelByGlobalIndex(int globalIndex);

        /// <summary>
        /// 判断是否包含指定全局索引的灯光通道配置。
        /// </summary>
        /// <param name="globalIndex">灯光通道的全局索引。</param>
        /// <returns>存在则返回 true，否则返回 false。</returns>
        bool ContainsLightChannelByGlobalIndex(int globalIndex);

        /// <summary>
        /// 更新指定灯光通道的默认亮度值并保存到持久化存储。
        /// </summary>
        /// <param name="globalIndex">灯光通道的全局索引。</param>
        /// <param name="brightness">新的默认亮度值，范围应在合适的区间内。</param>
        /// <returns>如果找到并更新成功则返回 true；否则返回 false。</returns>
        bool UpdateChannelDefaultBrightness(int globalIndex, int brightness);

    }
}