Display_D_HP/TeamAAS-VM/Interfaces/IScannerService.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using TeamAAS_VP.Models;
using TeamAAS_VP.Models.Scanner;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 提供扫码枪生命周期管理的接口，包括创建、获取及注销扫码枪实例。
    /// </summary>
    public interface IScannerService
    {
        /// <summary>
        /// 异步创建并注册一个扫码枪实例。
        /// </summary>
        /// <param name="id">要创建扫码枪的唯一标识（GUID）。</param>
        /// <param name="scannerInfo">用于初始化扫码枪的信息对象，不能为空。</param>
        /// <returns>
        /// 返回一个 <see cref="Task{Boolean}"/>；任务完成时布尔值指示创建是否成功。
        /// </returns>
        /// <exception cref="ArgumentNullException">当 <paramref name="scannerInfo"/> 为 null 时抛出。</exception>
        Task<bool> CreateScannerAsync(Guid id, ScannerInfo scannerInfo);

        /// <summary>
        /// 同步创建并注册一个扫码枪实例。
        /// </summary>
        /// <param name="id">要创建扫码枪的唯一标识（GUID）。</param>
        /// <param name="scannerInfo">用于初始化扫码枪的信息对象，不能为空。</param>
        /// <returns>返回布尔值，指示创建是否成功。</returns>
        /// <exception cref="ArgumentNullException">当 <paramref name="scannerInfo"/> 为 null 时抛出。</exception>
        bool CreateScanner(Guid id, ScannerInfo scannerInfo);

        /// <summary>
        /// 获取已注册的扫码枪实例（同步）。通过 GUID 查找。
        /// </summary>
        /// <param name="id">要获取的扫码枪唯一标识（GUID）。</param>
        /// <returns>
        /// 已注册的 <see cref="IScanner"/> 实例；如果未找到对应扫码枪，返回 null（或实现可选择抛出异常）。
        /// </returns>
        IScanner GetScanner(Guid id);
        /// <summary>
        /// 异步获取已注册的扫码枪实例。通过 GUID 查找。
        /// </summary>
        /// <param name="id">要获取的扫码枪唯一标识（GUID）。</param>
        /// <returns>
        /// 一个任务，完成时返回对应的 <see cref="IScanner"/> 实例；若未找到可返回 null。
        /// </returns>
        Task<IScanner> GetScannerAsync(Guid id);
        /// <summary>
        /// 获取所有已注册的扫码枪实例（同步）。
        /// </summary>
        /// <returns></returns>
        IReadOnlyCollection<IScanner> GetAllScanners();

        /// <summary>
        /// 获取所有已注册的扫码枪实例（异步）。
        /// </summary>
        /// <returns></returns>
        Task<IReadOnlyCollection<IScanner>> GetAllScannersAsync();
     

        /// <summary>
        /// 尝试获取已注册的扫码枪实例（同步）。通过 GUID 查找。
        /// </summary>
        /// <param name="id"></param>
        /// <param name="scanner"></param>
        /// <returns></returns>
        bool TryGetScanner(Guid id, out IScanner scanner);

        /// <summary>
        /// 尝试获取已注册的扫码枪实例（异步）。通过 GUID 查找。
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        Task<(bool found, IScanner scanner)> TryGetScannerAsync(Guid id);
        /// <summary>
        /// 检查扫码枪是否已注册（同步）。通过 GUID 检查。
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        bool ContainsScanner(Guid id);
        /// <summary>
        /// 检查扫码枪是否已注册（异步）。通过 GUID 检查。
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        Task<bool> ContainsScannerAsync(Guid id);
        /// <summary>
        /// 移除已注册的扫码枪实例（同步）。通过 GUID 移除。
        /// </summary>
        /// <param name="id"></param>
        /// <returns>返回是否成功移除</returns>
        bool RemoveScanner(Guid id);
        /// <summary>
        /// 移除已注册的扫码枪实例（异步）。通过 GUID 移除。
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        Task<bool> RemoveScannerAsync(Guid id);
        /// <summary>
        /// 异步注销并移除指定的扫码枪注册信息。通过 GUID 注销。
        /// </summary>
        /// <param name="id">要注销的扫码枪唯一标识（GUID）。</param>
        /// <returns>表示注销操作完成的任务。</returns>
        Task UnRegisterScannerAsync(Guid id);

        /// <summary>
        /// 同步注销并移除指定的扫码枪注册信息。通过 GUID 注销。
        /// </summary>
        /// <param name="id">要注销的扫码枪唯一标识（GUID）。</param>
        void UnRegisterScanner(Guid id);

        /// <summary>
        /// 获取已注册的扫码枪实例（同步）。通过扫码枪编号（int）查找。
        /// </summary>
        /// <param name="number">扫码枪编号（整型）。</param>
        /// <returns>
        /// 已注册的 <see cref="IScanner"/> 实例；如果未找到对应扫码枪，返回 null（或实现可选择抛出异常）。
        /// </returns>
        IScanner GetScannerByNumber(int number);

        /// <summary>
        /// 异步获取已注册的扫码枪实例。通过扫码枪编号（int）查找。
        /// </summary>
        /// <param name="number">扫码枪编号（整型）。</param>
        /// <returns>
        /// 一个任务，完成时返回对应的 <see cref="IScanner"/> 实例；若未找到可返回 null。
        /// </returns>
        Task<IScanner> GetScannerByNumberAsync(int number);
        /// <summary>
        /// 异步注销并移除指定的扫码枪注册信息。通过扫码枪编号（int）注销。
        /// </summary>
        /// <param name="number">要注销的扫码枪编号（整型）。</param>
        /// <returns>表示注销操作完成的任务。</returns>
        Task UnRegisterScannerByNumberAsync(int number);

        /// <summary>
        /// 同步注销并移除指定的扫码枪注册信息。通过扫码枪编号（int）注销。
        /// </summary>
        /// <param name="number">要注销的扫码枪编号（整型）。</param>
        void UnRegisterScannerByNumber(int number);

        /// <summary>
        /// 移除所有扫码枪
        /// </summary>
        void RemoveAllScanners();

        /// <summary>
        /// 初始化所有扫码枪
        /// </summary>
        /// <param name="scanners"></param>
        /// <returns></returns>
        (bool IsSucceed, string Message) InitializeAllScanners(ScannerInfo[] scanners);

        /// <summary>
        /// 初始化所有扫码枪 （异步）
        /// </summary>
        /// <param name="scanners"></param>
        Task<(bool IsSucceed, string Message)> InitializeAllScannersAsync(ScannerInfo[] scanners);

        /// <summary>
        /// 更新扫码枪编号
        /// </summary>
        /// <param name="id"></param>
        /// <param name="newNumber"></param>
        void UpdateScannerNumber(Guid id, int newNumber);
    }
}