Display_D_HP/Team.FFFeederService/Interfaces/IFeederService.cs

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

namespace Team.FFFeederService.Interfaces
{
    /// <summary>
    /// Feeder 管理服务接口。
    /// 提供创建、查询、注销、移除和枚举 Feeder 的同步和异步操作。
    /// 所有方法在实现中应保证线程安全并正确释放资源。
    /// </summary>
    public interface IFeederService
    {
        /// <summary>
        /// 异步创建并注册一个新的 Feeder 实例。
        /// </summary>
        /// <param name="id">Feeder 的唯一标识符 (GUID)。</param>
        /// <param name="feederNo">Feeder 的编号索引（用于位置/槽位标识）。</param>
        /// <param name="name">Feeder 的显示名称。</param>
        /// <param name="ip">Feeder 的网络 IP 地址或主机名。</param>
        /// <param name="port">Feeder 的网络端口号。</param>
        /// <param name="feederBrand">Feeder 的品牌枚举，用于创建特定实现。</param>
        /// <returns>返回一个任务，任务结果为是否成功创建并注册 Feeder。</returns>
        Task<bool> CreateFeederAsync(Guid id,int feederNo, string name, string ip, int port, FeederBrand feederBrand);

        /// <summary>
        /// 同步创建并注册一个新的 Feeder 实例。
        /// </summary>
        /// <param name="id">Feeder 的唯一标识符 (GUID)。</param>
        /// <param name="feederNo">Feeder 的编号索引（用于位置/槽位标识）。</param>
        /// <param name="name">Feeder 的显示名称。</param>
        /// <param name="ip">Feeder 的网络 IP 地址或主机名。</param>
        /// <param name="port">Feeder 的网络端口号。</param>
        /// <param name="feederBrand">Feeder 的品牌枚举，用于创建特定实现。</param>
        /// <returns>是否成功创建并注册 Feeder。</returns>
        bool CreateFeeder(Guid id, int feederNo, string name, string ip, int port, FeederBrand feederBrand);

        /// <summary>
        /// 获取已注册的 Feeder（通过 id）。若未找到，可抛出或返回 null（由实现决定）。
        /// </summary>
        /// <param name="id">要获取的 Feeder 的唯一标识符。</param>
        /// <returns>对应的 <see cref="IVoiceCoilMotorFeeder"/> 实例。</returns>
        IVoiceCoilMotorFeeder GetFeeder(Guid id);

        /// <summary>
        /// 异步获取已注册的 Feeder（通过 id）。
        /// </summary>
        /// <param name="id">要获取的 Feeder 的唯一标识符。</param>
        /// <returns>一个任务，任务结果为对应的 <see cref="IVoiceCoilMotorFeeder"/> 实例。</returns>
        Task<IVoiceCoilMotorFeeder> GetFeederAsync(Guid id);

        /// <summary>
        /// 通过 Feeder 编号（index）获取 Feeder。
        /// </summary>
        /// <param name="feederNo">Feeder 的编号索引。</param>
        /// <returns>对应的 <see cref="IVoiceCoilMotorFeeder"/> 实例，若不存在返回 null（由实现决定）。</returns>
        IVoiceCoilMotorFeeder GetFeederByIndex(int feederNo);

        /// <summary>
        /// 异步通过 Feeder 编号（index）获取 Feeder。
        /// </summary>
        /// <param name="feederNo">Feeder 的编号索引。</param>
        /// <returns>一个任务，任务结果为对应的 <see cref="IVoiceCoilMotorFeeder"/> 实例。</returns>
        Task<IVoiceCoilMotorFeeder> GetFeederByIndexAsync(int feederNo);

        /// <summary>
        /// 注销并移除 Feeder（通过 id）。调用后应释放与该 Feeder 相关的所有资源并从管理集合中移除。
        /// </summary>
        /// <param name="id">要注销的 Feeder 的唯一标识符。</param>
        Task UnRegisterFeederAsync(Guid id);

        /// <summary>
        /// 同步注销并移除 Feeder（通过 id）。调用后应释放与该 Feeder 相关的所有资源并从管理集合中移除。
        /// </summary>
        /// <param name="id">要注销的 Feeder 的唯一标识符。</param>
        void UnRegisterFeeder(Guid id);

        /// <summary>
        /// 注销并移除 Feeder（通过 index）。调用后应释放与该 Feeder 相关的所有资源并从管理集合中移除。
        /// </summary>
        /// <param name="feederNo">要注销的 Feeder 的编号索引。</param>
        Task UnRegisterFeederByIndexAsync(int feederNo);

        /// <summary>
        /// 同步注销并移除 Feeder（通过 index）。
        /// </summary>
        /// <param name="feederNo">要注销的 Feeder 的编号索引。</param>
        void UnRegisterFeederByIndex(int feederNo);

        /// <summary>
        /// 获取所有已注册的 Feeder 的只读集合快照。
        /// 返回的集合不应允许外部修改管理内部状态。
        /// </summary>
        /// <returns>只读集合，包含当前所有已注册的 Feeder 实例。</returns>
        IReadOnlyCollection<IVoiceCoilMotorFeeder> GetAllFeeders();

        /// <summary>
        /// 异步获取所有已注册的 Feeder 的只读集合快照。
        /// </summary>
        /// <returns>一个任务，任务结果为只读集合，包含当前所有已注册的 Feeder 实例。</returns>
        Task<IReadOnlyCollection<IVoiceCoilMotorFeeder>> GetAllFeedersAsync();

        /// <summary>
        /// 尝试通过 id 获取 Feeder，避免抛出异常的安全访问方式。
        /// </summary>
        /// <param name="id">要查找的 Feeder 的唯一标识符。</param>
        /// <param name="feeder">如果找到则输出对应的 Feeder 实例；否则为 null。</param>
        /// <returns>如果找到则返回 true，否则返回 false。</returns>
        bool TryGetFeeder(Guid id, out IVoiceCoilMotorFeeder feeder);

        /// <summary>
        /// 异步尝试通过 id 获取 Feeder，返回一个包含查找结果的元组。
        /// </summary>
        /// <param name="id">要查找的 Feeder 的唯一标识符。</param>
        /// <returns>一个任务，任务结果为 (found, feeder)，found 表示是否找到，feeder 为对应实例或 null。</returns>
        Task<(bool found, IVoiceCoilMotorFeeder feeder)> TryGetFeederAsync(Guid id);

        /// <summary>
        /// 检查 Feeder 是否存在（通过 id）。
        /// </summary>
        /// <param name="id">要检查的 Feeder 的唯一标识符。</param>
        /// <returns>存在则返回 true，否则返回 false。</returns>
        bool ContainsFeeder(Guid id);

        /// <summary>
        /// 异步检查 Feeder 是否存在（通过 id）。
        /// </summary>
        /// <param name="id">要检查的 Feeder 的唯一标识符。</param>
        /// <returns>一个任务，任务结果为是否存在。</returns>
        Task<bool> ContainsFeederAsync(Guid id);

        /// <summary>
        /// 移除 Feeder（通过 id）并释放资源，返回是否成功移除。
        /// 如果 Feeder 不存在则返回 false。
        /// </summary>
        /// <param name="id">要移除的 Feeder 的唯一标识符。</param>
        /// <returns>是否成功移除并释放资源。</returns>
        bool RemoveFeeder(Guid id);

        /// <summary>
        /// 异步移除 Feeder（通过 id）并释放资源，返回是否成功移除。
        /// </summary>
        /// <param name="id">要移除的 Feeder 的唯一标识符。</param>
        /// <returns>一个任务，任务结果为是否成功移除并释放资源。</returns>
        Task<bool> RemoveFeederAsync(Guid id);

        /// <summary>
        /// 移除并释放所有已注册的 Feeder。调用后管理集合应为空。
        /// 实现应确保对每个 Feeder 的资源正确释放且保持原子性或可恢复性。
        /// </summary>
        void RemoveAllFeeders();

        /// <summary>
        /// 更新Feeder编号
        /// </summary>
        /// <param name="id"></param>
        /// <param name="newFeederNo"></param>
        void UpdateFeederNo(Guid id, int newFeederNo);
    }
}